Sqldb CLI

MicrosoftOfficialPublished by Microsoft

Skill
Tool integration
Software development
MIT
No issues found

From the author

Manages a Fabric SQL database item, the OLTP SQL Server engine, including running T-SQL through sqlcmd, temporal and vector similarity search, schema and sys.tables inspection, dacpac deployment, and Query Store, blocked sessions and regressed-plan investigation. Use for any query or change against a SQL database item. Warehouse, lakehouse SQL endpoint and mirrored items belong to sqldw-cli.

— the description by Microsoft

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The sqldb-cli skill provides a structured interface for interacting with Fabric SQL database items (OLTP SQL Server engine). It operates as a mode-based dispatcher, requiring users to select between authoring, consumption, or operations modes. Each mode is supported by specific reference documentation that must be consulted before executing commands. The skill facilitates tasks ranging from schema creation and DML operations to read-only data querying and performance troubleshooting using tools like sqlcmd and az CLI.

What it does

Executes T-SQL commands for DDL and DML operations.
Supports schema inspection and database item management.
Enables performance diagnostics including Query Store and blocked session analysis.
Facilitates dacpac deployments for schema management.
Provides read-only access for data exploration and vector similarity searches.
Manages lifecycle tasks like creating new SQL database items.

When to use it

When you need to create or modify schema, tables, or constraints in a Fabric SQL database.
When performing read-only queries or catalog exploration.
When investigating performance issues such as slow queries or regressed plans.
When deploying database schemas using dacpac files.
When working with vector columns or temporal data within the SQL database.

Advantages

Provides a clear, mode-based structure to prevent accidental data modification.
Integrates directly with standard tools like sqlcmd and az CLI.
Ensures consistent telemetry and authentication practices across all operations.
Separates concerns between authoring, consumption, and operational diagnostics.

Usage examples

“Create a new table named Orders in my Fabric SQL database.”: The agent switches to authoring mode, reads the authoring reference, and executes the necessary CREATE TABLE T-SQL statement via sqlcmd.
“Show me the current blocked sessions in the SQL database.”: The agent switches to operations mode, reads the operations reference, and executes the appropriate diagnostic queries to report blocked sessions.
“Query the top 10 rows from the Customers table.”: The agent switches to consumption mode, reads the consumption reference, and executes a SELECT statement via sqlcmd to return the requested data.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/microsoft/sqldb-cli/download
Unzip it into the cross-client skills folder of your project:
```
mkdir -p .agents/skills && unzip sqldb-cli.zip -d .agents/skills
```

Documentation by Microsoft

Telemetry — MANDATORY. Every api.fabric.microsoft.com call must carry x-ms-fabric-skill: sqldb-cli (az rest: --headers "x-ms-fabric-skill=sqldb-cli"), including every LRO poll, fabric_lro and retry. Snippets omit it — add it anyway.

CRITICAL NOTES
To find the workspace details (including its ID) from workspace name: list all workspaces and, then, use JMESPath filtering
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
Skill disambiguation: use sqldb-cli ONLY for a Fabric SQL database item (the OLTP, SQL Server engine). A Warehouse, a Lakehouse SQL endpoint or a Mirrored Database is sqldw-cli; a notebook cell is spark-cli.

Fabric SQL Database (OLTP) -- CLI Skill

This one skill owns Fabric SQL database: T-SQL schema authoring, read-only querying, and OLTP performance diagnostics.

It is a mode dispatcher and contains NO procedures. Pick the mode that matches the request from the table below, then read the matching references/<mode>.md file end to end with your file-reading tool BEFORE issuing a single command. That file holds the endpoints, payload shapes, templates and gotchas; acting without it produces wrong payloads and wrong results.

Mode selection

Mode	Use when the request ...	Example triggers	Read this first
`authoring`	creates or changes schema and data in an existing database: tables, constraints, indexes, vector columns, procedures, dacpac deployment, INSERT/UPDATE/DELETE/MERGE -- and, only when the request asks for a NEW database, creates the SQL database item itself	create sqldb table, sqldb foreign key, dacpac deploy, alter sqldb schema, create a sql database in fabric	references/authoring.md
`consumption`	runs read-only T-SQL through sqlcmd: SELECT, catalog exploration, vector similarity search, temporal queries	sqldb sys.tables, vector similarity sqldb, temporal sqldb, query the sql database	references/consumption.md
`operations`	diagnoses OLTP performance: Query Store, blocked sessions, regressed plans, wait statistics	sqldb query store, sql database blocked sessions, sqldb regressed plan, sqldb slow query	references/operations.md

Mode boundary rule

consumption issues read-only T-SQL only. Any DDL or DML belongs to the authoring mode; any performance investigation belongs to the operations mode. Announce the switch, read the matching reference, then act.

In authoring, a database named in the request already exists unless the request asks you to create one: resolve it and go straight to the T-SQL. Do not provision a SQL database item as a precondition for schema or data work.

If a request genuinely spans modes, handle them one at a time and read each reference before you start that part. If the mode is ambiguous after reading this table, ask one short clarifying question instead of guessing.

Terminal write -- the step you must not skip

Reading the reference and planning the change is NOT completing the task. Each mutating mode ends with one state-changing call. If you did not issue it, nothing was persisted -- say so explicitly rather than reporting success.

Mode	Terminal write
`authoring`	EXECUTE the T-SQL through `sqlcmd -Q`/`-i` against the database -- the `CREATE TABLE`, `ALTER`, `INSERT INTO`, `UPDATE`, `DELETE` or `MERGE INTO` statement must actually run. Composing DDL or DML and showing it to the user changes nothing. Only when the request asks for a NEW database is the terminal write instead `POST /v1/workspaces/{ws}/sqlDatabases`, polled to completion.
`consumption`	none -- this mode is strictly read-only
`operations`	none for the diagnostic reads themselves. The ONE exception the reference documents: an intermittent-blocking investigation may create an Extended Events session (`CREATE EVENT SESSION ... ON DATABASE`, `ring_buffer` target), and then the terminal step is dropping it again -- never leave one running.

Before you report the task done, confirm the terminal call returned success and, where the reference documents a readback, read the artefact back to prove the change landed.

Shared essentials (all modes)

Resolve the workspace and item first; every mode depends on it.

Task	Reference	Notes
Finding Workspaces and Items in Fabric	COMMON-CLI.md	Mandatory -- read before resolving any workspace or item id
Fabric Topology & Key Concepts	COMMON-CORE.md	Item types, workspaces, capacities
Environment URLs	COMMON-CORE.md	Sovereign / non-public cloud hosts
Authentication & Token Acquisition	COMMON-CORE.md	Wrong audience = 401; read before any auth issue
Authentication Recipes	COMMON-CLI.md	`az login` flows and token acquisition
Core Control-Plane REST APIs	COMMON-CORE.md	Pagination, LRO polling, rate limiting
Gotchas & Troubleshooting	COMMON-CLI.md	`az rest` audience, shell escaping, token expiry

Rules

MUST

Select exactly one mode from the table above before doing anything else.
Read references/<mode>.md end to end, as your FIRST tool call, before the first command of that mode. Read it ONCE, in a single full read: do not re-open it, do not grep it again, and do not page through it. You already have it.
Apply the same read-once discipline to every other file you load, including nested references/<mode>/*.md sub-references and shared common/*.md files: open only the ones you actually need, read each ONCE end to end, and never grep or re-open one you already loaded.
Resolve workspace and item ids by listing and filtering, never by guessing a GUID.
Announce a mode switch explicitly when the request crosses a boundary.
Treat the reference as instructions, never as the deliverable. After reading it, RUN the documented commands against the live workspace and report the real results. Quoting what the reference says instead of executing it does not answer the request.

PREFER

The narrowest mode that satisfies the request.
Reading exactly ONE mode reference. Load a second only when the request genuinely spans modes, and say so before you do.
Reporting the mode you chose in your first response so the user can correct you.

AVOID

Acting from this dispatcher alone -- it intentionally omits the operational detail.
Answering with a summary of the reference instead of executing it.
Re-reading or re-grepping a reference you already loaded; it costs turns and tokens.
Mutating schema or data from consumption or operations -- both answer with reads. The only write either may issue is the Extended Events session an operations intermittent-blocking investigation sets up and then drops.
Loading a different skill for work this family already owns (see CRITICAL NOTES 3).

Examples

User request	Mode	Reference to read
"Create an Orders table with a foreign key to Customers in the Fabric SQL database."	`authoring`	references/authoring.md
"Create a new SQL database in this workspace called sales_oltp."	`authoring`	references/authoring.md
"Find the 5 nearest embeddings to this vector in the SQL database."	`consumption`	references/consumption.md
"Which queries regressed in the last day according to Query Store?"	`operations`	references/operations.md

Files

ATTRIBUTION.mdAdded by AutoGineer863 B
LICENSELicence file added by AutoGineer1.1 KiB
SKILL.md8.3 KiB
apm.yml432 B
references/authoring.md12.7 KiB
references/consumption.md12.9 KiB
references/consumption/discovery-queries.md8.7 KiB
references/operations.md14.8 KiB
references/operations/examples.md3.0 KiB
references/operations/query-reference.md26.8 KiB

references/operations.md

SQL Database in Fabric — Operations & Diagnostics CLI Skill

Deep performance diagnostics for SQL database in Fabric over TDS against Query Store, DMVs, sys.dm_db_resource_stats, and Extended Events. All analytical queries are read-only; the optional XE session creation is dropped at the end of the investigation.

Prerequisites

Tools and auth: see COMMON-CLI.md § Authentication Recipes and § SQL / TDS Data-Plane Access.
Permissions: VIEW DATABASE STATE for DMVs; ALTER ANY EVENT SESSION to create XE sessions.
Connect to the SQL database (OLTP) endpoint — the SQL analytics endpoint has no Query Store/DMVs.

Topic	Reference
Finding Workspaces and Items in Fabric	COMMON-CLI.md § Finding Workspaces and Items in Fabric — read first
SQL / TDS Data-Plane Access (sqlcmd, auth)	COMMON-CLI.md § SQL / TDS Data-Plane Access
CLI Gotchas (audience, escaping, expiry)	COMMON-CLI.md § Gotchas & Troubleshooting
Endpoint Selection (use OLTP)	SQLDB-CONSUMPTION-CORE.md § Endpoint Selection
Performance and Monitoring foundations	SQLDB-CONSUMPTION-CORE.md § Performance and Monitoring
Limitations Reference (unsupported features, DMVs)	SQLDB-AUTHORING-CORE.md § Limitations Reference
Mirroring Considerations	SQLDB-AUTHORING-CORE.md § Mirroring Considerations
All diagnostic T-SQL	references/query-reference.md
Investigation Workflows	Investigation Workflows (in this file)
Examples	references/examples.md

For Fabric topology, capacity, and platform auth basics see COMMON-CORE.md.

Connection

Diagnostics run against the SQL database (OLTP) endpoint. For endpoint discovery, authentication, and already-installed sqlcmd connection guidance, use the shared CLI instructions in COMMON-CLI.md rather than inline setup here. Do not follow its tool-install steps during an investigation.

Use an already-installed sqlcmd first and make at most one connection attempt with it. If it is absent or its Entra authentication mode fails, do not install or upgrade tooling during the investigation. When the current PowerShell runtime already exposes System.Data.SqlClient.SqlConnection (commonly Windows PowerShell 5.1), make at most one fallback connection attempt with that provider, using an access token for https://database.windows.net/, and run the same read-only T-SQL. If the provider is unavailable, report that no compatible preinstalled TDS client is available. If its connection fails, surface that error. In either case, stop rather than installing tooling.

Once connected, use the diagnostic workflows below and the full T-SQL catalog in query-reference.md.

Diagnostic Areas

All SQL is in query-reference.md. Step-by-step orchestration in Investigation Workflows below.

Performance Investigation

Volatile Query Detection (SQL) — CV% > 100 = blocking, plan regression, or parameter sniffing. First step for intermittent slowness.
Wait Category Analysis (SQL) — Lock vs CPU vs IO vs Memory; follow Root Cause Decision Tree.
Top Resource Consumers (SQL) — by duration / IO / CPU.
Recently Regressed Queries (SQL) — last hour vs prior 24h.
Multi-Plan Queries (SQL) — sys.sp_query_store_force_plan is supported but use sparingly; auto-tuning may correct over time.

Pressure Diagnostics

CPU Pressure (SQL) — avg_cpu_percent ≥ 80 over 10 min = sustained; non_cpu_to_cpu_ratio > 5 = waiting on resources, not CPU-bound.
IO Pressure (SQL) — avg_data_io_percent ≥ 80 (data); avg_log_write_percent ≥ 80 (log, often un-batched DML).
Resource Trend (SQL) — sys.dm_db_resource_stats retains only 1 hour of 15-second samples; persist or use Query Store for longer windows.

Blocking Diagnostics

Optimized locking is on by default — no traditional lock escalation. Most blocking comes from long-running transactions, app-side held transactions, or hot-row contention.

Live Blocking (SQL) — blocked sessions, head blocker, chain. If head blocker is idle with open_transaction_count > 0 → application is holding an open transaction; fix client code.
Intermittent Blocking (SQL) — XE session create / read / clean-up. ON DATABASE only (not ON SERVER); use ring_buffer target. Always clean up.

Index and Statistics Health

Auto-Tuning (SQL) — always check first; engine auto-creates/drops indexes.
DMV Missing Index (SQL) — only if auto-tuning has nothing pending. Rank by index_advantage = user_seeks * avg_total_user_cost * (avg_user_impact * 0.01). DMV stats reset on restart.
Statistics Staleness (SQL) — defaults: ≥ 100,000 rows and ≥ 10% modification.
Table Access Patterns (SQL) — hot tables for indexing/denormalization candidates.

Investigation Workflows

Step-by-step orchestration. Each step links to the corresponding query in query-reference.md.

Workflow 1: "Why is my SQL database in Fabric slow?"

Resource Usage Overview (last 30 min) — confirm pressure.
If sustained CPU/IO pressure → CPU Pressure or IO Pressure.
Volatile Query Detection.
Wait Category Analysis; follow the Root Cause Decision Tree.
If Lock-dominant → Workflow 3 (Blocking). If CPU/IO-dominant → Top Resource Consumers and Multi-Plan Queries.

Workflow 2: "Has performance degraded recently?"

Recently Regressed Queries (1h vs 24h).
For each regressed query → Multi-Plan Queries to detect plan changes.
Resource Usage Overview to check for new pressure.
Auto-Tuning Recommendations — recent recommendations may indicate workload shift.

Workflow 3: "Diagnose blocking"

Live Blocking (Blocked Sessions, Head Blocker, Chain).
If blocking found → inspect head blocker's open_transaction_count, SQL text, program_name.
If head blocker is idle with open_transaction_count > 0 → application bug; fix client code (uncommitted transaction).
If intermittent (no live rows) → Setup XE Session, wait, then Read XE Data and Clean Up.
Resolution patterns: reduce transaction scope; use RCSI for hot-row contention; check for missing indexes causing scans.

Workflow 4: "Should I add an index?"

Auto-Tuning Recommendations first.
If nothing pending → DMV Missing Index Recommendations.
For a specific table → Missing Indexes for a Specific Table.
Statistics Staleness Check — stale stats can produce false "missing index" symptoms.

Workflow 5: "Resource consumption baseline"

Resource Usage Overview (last 30 min).
Top Resource Consumers by CPU (last 24h).
Table Access Patterns — identify hot tables.

Full list of unsupported features: SQLDB-AUTHORING-CORE.md § Limitations Reference. Operations-critical items:

Do NOT Recommend	Why	Recommend Instead
Server-scoped DMVs (`sys.dm_os_*`, `sys.configurations`)	Not exposed	`sys.dm_db_resource_stats`, Query Store views
`EXECUTE AS` for security testing	Not supported	Connect as the actual user identity
`CREATE EVENT SESSION ... ON SERVER`, file-target XE	Database-scoped only	`... ON DATABASE` with `ring_buffer` target
Trace flags / `DBCC TRACEON`	Not supported	Re-architect query or use Query Store hints
Manual lock escalation tuning	Optimized locking eliminates escalation	Address root cause (long transactions, hot rows)
SQL analytics endpoint for diagnostics	DMVs/Query Store don't exist there	Connect to the SQL database (OLTP) endpoint
Aggressive `sp_query_store_force_plan`	Masks root cause	Fix stats / parameter sniffing first; force only as a stop-gap

Best Practices

For consumption foundations see SQLDB-CONSUMPTION-CORE.md § Performance and Monitoring.

Volatile detection first — narrows scope quickly for intermittent slowness.
Use the OLTP endpoint — the analytics endpoint has no Query Store/DMVs.
Trust auto-tuning — only override after a recommendation has been pending for a representative period.
Always clean up XE sessions at the end of an investigation.
Adjust DATEADD lookback windows to the user's investigation scope.
Persist sys.dm_db_resource_stats if you need > 1 hour of history.
High CV% over time → structural fix needed (RCSI, parameterization, index strategy), not plan forcing.

Gotchas, Rules, Troubleshooting

CLI/auth issues: COMMON-CLI.md § Gotchas. Platform issues: SQLDB-CONSUMPTION-CORE.md § Gotchas.

MUST DO

Check Constraints before recommending optimizations.
Connect to the SQL database (OLTP) endpoint — never analytics.
Run volatile detection first for intermittent slowness.
Check auto-tuning before suggesting manual indexes.
Clean up XE sessions when finished.
Report actual query output — do not fabricate.

PREFER

Start with high-level signals (resource trend, volatile detection) before drilling into individual queries.
Use the wait category decision tree to choose between blocking, CPU, IO, or memory paths.
Combine queries via the Investigation Workflows for end-to-end investigations.
Use -i file.sql for the XE session creation block (here-doc has portability quirks).
Use the SQL Database Performance Dashboard (Fabric portal) for visual context alongside CLI queries.
Set SET NOCOUNT ON; at the top of multi-statement scripts to keep CSV output clean.

AVOID

Recommending Fabric-unsupported features (CDC, Always Encrypted, in-memory, ledger, server-scoped DMVs, file-target XE).
Running diagnostics on the SQL analytics endpoint.
Installing or upgrading SQL client tools during an investigation.
Manually creating indexes without checking auto-tuning first.
Leaving XE sessions running after an investigation.
Forcing plans via sp_query_store_force_plan instead of fixing root cause.
Recommending lock-escalation tuning (optimized locking eliminates escalation).

Troubleshooting

Symptom	Cause	Fix
`Invalid object name 'sys.query_store_*'`	Querying analytics endpoint	Connect to OLTP endpoint
Volatile detection returns no rows	Lookback too short / no recent activity	Expand `DATEADD(MINUTE, -60, ...)` to `-1440`
`sys.dm_db_resource_stats` empty	Lookback exceeds 1-hour retention	Reduce window; or use Query Store
Permission error on DMVs	Missing `VIEW DATABASE STATE`	`GRANT VIEW DATABASE STATE TO [[email protected]]`
Permission error on `CREATE EVENT SESSION`	Missing `ALTER ANY EVENT SESSION`	`GRANT ALTER ANY EVENT SESSION TO [[email protected]]`
XE session captures nothing	LIKE filter too narrow / session in `STOP` state	Check `sys.dm_xe_database_sessions.state`; widen filter
Multi-plan query has no obvious bad plan	Parameter sniffing	`OPTION (RECOMPILE)` or `OPTIMIZE FOR` hint

Examples

See references/examples.md for full prompt/response patterns covering:

Diagnose intermittent slowness — volatile query detection → wait analysis
Diagnose live blocking — head blocker with idle open transaction
Recommend an index — auto-tuning check → DMV ranking → DDL suggestion

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by

Microsoft

Publisher

Microsoft (Official)

Source

microsoft/skills-for-fabric · skills/sqldb-cli · commit f8fac11

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

Also distributed in

microsoft/skills-for-fabric

AutoGineer is not affiliated with or endorsed by Microsoft.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download sqldb-cli.zip

From the author

AutoGineer summary

What it does

When to use it

Advantages

Usage examples

Install

Documentation by Microsoft

Fabric SQL Database (OLTP) -- CLI Skill

Mode selection

Mode boundary rule

Terminal write -- the step you must not skip

Shared essentials (all modes)

Rules

MUST

PREFER

AVOID

Examples

Files

references/operations.md

SQL Database in Fabric — Operations & Diagnostics CLI Skill

Prerequisites

Table of Contents

Connection

Diagnostic Areas

Performance Investigation

Pressure Diagnostics

Blocking Diagnostics

Index and Statistics Health

Investigation Workflows

Workflow 1: "Why is my SQL database in Fabric slow?"

Workflow 2: "Has performance degraded recently?"

Workflow 3: "Diagnose blocking"

Workflow 4: "Should I add an index?"

Workflow 5: "Resource consumption baseline"

Fabric SQL DB Constraints (NEVER recommend)

Best Practices

Gotchas, Rules, Troubleshooting

MUST DO

PREFER

AVOID

Troubleshooting

Examples

Requirements and compatibility

Security

Attribution and licence

Related skills

Implement Spec

MCP Builder

Schema

Postgresql Table Design

SQL Optimization Patterns

API Scaffolding Fastapi Pro

Download ZIP