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 LRO poll, fabric_lro and retry. Snippets omit it — add it anyway.

CRITICAL NOTES

1. To find the workspace details (including its ID) from workspace name: list all workspaces and, then, use JMESPath filtering
2. To find the item details (including its ID) from workspace ID, item type, and item name: list all items of that type in that workspace and, then, use JMESPath filtering
3. 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 skill.

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.

Prerequisite knowledge

• Private-over-public API contract — required authentication, transport, pagination, partial-result, error, and route-safety rules.
• Health drill-downs and filtered snapshots — required for named SQL/PostgreSQL resources, per-resource SQL metrics, and filtered health comparisons.
• Fabric authentication and CLI patterns
• Fabric REST API concepts
• Databases in Fabric documentation

Select one mode

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

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

1. Confirm the active Entra identity and requested scope. Portal-provided subscriptions, resource filters, or time range are query hints, never authorization.
2. Before the first Database Hub call, read references/private-over-public-api.md and the selected mode reference. For named-resource or filtered health drill-downs, read references/health-drilldowns.md in addition to operations.md, not instead of it.
3. Run the documented live calls through https://api.fabric.microsoft.com.
4. Follow every continuation token needed for the requested scope.
5. Report timeframe, aggregation, engine coverage, pagination completeness, coverage, and sanitized errors.
6. For prompts containing "all", "across", or "estate", complete every required summary/posture call in the selected workflow before answering. Attempt independent required calls even when another route fails; collect each route's error instead of short-circuiting the workflow. Only a page that depends on a failed prior page/token may be skipped. Do not defer required calls as an optional follow-up.
7. 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.
• Emit SQL and PostgreSQL health summaries only through the compact Select-Object projection in operations.md; never print raw summaries with their series arrays. A populated estate's raw summaries exceed the tool-output limit, and answering from partial file reads misattributes metrics.
• For general cross-engine health/performance that includes Cosmos availability or RU, query Microsoft SQL, PostgreSQL, and Cosmos DB separately; preserve their different metric contracts in the answer. For a CPU-only request, query SQL and PostgreSQL and state that Cosmos CPU is not exposed by this contract.
• For general cross-engine health/performance requests that include Cosmos availability/RU, and for all-findings requests, page Cosmos health with the filtered POST form until continuationToken is absent. A first-page Cosmos result is incomplete. Do not call Cosmos health for inventory-only or CPU-only requests.
• In every Cosmos health answer, label processedAccounts and totalAccounts separately even when they are equal; do not compress them into one unlabeled account count. When they differ, literally label coverage partial or inconsistent. When totalAccounts is 0, report totalAccounts: 0, say there are no Cosmos DB accounts in scope and therefore no availability or normalized RU data, and do not call Cosmos healthy.
• For CPU-only requests, report CPU evidence only. Do not add storage or memory counts merely because the summary response also contains them.
• 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. Repeat the literal scope on each posture line: "Azure SQL + Arc SQL Server" for authentication and "Azure SQL only" for both auditing and CMK.
• For "all issues and suggestions" output, report both totalFindingCount and totalAffectedResourceCount for every returned database family. Do not substitute affected-resource counts for finding totals.
• 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. Do not rephrase saturation as a confirmed, likely, or potential throttling risk.

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.

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.