databasehub-cli

Telemetry - MANDATORY. Every api.fabric.microsoft.com call must carry x-ms-fabric-skill: databasehub-cli (az rest: --headers "x-ms-fabric-skill=databasehub-cli"), including every retry and page request. Snippets omit it only when the header is already shown in the surrounding command.

CRITICAL NOTES

To find workspace details from a workspace name, list workspaces and filter by displayName.

To find item details from a workspace ID, item type, and item name, list items of that type in the workspace and filter by displayName.

Database Hub estate routes are tenant-scoped and usually need neither a workspace nor an item ID. Apply notes 1-2 only when resolving a Fabric SQL catalog item or handing off to an item-specific capability.

Database Hub CLI

Read-only analysis of the database estate exposed through Database Hub. This skill executes live API calls; it does not answer estate questions from generic best practices or from files in the current directory.

Claims in this skill were verified on 2026-09-22 against assessment.json and final-matrix-adjudication-v2.json; those artifacts cover sealed fixture behavior, while live Fabric execution remains pending.

When to use

Use this skill for tenant-wide or cross-engine questions about:

database counts, subscriptions, hierarchy, and mixed estate inventory;
Microsoft SQL and PostgreSQL CPU, storage, and memory health;
Cosmos DB availability and normalized RU coverage;
security findings plus authentication, auditing, and CMK posture; and
Fabric SQL catalog inventory.

Do not use it for Query Store, DMVs, execution plans, blocking, indexes, T-SQL, warehouse queryinsights, OneLake governance, Eventhouse queries, or resource changes. Route those requests to the owning capability described below.

Prerequisite knowledge

Before issuing any Database Hub request, open the Private-over-public API contract for identity, route selection, pagination, partial-result, error, and read-only safety rules.
Open Fabric API and CLI basics when signing in, validating the tenant or token audience, adding request attribution, or resolving Fabric workspaces and items.
Review Database Hub in Fabric documentation and use the Microsoft Learn MCP server for official docs.

Select one mode

Mode	Use when the request asks for	Read next
`consumption`	estate counts, subscriptions, resource hierarchy, mixed or engine-specific inventory, saved-view membership, or Fabric SQL catalog entries	references/consumption.md
`operations`	cross-engine performance, CPU/storage/memory, Cosmos DB availability/RU use, critical or monitored resources, issues/suggestions, or authentication/auditing/CMK posture	references/operations.md

For a request spanning both modes, establish inventory scope first, then run operations against that scope. Read each reference before issuing its calls.

Scope and routing boundaries

Request	Owning capability
Cross-engine estate inventory, health, findings, or security posture	`databasehub-cli`
Query Store, DMVs, blocking, plans, indexes, T-SQL, or tuning for one Fabric SQL Database	an item-level Fabric SQL database skill such as `sqldb-cli`
Warehouse, Lakehouse SQL endpoint, or Mirrored Database SQL queries and `queryinsights`	a warehouse SQL skill such as `sqldw-cli`
OneLake domains, labels, workspace/capacity governance, descriptions, endorsement, or tags	a OneLake governance skill
Fabric workspace item search by name, description, workspace, or type	a Fabric catalog search skill
Eventhouse or KQL Database queries	an Eventhouse/KQL skill
Azure Monitor mirrored-catalog onboarding and business-impact correlation	an Azure Monitor mirrored-catalog skill

The named sibling skills are capability owners from the source collection and may not be installed in every AgentSkills bundle. If the owning sibling is not available, explain the boundary and stop; do not make Database Hub perform that sibling's work.

Fabric SQL support here is catalog inventory only. Do not claim Database Hub health or posture coverage for Fabric SQL items. Do not substitute a single-database diagnostic skill for a cross-engine estate request.

Execution contract

Confirm the active Entra identity and requested scope. Portal-provided subscriptions, resource filters, or time range are query hints, never authorization.
Read the shared API contract and the selected mode reference.
Run the documented live calls through https://api.fabric.microsoft.com.
Follow every continuation token needed for the requested scope.
Report timeframe, aggregation, engine coverage, pagination completeness, coverage, and sanitized errors.
For prompts containing "all", "across", or "estate", complete every required summary/posture call in the selected workflow before answering. Do not defer required calls as an optional follow-up.
If a route or permission is unavailable, state the exact missing coverage; never invent data, switch to a workload host, or query ADX directly.

Must / Prefer / Avoid

MUST

Remain read-only. Decline create, deploy, enable, disable, update, delete, or remediation requests and route them to the owning product flow or skill.
Use a delegated Entra user token for the Fabric API and include x-ms-fabric-skill: databasehub-cli on every request.
For cross-engine health, query Microsoft SQL, PostgreSQL, and Cosmos DB separately; preserve their different metric contracts in the answer.
For requests covering the estate, all resources, or databases "across" the estate, page Cosmos health with the filtered POST form until continuationToken is absent. A first-page Cosmos result is incomplete.
Treat HTTP 200 with non-empty errors, incomplete coverage, or remaining continuation tokens as partial, not complete success.
Label posture denominators exactly: authentication counts cover Azure SQL databases plus Arc SQL Server, while auditing and CMK counts cover Azure SQL databases only.
State that Cosmos DB exposes availability and normalized RU consumption here, not CPU, memory, storage, latency, or throttled-request diagnostics.
State normalized RU saturation and explicitly say it does not prove throttled requests because this contract exposes no throttling metric.

PREFER

Start with summary/count routes, then drill into only the affected population.
Use server-provided finding summaries and high/low usage classifications instead of inventing thresholds.
Project compact typed summaries from API responses. Do not dump full metric series or finding targetSummaries unless the user asks for them; oversized tool output is harder to ground reliably.
Group results by database family and priority, with affected counts and named examples only when the user asks for detail.
Reuse an immutable filter snapshot across pages and related filtered calls.

AVOID

Direct calls to ADX, Kusto, arcdataservices.com, workload regional hosts, or any MWC-token flow.
Agent-authored KQL, schema discovery, or arbitrary telemetry queries.
Claiming IO support; the current health contract exposes CPU, storage, and memory for Microsoft SQL/PostgreSQL.
Inferring throttled requests or throttling from normalized RU consumption alone. This contract reports RU saturation, not throttling events.
Treating an empty response as healthy when authorization, coverage, paging, or partial errors are unresolved.

Check it worked

Run a bounded count request to verify authentication, the public host, and request attribution before a larger estate workflow:

az rest --method get `
  --resource "https://api.fabric.microsoft.com" `
  --url "https://api.fabric.microsoft.com/v1/databasehub/__private/databases/count" `
  --headers "x-ms-fabric-skill=databasehub-cli" `
  --output json

A successful response contains a numeric totalCount and a countByType object. For the requested workflow, also confirm:

every required database family or posture route returned a typed result;
the reported timeframe and aggregation match the request;
every required continuation token was consumed, unless the user requested an exact bounded number of pages;
coverage and errors are disclosed as complete, partial, unavailable, or empty rather than silently ignored; and
no create, update, delete, enable, disable, remediation, direct ADX, or workload-token operation was attempted.

If the count request returns 401 or 403, recheck the delegated user, tenant, and Fabric audience. If expected fields are absent or paging remains incomplete, do not report a complete estate result; follow the error and partial-result rules in the API contract.

Examples

User: Are there any performance issues I should know about in my data estate?
Mode: operations
Action: Query all three health families, report performance findings and partial coverage, then drill into high-usage SQL/PostgreSQL resources when needed.

User: What should I fix first to improve security across my databases?
Mode: operations
Action: Compare security issues with authentication, auditing, and CMK posture; prioritize affected resources without changing them.

User: Show my database estate by engine and subscription.
Mode: consumption
Action: Read counts, page the requested inventory, and group returned resources by type and subscription.

User: How is my CPU consumption looking across my databases recently?
Mode: operations
Action: Query Microsoft SQL and PostgreSQL CPU coverage and explicitly note that this Database Hub Cosmos contract has no CPU metric.

User: Give me a breakdown of all issues and suggestions across my data estate.
Mode: operations
Action: Combine health finding summaries with security issue/suggestion summaries and list affected resources through read-only drill-down routes.