Update Check — ONCE PER SESSION (mandatory) The first time this skill is used in a session, run the check-updates skill before proceeding.

• GitHub Copilot CLI / VS Code: invoke the

  check-updates

  skill.
• Claude Code / Cowork / Cursor / Windsurf / Codex: compare local vs remote package.json version.
• Skip if the check was already performed earlier in this session.

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

SQL Endpoint Authoring — CLI Skill

Table of Contents

storage.azure.com

az login

az rest

--resource

curl

curl

az rest

sqlcmd

az rest

az rest

nvarchar

datetime

money

queryinsights.*

sys.tables

sys.columns

sys.views

sys.stats

sqlcmd

sqlcmd

az

jq

Tool Stack

sqlcmd

winget install sqlcmd

brew install sqlcmd

apt-get install sqlcmd

az

az login

jq

az rest

Agent check — verify before first operation:

sqlcmd --version 2>/dev/null || echo "INSTALL: winget install sqlcmd OR brew install sqlcmd"

Authoring Scope by Item Type

Connection

Discover the SQL Endpoint FQDN

Per COMMON-CLI.md Discovering Connection Parameters via REST:

WS_ID="<workspaceId>"
ITEM_ID="<warehouseOrLakehouseId>"

# Warehouse
az rest --method get \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/warehouses/$ITEM_ID" \
  --query "properties.connectionString" --output tsv

# Lakehouse SQL endpoint
az rest --method get \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/lakehouses/$ITEM_ID" \
  --query "properties.sqlEndpointProperties.connectionString" --output tsv

Result:

<uniqueId>.datawarehouse.fabric.microsoft.com

Connect with sqlcmd (Go)

# Non-interactive one-shot query
sqlcmd -S "<endpoint>.datawarehouse.fabric.microsoft.com" -d "<DatabaseName>" -G \
  -Q "SELECT TOP 10 * FROM dbo.FactSales"

# Service principal (CI/CD)
SQLCMDPASSWORD="<clientSecret>" \
sqlcmd -S "<endpoint>.datawarehouse.fabric.microsoft.com" -d "<DatabaseName>" \
  --authentication-method ActiveDirectoryServicePrincipal \
  -U "<appId>" \
  -Q "SELECT COUNT(*) FROM dbo.FactSales"

Reusable Connection Variables

# Set once at script top
FABRIC_SERVER="<endpoint>.datawarehouse.fabric.microsoft.com"
FABRIC_DB="<DatabaseName>"
SQLCMD="sqlcmd -S $FABRIC_SERVER -d $FABRIC_DB -G"

# Use throughout
$SQLCMD -Q "SELECT TOP 5 * FROM dbo.DimProduct"
$SQLCMD -i myscript.sql

PowerShell / Windows CMD

$s = "<endpoint>.datawarehouse.fabric.microsoft.com"; $db = "<DatabaseName>"
sqlcmd -S $s -d $db -G -Q "SELECT TOP 10 * FROM dbo.FactSales"
# CMD: use set S=... and %S% / %DB% instead of $variables

Agentic Workflows

Schema Discovery Before Authoring

Before any write operation, discover the target schema:

# 1. List tables
$SQLCMD -Q "SELECT table_schema, table_name FROM information_schema.tables ORDER BY 1,2" -W

# 2. Check columns
$SQLCMD -Q "SELECT column_name, data_type, is_nullable FROM information_schema.columns WHERE table_name='FactSales' ORDER BY ordinal_position" -W

# 3. Sample data
$SQLCMD -Q "SELECT TOP 5 * FROM dbo.FactSales" -W

# 4. Check constraints
$SQLCMD -Q "SELECT constraint_name, constraint_type FROM information_schema.table_constraints WHERE table_name='FactSales'" -W

# 5. Row counts
$SQLCMD -Q "SELECT s.name AS [schema], t.name AS [table], SUM(p.rows) AS row_count FROM sys.tables t JOIN sys.schemas s ON t.schema_id=s.schema_id JOIN sys.partitions p ON t.object_id=p.object_id AND p.index_id IN (0,1) GROUP BY s.name, t.name ORDER BY row_count DESC" -W

# 6. Programmability objects
$SQLCMD -Q "SELECT name, type_desc FROM sys.objects WHERE type IN ('V','FN','IF','P','TF') ORDER BY type_desc, name" -W

Agentic Workflow

1. Discover → Run steps 1–4 to understand available tables/columns.
2. Sample →

   SELECT TOP 5

   on relevant tables.
3. Formulate → Select pattern from SQLDW-AUTHORING-CORE.md (Table DDL through Common Authoring Patterns).
4. Execute →

   $SQLCMD -Q "..."

   or

   $SQLCMD -i file.sql

   for multi-statement.
5. Verify → Query affected table (

   SELECT COUNT(*)

   ,

   SELECT TOP 5

   ).
6. Optionally script → Generate reusable

   .sh

   or

   .ps1

   using references/authoring-script-templates.md.

Gotchas, Rules, Troubleshooting

For full authoring gotchas: SQLDW-AUTHORING-CORE.md Authoring Gotchas and Troubleshooting. For CLI-specific issues: COMMON-CLI.md Gotchas & Troubleshooting (CLI-Specific).

MUST DO

• Verify workspace has capacity before creating warehouse — call

  GET /v1/workspaces/{id}

  and check

  capacityId

  .
• Always

  -d <DatabaseName>

  — FQDN alone is insufficient.
• Always

  -G

  or

  --authentication-method

  — SQL auth not supported on Fabric.

• az login

  first —

  ActiveDirectoryDefault

  uses az session. No session → cryptic failure.

• SET NOCOUNT ON;

  in scripts — suppresses row-count messages that corrupt output.
• Use

  -i file.sql

  for multi-statement batches (CREATE PROCEDURE, transactions with GO separators).
• Label authoring queries with

  OPTION (LABEL = 'ETL_description')

  .
• Use explicit

  CAST()

  in CTAS to control output types.
• Keep transactions short — long transactions increase conflict window.

AVOID

• ODBC sqlcmd (

  /opt/mssql-tools/bin/sqlcmd

  ) — requires ODBC driver. Use Go version.
• Omitting

  -W

  in scripts — trailing spaces corrupt CSV.
• Singleton

  INSERT ... VALUES

  at scale — creates tiny Parquet files. Use INSERT...SELECT, CTAS, or COPY INTO.

• DROP TABLE IF EXISTS

  +

  CREATE TABLE

  to refresh — loses time-travel history. Use

  TRUNCATE TABLE

  +

  INSERT INTO

  .
• MERGE in production — preview, table-level conflict detection. Use DELETE + INSERT.
• ALTER COLUMN — not supported. Use CTAS workaround (Schema Evolution).
• Variables in CTAS — not allowed. Wrap in dynamic SQL:

  EXEC sp_executesql N'CREATE TABLE ...'

  .
• DML on Lakehouse/Mirrored DB SQLEP — read-only for table data. Only views/funcs/procs can be authored.
• Concurrent UPDATE/DELETE on same table — snapshot isolation conflicts at table level. Serialize writes.
• Hardcoded FQDNs — discover via REST API (Connection section).
• MARS — not supported. Remove

  MultipleActiveResultSets

  from connection strings.

PREFER

• CTAS over

  CREATE TABLE

  +

  INSERT

  — parallel, single-operation.

• INSERT ... SELECT

  over singleton INSERTs.

• COPY INTO

  for external file ingestion — highest throughput.
• DELETE + INSERT over MERGE for upserts in production.

• TRUNCATE TABLE

  over

  DELETE FROM

  without WHERE — faster, preserves history.

• -i file.sql

  over

  -Q "..."

  for anything beyond simple one-liners.
• Piped here-doc for multi-statement batches without GO requirements.
• CTAS + sp_rename for large-scale transforms instead of UPDATE.

• sqlcmd (Go) -G

  over curl+token for SQL queries.

• -Q

  (non-interactive exit) for agentic use.

• -F vertical

  for exploration of wide tables.
• Env vars (

  FABRIC_SERVER

  ,

  FABRIC_DB

  ) for script reuse.

TROUBLESHOOTING

CAST()

-Q

-i file.sql

Login failed for user

-d

Cannot open server

Login timeout expired

ActiveDirectoryDefault

az login

az login --tenant <tenantId>

(N rows affected)

-W -s"," -w 4000

SET NOCOUNT ON;

sqlcmd

winget install sqlcmd