diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 481eef1..100a69c 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,18 +1,19 @@ { "$comment": "GENERATED by scripts/generate.mjs from catalog/catalog.json. Do not edit by hand; the parity gate will fail.", - "name": "azure-sql", + "name": "microsoft-sql", "owner": { - "name": "Microsoft", - "url": "https://github.com/microsoft/azure-sql-skills" + "name": "Microsoft SQL", + "url": "https://github.com/microsoft/microsoft-sql" }, "metadata": { - "description": "Curated by the Azure SQL Database product team. Skills that correct what coding agents get wrong about the engine, from connection strings to vector search, measured against a live database rather than quoted from documentation." + "description": "From the Microsoft SQL product team. Build AI-ready apps on Azure SQL Database with vector search, RAG, REST APIs, serverless functions, passwordless auth, and the ORMs you already use." }, "plugins": [ { - "name": "azure-sql", + "name": "microsoft-sql", + "displayName": "Microsoft SQL", "source": "./", - "description": "Curated by the Azure SQL Database product team. Skills that correct what coding agents get wrong about the engine, from connection strings to vector search, measured against a live database rather than quoted from documentation.", + "description": "From the Microsoft SQL product team. Build AI-ready apps on Azure SQL Database with vector search, RAG, REST APIs, serverless functions, passwordless auth, and the ORMs you already use.", "version": "0.1.0", "skills": [ "./skills/azure-functions-sql-bindings", @@ -73,6 +74,27 @@ "./skills/t-sql-upserts-merge", "./skills/vector-search-azure-sql" ] + }, + { + "name": "microsoft-sql-vscode", + "displayName": "Microsoft SQL for Visual Studio Code", + "source": "./plugins/microsoft-sql-vscode", + "description": "From the Microsoft SQL product team. Application work on Azure SQL Database in Visual Studio Code: connections and drivers, schema and ORMs, T-SQL, vector search and RAG, Azure Functions bindings, and database projects.", + "version": "0.1.0" + }, + { + "name": "microsoft-sql-ssms", + "displayName": "Microsoft SQL for SQL Server Management Studio", + "source": "./plugins/microsoft-sql-ssms", + "description": "From the Microsoft SQL product team. Running Azure SQL Database: diagnosing slow queries, blocking and resource pressure, reading execution plans, capturing Extended Events, restoring after data loss, row level security, passwordless access, provisioning and bulk data movement.", + "version": "0.1.0" + }, + { + "name": "microsoft-azuresql-db-container", + "displayName": "Azure SQL Database container", + "source": "./plugins/microsoft-azuresql-db-container", + "description": "From the Microsoft SQL product team. Local development against the Azure SQL Database container, the real cloud engine on your machine: running it, connecting to it, seeding and testing against it, importing an existing database, and proving the same code runs unchanged in Azure.", + "version": "0.1.0" } ] } diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 5913f54..234650f 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,17 +1,18 @@ { "$comment": "GENERATED by scripts/generate.mjs from catalog/catalog.json. Do not edit by hand; the parity gate will fail.", - "displayName": "Azure SQL", - "name": "azure-sql", + "displayName": "Microsoft SQL", + "name": "microsoft-sql", "version": "0.1.0", - "description": "Curated by the Azure SQL Database product team. Skills that correct what coding agents get wrong about the engine, from connection strings to vector search, measured against a live database rather than quoted from documentation.", + "description": "From the Microsoft SQL product team. Build AI-ready apps on Azure SQL Database with vector search, RAG, REST APIs, serverless functions, passwordless auth, and the ORMs you already use.", "author": { - "name": "Microsoft", + "name": "Microsoft SQL", "url": "https://microsoft.com" }, - "homepage": "https://github.com/microsoft/azure-sql-skills", - "repository": "https://github.com/microsoft/azure-sql-skills", + "homepage": "https://github.com/microsoft/microsoft-sql", + "repository": "https://github.com/microsoft/microsoft-sql", "license": "MIT", "keywords": [ + "microsoft-sql", "azure-sql", "sql", "database", diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 75d66c6..4836807 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,16 +1,17 @@ { "$comment": "GENERATED by scripts/generate.mjs from catalog/catalog.json. Do not edit by hand; the parity gate will fail.", - "name": "azure-sql", + "name": "microsoft-sql", "version": "0.1.0", - "description": "Curated by the Azure SQL Database product team. Skills that correct what coding agents get wrong about the engine, from connection strings to vector search, measured against a live database rather than quoted from documentation.", + "description": "From the Microsoft SQL product team. Build AI-ready apps on Azure SQL Database with vector search, RAG, REST APIs, serverless functions, passwordless auth, and the ORMs you already use.", "author": { - "name": "Microsoft", + "name": "Microsoft SQL", "url": "https://microsoft.com" }, - "homepage": "https://github.com/microsoft/azure-sql-skills", - "repository": "https://github.com/microsoft/azure-sql-skills", + "homepage": "https://github.com/microsoft/microsoft-sql", + "repository": "https://github.com/microsoft/microsoft-sql", "license": "MIT", "keywords": [ + "microsoft-sql", "azure-sql", "sql", "database", @@ -21,8 +22,8 @@ ], "skills": "./skills/", "interface": { - "displayName": "Azure SQL", - "shortDescription": "Curated by the Azure SQL Database product team. Skills that correct what coding agents get wrong about the engine, from connection strings to vector search, measured against a live database rather than quoted from documentation.", + "displayName": "Microsoft SQL", + "shortDescription": "From the Microsoft SQL product team. Build AI-ready apps on Azure SQL Database with vector search, RAG, REST APIs, serverless functions, passwordless auth, and the ORMs you already use.", "category": "Databases", "logo": "assets/plugin-logo.svg", "composerIcon": "assets/plugin-logo.svg" diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index cfe537c..0619e78 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -1,17 +1,18 @@ { "$comment": "GENERATED by scripts/generate.mjs from catalog/catalog.json. Do not edit by hand; the parity gate will fail.", - "displayName": "Azure SQL", - "name": "azure-sql", + "displayName": "Microsoft SQL", + "name": "microsoft-sql", "version": "0.1.0", - "description": "Curated by the Azure SQL Database product team. Skills that correct what coding agents get wrong about the engine, from connection strings to vector search, measured against a live database rather than quoted from documentation.", + "description": "From the Microsoft SQL product team. Build AI-ready apps on Azure SQL Database with vector search, RAG, REST APIs, serverless functions, passwordless auth, and the ORMs you already use.", "author": { - "name": "Microsoft", + "name": "Microsoft SQL", "url": "https://microsoft.com" }, - "homepage": "https://github.com/microsoft/azure-sql-skills", - "repository": "https://github.com/microsoft/azure-sql-skills", + "homepage": "https://github.com/microsoft/microsoft-sql", + "repository": "https://github.com/microsoft/microsoft-sql", "license": "MIT", "keywords": [ + "microsoft-sql", "azure-sql", "sql", "database", diff --git a/.grok-plugin/marketplace.json b/.grok-plugin/marketplace.json new file mode 100644 index 0000000..b71a144 --- /dev/null +++ b/.grok-plugin/marketplace.json @@ -0,0 +1,51 @@ +{ + "$comment": "GENERATED by scripts/generate.mjs from catalog/catalog.json. Do not edit by hand; the parity gate will fail.", + "name": "microsoft-sql", + "description": "From the Microsoft SQL product team. Build AI-ready apps on Azure SQL Database with vector search, RAG, REST APIs, serverless functions, passwordless auth, and the ORMs you already use.", + "owner": { + "name": "Microsoft SQL", + "url": "https://github.com/microsoft/microsoft-sql" + }, + "plugins": [ + { + "name": "microsoft-sql", + "displayName": "Microsoft SQL", + "description": "From the Microsoft SQL product team. Build AI-ready apps on Azure SQL Database with vector search, RAG, REST APIs, serverless functions, passwordless auth, and the ORMs you already use.", + "category": "databases", + "source": { + "type": "local", + "path": "./" + } + }, + { + "name": "microsoft-sql-vscode", + "displayName": "Microsoft SQL for Visual Studio Code", + "description": "From the Microsoft SQL product team. Application work on Azure SQL Database in Visual Studio Code: connections and drivers, schema and ORMs, T-SQL, vector search and RAG, Azure Functions bindings, and database projects.", + "category": "databases", + "source": { + "type": "local", + "path": "./plugins/microsoft-sql-vscode" + } + }, + { + "name": "microsoft-sql-ssms", + "displayName": "Microsoft SQL for SQL Server Management Studio", + "description": "From the Microsoft SQL product team. Running Azure SQL Database: diagnosing slow queries, blocking and resource pressure, reading execution plans, capturing Extended Events, restoring after data loss, row level security, passwordless access, provisioning and bulk data movement.", + "category": "databases", + "source": { + "type": "local", + "path": "./plugins/microsoft-sql-ssms" + } + }, + { + "name": "microsoft-azuresql-db-container", + "displayName": "Azure SQL Database container", + "description": "From the Microsoft SQL product team. Local development against the Azure SQL Database container, the real cloud engine on your machine: running it, connecting to it, seeding and testing against it, importing an existing database, and proving the same code runs unchanged in Azure.", + "category": "databases", + "source": { + "type": "local", + "path": "./plugins/microsoft-azuresql-db-container" + } + } + ] +} diff --git a/.grok-plugin/plugin.json b/.grok-plugin/plugin.json new file mode 100644 index 0000000..2dcdcbf --- /dev/null +++ b/.grok-plugin/plugin.json @@ -0,0 +1,25 @@ +{ + "$comment": "GENERATED by scripts/generate.mjs from catalog/catalog.json. Do not edit by hand; the parity gate will fail.", + "displayName": "Microsoft SQL", + "name": "microsoft-sql", + "version": "0.1.0", + "description": "From the Microsoft SQL product team. Build AI-ready apps on Azure SQL Database with vector search, RAG, REST APIs, serverless functions, passwordless auth, and the ORMs you already use.", + "author": { + "name": "Microsoft SQL", + "url": "https://microsoft.com" + }, + "homepage": "https://github.com/microsoft/microsoft-sql", + "repository": "https://github.com/microsoft/microsoft-sql", + "license": "MIT", + "keywords": [ + "microsoft-sql", + "azure-sql", + "sql", + "database", + "tsql", + "agent-skills", + "vector-search", + "entra-id" + ], + "skills": "skills/" +} diff --git a/AGENTS.md b/AGENTS.md index 41c9192..967c346 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,8 +16,11 @@ before proposing anything. ## What this repository holds -- `skills///` , the content a customer installs +- `skills//` , the content a customer installs. Flat, one level, as the Agent Plugins + specification requires - `catalog/catalog.json` , all 142 skills, including the ones with no content yet +- `catalog/plugins.json` , which skills each scoped plugin carries +- `plugins//` , generated copies of those subsets. Never edit anything under here - `scripts/` , the structural gates CI runs ## Two rules that matter most here @@ -92,9 +95,17 @@ decide what is valid, ask what a clean clone actually contains. ## Generated surfaces -`llms.txt`, `apm.yml`, `.claude-plugin/`, `.codex-plugin/`, `.cursor-plugin/`, `.grok-plugin/`, -`.agents/plugins/` and the catalog table inside `README.md` are all generated by -`scripts/generate.mjs` from `catalog/catalog.json` and `catalog/taxonomy.json`. +`llms.txt`, `apm.yml`, `plugin.json`, `.claude-plugin/`, `.codex-plugin/`, `.cursor-plugin/`, +`.grok-plugin/`, everything under `plugins/`, the skill options inside +`.github/ISSUE_TEMPLATE/skill_feedback.yml` and the catalog table inside `README.md` are all +generated by `scripts/generate.mjs` from `catalog/catalog.json`, `catalog/taxonomy.json` and +`catalog/plugins.json`. + +`plugins/` holds a folder per scoped plugin: its four manifests, its logo, a README saying it is +generated, and **byte copies of the skills it carries**. Copies rather than symlinks because Codex +installs an empty skills directory from a symlinked plugin without reporting an error, and a Windows +clone turns each link into a small text file. So a skill's content exists more than once on disk, and +there is still exactly one place a human edits it: `skills/`. **Never edit them by hand.** CI regenerates and diffs. Change the source, run `npm run generate`, commit the result. diff --git a/README.md b/README.md index 0fff103..9fdfa8b 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,18 @@ -# Azure SQL Agent Skills +# Microsoft SQL -Curated by the Azure SQL Database product team. Skills that correct what coding agents get wrong about the engine, from connection strings to vector search, measured against a live database rather than quoted from documentation. +From the Microsoft SQL product team. Build AI-ready apps on Azure SQL Database with vector search, RAG, REST APIs, serverless functions, passwordless auth, and the ORMs you already use. [![Documentation](https://img.shields.io/badge/Documentation-blue?logo=github)](https://learn.microsoft.com/azure/azure-sql/database/) [![Agent Plugins](https://img.shields.io/badge/Agent%20Plugins-1.0.0-8A2BE2?logo=github)](https://agent-plugins.org/specification) [![Agent Skills](https://img.shields.io/badge/Agent%20Skills-spec-brightgreen?logo=github)](https://agentskills.io/) [![Skill feedback](https://img.shields.io/badge/Skill%20feedback-red?logo=github)](https://aka.ms/sql-agent-skills-feedback) [![Discussions](https://img.shields.io/badge/Discussions-blueviolet?logo=github)](../../discussions) -[![Skills](https://skills.sh/b/microsoft/azure-sql-skills)](https://skills.sh/microsoft/azure-sql-skills) +[![Skills](https://skills.sh/b/microsoft/microsoft-sql)](https://skills.sh/microsoft/microsoft-sql) - Watch the Azure SQL agent skills demo + Watch the Microsoft SQL demo **Watch the demo** @@ -26,19 +26,19 @@ These follow the [Agent Skills](https://agentskills.io/) format, and the reposit ### Install every skill ```bash -npx skills add microsoft/azure-sql-skills +npx skills add microsoft/microsoft-sql ``` ### Install one skill ```bash -npx skills add microsoft/azure-sql-skills --skill connect-to-azure-sql +npx skills add microsoft/microsoft-sql --skill connect-to-azure-sql ``` ### GitHub CLI ```bash -gh skill install microsoft/azure-sql-skills --all --agent claude-code +gh skill install microsoft/microsoft-sql --all --agent claude-code ``` Choose your agent with `--agent`, for example `github-copilot` or `cursor`. @@ -52,17 +52,75 @@ The repository root is an Agent Plugins package. [`plugin.json`](plugin.json) de Claude Code uses its own plugin format rather than Agent Plugins, so it has its own path: ```bash -claude plugin marketplace add microsoft/azure-sql-skills +claude plugin marketplace add microsoft/microsoft-sql ``` ```bash -claude plugin install azure-sql-skills@azure-sql-skills +claude plugin install microsoft-sql@microsoft-sql +``` + +### GitHub Copilot CLI plugin + +```bash +copilot plugin marketplace add microsoft/microsoft-sql +``` + +```bash +copilot plugin install microsoft-sql@microsoft-sql +``` + +Visual Studio Code loads plugins installed this way, so the same two commands cover it. + +### Codex plugin + +```bash +codex plugin marketplace add microsoft/microsoft-sql +``` + +```bash +codex plugin add microsoft-sql@microsoft-sql ``` ### Repository-committed skills Committed to `.github/skills/` in your own repository, skills also reach the GitHub Copilot coding agent and Visual Studio agent mode with no install step at all. +## Pick a plugin + +The commands above install the whole collection. If you work in one place, a smaller plugin carries only the skills that belong there, so your agent reads less on every turn and never reaches for a skill your tool already handles. + +| Install | What it carries | Who it is for | +|---|---|---| +| `microsoft-sql` | every skill | you drive an agent directly and want the lot | +| `microsoft-sql-vscode` | connections, schema and ORMs, T-SQL, vector search and RAG, Azure Functions bindings, database projects | the MSSQL extension for Visual Studio Code | +| `microsoft-sql-ssms` | diagnostics, execution plans, Extended Events, restore, row level security, provisioning, bulk data movement | SQL Server Management Studio | +| `microsoft-azuresql-db-container` | running the Azure SQL Database container locally, connecting, seeding, testing, importing, going to the cloud | local development against the container | + +Every plugin comes from the same marketplace, so the pattern is always `@microsoft-sql`. Add the marketplace once, then install whichever ones you want: + +```bash +claude plugin marketplace add microsoft/microsoft-sql +claude plugin install microsoft-sql-vscode@microsoft-sql +``` + +```bash +copilot plugin marketplace add microsoft/microsoft-sql +copilot plugin install microsoft-sql-ssms@microsoft-sql +``` + +```bash +codex plugin marketplace add microsoft/microsoft-sql +codex plugin add microsoft-azuresql-db-container@microsoft-sql +``` + +Visual Studio Code loads whatever the GitHub Copilot CLI installed. Cursor loads whatever Claude Code installed, after you quit and reopen it. + +Two things worth knowing before you choose: + +**Installing two plugins installs both sets.** The Visual Studio Code plugin leaves out the Data API builder skills on purpose, because the MSSQL extension already carries its own Data API builder tooling. Install the full collection alongside it and those skills come back. + +**A smaller plugin knows less.** These skills hand work to each other by name, so a skill in a subset can point you at one the subset does not carry. Install the full collection if you would rather have everything than have less to read. + ## Available skills diff --git a/SUPPORT.md b/SUPPORT.md index 25bc851..135e7fc 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -4,7 +4,7 @@ This project uses GitHub Issues for feedback about the skills in this repository: a skill that gave you wrong guidance, a skill that did not load when it should have, or one that loaded when it should -not have. Please search the [existing issues](https://github.com/microsoft/azure-sql-skills/issues) +not have. Please search the [existing issues](https://github.com/microsoft/microsoft-sql/issues) before filing, to avoid duplicates. Open a new issue with the **Agent skill feedback** form: @@ -12,7 +12,7 @@ Open a new issue with the **Agent skill feedback** form: off, so the form is the way in. Tell us which skill, what you asked, and what it did. For questions about using the skills rather than a defect in one, use -[Discussions](https://github.com/microsoft/azure-sql-skills/discussions). +[Discussions](https://github.com/microsoft/microsoft-sql/discussions). Issues here are about the skills. For the Azure SQL Database service itself, start with the [Azure SQL Database documentation](https://learn.microsoft.com/azure/azure-sql/database/), and use diff --git a/apm.yml b/apm.yml index dc6febb..9254805 100644 --- a/apm.yml +++ b/apm.yml @@ -1,14 +1,14 @@ # GENERATED by scripts/generate.mjs from catalog/catalog.json. Do not edit by hand; the parity gate will fail. -name: azure-sql +name: microsoft-sql version: "0.1.0" description: >- - Curated by the Azure SQL Database product team. Skills that correct what coding agents get wrong about the engine, from connection strings to vector search, measured against a live database rather than quoted from documentation. -author: Microsoft + From the Microsoft SQL product team. Build AI-ready apps on Azure SQL Database with vector search, RAG, REST APIs, serverless functions, passwordless auth, and the ORMs you already use. +author: Microsoft SQL license: MIT -homepage: https://github.com/microsoft/azure-sql-skills -repository: https://github.com/microsoft/azure-sql-skills -keywords: [azure-sql, sql, database, tsql, agent-skills, vector-search, entra-id] +homepage: https://github.com/microsoft/microsoft-sql +repository: https://github.com/microsoft/microsoft-sql +keywords: [microsoft-sql, azure-sql, sql, database, tsql, agent-skills, vector-search, entra-id] # Constrains what this package may contain. Skills, and nothing else. type: skill diff --git a/catalog/plugins.json b/catalog/plugins.json new file mode 100644 index 0000000..ebc95b7 --- /dev/null +++ b/catalog/plugins.json @@ -0,0 +1,88 @@ +{ + "$comment": "Scoped plugins. Each one ships a subset of skills/ for a single surface, so a user of that surface installs what they need and nothing else. scripts/generate.mjs reads this file, writes plugins//, and the parity gate fails if a generated copy drifts. The full collection is not listed here: it is the repository root and carries every skill.", + "plugins": [ + { + "name": "microsoft-sql-vscode", + "displayName": "Microsoft SQL for Visual Studio Code", + "description": "From the Microsoft SQL product team. Application work on Azure SQL Database in Visual Studio Code: connections and drivers, schema and ORMs, T-SQL, vector search and RAG, Azure Functions bindings, and database projects.", + "why": "The MSSQL extension already carries Data API builder tooling, so shipping our Data API builder skills into this surface puts two sets of instructions on one subject in front of the same agent.", + "mustNotInclude": ["dab-rest-and-graphql", "azuresql-db-dab", "build-app-on-azure-sql"], + "skills": [ + "connect-to-azure-sql", + "connect-from-dotnet", + "connect-from-python", + "connect-from-typescript-and-node", + "diagnose-connection-errors", + "design-azure-sql-schema", + "ef-core-azure-sql", + "prisma-azure-sql", + "sqlalchemy-azure-sql", + "t-sql-correctness", + "t-sql-json-and-openjson", + "t-sql-upserts-merge", + "prevent-sql-injection", + "entra-id-auth", + "vector-search-azure-sql", + "embeddings-and-external-models", + "rag-on-azure-sql", + "langchain-and-llamaindex-on-azure-sql", + "azure-functions-sql-bindings", + "dev-container-templates", + "sql-database-projects", + "schema-migrations-safely", + "skill-feedback" + ] + }, + { + "name": "microsoft-sql-ssms", + "displayName": "Microsoft SQL for SQL Server Management Studio", + "description": "From the Microsoft SQL product team. Running Azure SQL Database: diagnosing slow queries, blocking and resource pressure, reading execution plans, capturing Extended Events, restoring after data loss, row level security, passwordless access, provisioning and bulk data movement.", + "why": "This surface belongs to a database administrator. Application development, ORMs, serverless bindings and AI work belong in the Visual Studio Code plugin instead.", + "mustNotInclude": ["dab-rest-and-graphql", "azuresql-db-dab", "azure-functions-sql-bindings", "azuresql-db-functions"], + "skills": [ + "diagnose-slow-query", + "diagnose-blocking-and-deadlocks", + "diagnose-resource-pressure", + "diagnose-connection-errors", + "read-execution-plan", + "capture-with-extended-events", + "restore-and-recover", + "rls-multi-tenant", + "prevent-sql-injection", + "entra-id-auth", + "provision-azure-sql-db", + "provision-hyperscale", + "bulk-load-and-bulk-copy", + "sqlpackage-import-export", + "skill-feedback" + ] + }, + { + "name": "microsoft-azuresql-db-container", + "displayName": "Azure SQL Database container", + "description": "From the Microsoft SQL product team. Local development against the Azure SQL Database container, the real cloud engine on your machine: running it, connecting to it, seeding and testing against it, importing an existing database, and proving the same code runs unchanged in Azure.", + "why": "The container is its own product with its own audience. Someone who wants a local engine should not have to take the whole cloud catalog to get it.", + "mustNotInclude": [], + "skills": [ + "azuresql-db-auth", + "azuresql-db-ci", + "azuresql-db-connections", + "azuresql-db-container", + "azuresql-db-dab", + "azuresql-db-faq", + "azuresql-db-feedback", + "azuresql-db-from-sql-server", + "azuresql-db-functions", + "azuresql-db-import", + "azuresql-db-local-to-cloud", + "azuresql-db-rag", + "azuresql-db-scaffold", + "azuresql-db-schema-migration", + "azuresql-db-seed", + "azuresql-db-sidecar", + "azuresql-db-testing", + "skill-feedback" + ] + } + ] +} diff --git a/llms.txt b/llms.txt index 2e346a1..38dadbd 100644 --- a/llms.txt +++ b/llms.txt @@ -1,6 +1,6 @@ -# Azure SQL Agent Skills +# Microsoft SQL -> Curated by the Azure SQL Database product team. Skills that correct what coding agents get wrong about the engine, from connection strings to vector search, measured against a live database rather than quoted from documentation. +> From the Microsoft SQL product team. Build AI-ready apps on Azure SQL Database with vector search, RAG, REST APIs, serverless functions, passwordless auth, and the ORMs you already use. @@ -12,133 +12,133 @@ searching deeper. Domain is metadata in the sidecar, not a directory. Get a developer to a working database in minutes, and onto the right service tier when the workload is real -- [dev-container-templates](https://github.com/microsoft/azure-sql-skills/blob/main/skills/dev-container-templates/SKILL.md): Sets up local development from the Azure SQL Database dev container templates in microsoft/azuresql-devcontainers (.NET, .NET Aspire, Node.js, Python), each with a sample database and schema loaded. Use for "start from the Azure SQL Database dev container template", "which Azure SQL Database devcontainer should I pick", or "add a dev container with a database already in it", and for what these templates do: an empty database, a schema project that never deploys, a saved profile prompting for a password, a database at localhost not a service name, a vector index refused, a port on the app service refused, or the local database in a template not behaving the way the Azure SQL Database documentation describes, because it is SQL Server. Covers the SQL Database project whose target platform, not the engine, decides what Azure SQL Database accepts, and the create-time build and publish. -- [provision-azure-sql-db](https://github.com/microsoft/azure-sql-skills/blob/main/skills/provision-azure-sql-db/SKILL.md): Creates an Azure SQL Database and returns a connection string that actually works, covering the free offer and paid tiers, the firewall rule, and Microsoft Entra-only administration. Use when a user asks to "create an Azure SQL database", "set up a free SQL database in Azure", "provision SQL for this app", "give me a connection string", or when an application needs a cloud database and none exists yet. Also use when a provisioning attempt succeeded but nothing can connect, which is almost always the missing firewall rule. Covers how many free databases a subscription actually gets and the exhaustion behavior value the CLI accepts, which is not the one its own help text describes. -- [provision-hyperscale](https://github.com/microsoft/azure-sql-skills/blob/main/skills/provision-hyperscale/SKILL.md): Puts a real workload on the Hyperscale service tier of Azure SQL Database: when to choose it, how to size it, and how to convert an existing database without walking through a door that does not open again. Use when a user asks "should I use Hyperscale", "convert my database to Hyperscale", "we are close to the 4 TB ceiling", "how many vCores for Hyperscale", "Hyperscale serverless or provisioned", "add a read replica", "elastic pool for Hyperscale", or "can I go back from Hyperscale". Also use when a free offer database has to become a real one, because the free limit must be turned off before the tier can change and that step cannot be undone. Covers the eligibility rules for reverse migration, controlling the cutover, replica-based read scale-out, and what actually limits write throughput. Creating the server, the database and the firewall rule belongs to provision-azure-sql-db. +- [dev-container-templates](https://github.com/microsoft/microsoft-sql/blob/main/skills/dev-container-templates/SKILL.md): Sets up local development from the Azure SQL Database dev container templates in microsoft/azuresql-devcontainers (.NET, .NET Aspire, Node.js, Python), each with a sample database and schema loaded. Use for "start from the Azure SQL Database dev container template", "which Azure SQL Database devcontainer should I pick", or "add a dev container with a database already in it", and for what these templates do: an empty database, a schema project that never deploys, a saved profile prompting for a password, a database at localhost not a service name, a vector index refused, a port on the app service refused, or the local database in a template not behaving the way the Azure SQL Database documentation describes, because it is SQL Server. Covers the SQL Database project whose target platform, not the engine, decides what Azure SQL Database accepts, and the create-time build and publish. +- [provision-azure-sql-db](https://github.com/microsoft/microsoft-sql/blob/main/skills/provision-azure-sql-db/SKILL.md): Creates an Azure SQL Database and returns a connection string that actually works, covering the free offer and paid tiers, the firewall rule, and Microsoft Entra-only administration. Use when a user asks to "create an Azure SQL database", "set up a free SQL database in Azure", "provision SQL for this app", "give me a connection string", or when an application needs a cloud database and none exists yet. Also use when a provisioning attempt succeeded but nothing can connect, which is almost always the missing firewall rule. Covers how many free databases a subscription actually gets and the exhaustion behavior value the CLI accepts, which is not the one its own help text describes. +- [provision-hyperscale](https://github.com/microsoft/microsoft-sql/blob/main/skills/provision-hyperscale/SKILL.md): Puts a real workload on the Hyperscale service tier of Azure SQL Database: when to choose it, how to size it, and how to convert an existing database without walking through a door that does not open again. Use when a user asks "should I use Hyperscale", "convert my database to Hyperscale", "we are close to the 4 TB ceiling", "how many vCores for Hyperscale", "Hyperscale serverless or provisioned", "add a read replica", "elastic pool for Hyperscale", or "can I go back from Hyperscale". Also use when a free offer database has to become a real one, because the free limit must be turned off before the tier can change and that step cannot be undone. Covers the eligibility rules for reverse migration, controlling the cutover, replica-based read scale-out, and what actually limits write throughput. Creating the server, the database and the firewall rule belongs to provision-azure-sql-db. ## Drivers and connectivity Connect from any language first try, and fix it fast when it fails -- [connect-from-dotnet](https://github.com/microsoft/azure-sql-skills/blob/main/skills/connect-from-dotnet/SKILL.md): Connects a .NET application to Azure SQL Database with Microsoft.Data.SqlClient: which package references are required, the encryption defaults and what changed, connection pooling and the keys that split a pool, and managed identity or other Microsoft Entra ID modes. Use when a user says "connect .NET to Azure SQL", "Microsoft.Data.SqlClient", "SqlConnection", "passwordless access for my .NET app", "managed identity for my API", "Active Directory Default", "Max Pool Size", "Encrypt=Strict", or asks whether "Microsoft.Data.SqlClient.Extensions.Azure" is needed. Also use when an app authenticates with a password locally and must use an identity in Azure. Covers packages, connection string keywords, pooling and Entra ID for .NET only; the ORM path is ef-core-azure-sql, and encryption doctrine plus transient-fault retry belong to connect-to-azure-sql. -- [connect-from-python](https://github.com/microsoft/azure-sql-skills/blob/main/skills/connect-from-python/SKILL.md): Connects a Python application to Azure SQL Database, choosing between Microsoft's first-party mssql-python driver and the incumbent pyodbc, and covering driver installation, the connection string each one wants, connection pooling, and Microsoft Entra ID including token-based authentication. Use when a user says "connect Python to Azure SQL", "mssql-python", "pyodbc", "install the ODBC driver so my Python code can connect", "which Python driver for SQL Server", or hits errors such as "data source name not found and no default driver specified" or a container image that cannot load the driver. Also use when adding a database layer to a Python service, or when it needs a passwordless connection. Covers installation, connection strings, pooling and Entra ID for Python only. Encryption doctrine and transient-fault retry belong to connect-to-azure-sql; Node and .NET have their own skills. -- [connect-from-typescript-and-node](https://github.com/microsoft/azure-sql-skills/blob/main/skills/connect-from-typescript-and-node/SKILL.md): Connects a TypeScript or JavaScript application to Azure SQL Database with the mssql package over tedious: which packages to install, where the connection pool has to live, how to type query results, and how to authenticate with Microsoft Entra ID without a password. Use when a user says "connect my Node app to Azure SQL", "which npm package for SQL Server", "mssql pool size", "passwordless connection from Node", "azure-active-directory-default", "@types/mssql", or reports that a Node API gets slower under load, opens a connection per request, or runs out of connections. Also use when adding a database layer to a Node backend, an Azure Function or an Express route. Covers driver installation, the config object, pool lifetime and Entra ID for this stack only. Encryption doctrine, retry and transient-fault handling belong to connect-to-azure-sql; Python and .NET have their own skills. -- [connect-to-azure-sql](https://github.com/microsoft/azure-sql-skills/blob/main/skills/connect-to-azure-sql/SKILL.md): Connects an application to Azure SQL Database: picks the Microsoft driver for the language, sets encryption and certificate validation, sizes the pool against the worker limit not the session limit, and makes retry part of the first version of the code. Use when a user asks "how do I connect to Azure SQL", "which driver should I use", "what goes in the connection string", "add retry logic", "the connection keeps dropping", "should I set TrustServerCertificate", or "my app times out connecting to Azure". Also use when a first connection to a free or serverless database fails with error 40613, documented resume behaviour, not an outage. Azure SQL Database only, not Azure SQL Managed Instance and not self-managed SQL Server. Driver installation, connection strings and pooling per language belong to connect-from-dotnet, connect-from-python and connect-from-typescript-and-node. -- [diagnose-connection-errors](https://github.com/microsoft/azure-sql-skills/blob/main/skills/diagnose-connection-errors/SKILL.md): Diagnoses an Azure SQL Database connection refused before a credential was evaluated, reading the error number to name the layer that refused: the IP firewall (40615), a virtual network rule (40914), public network access disabled (47073, 42101), the gateway declining a server name or login format (40532, 40531), a TLS version under the server minimum (47072), plus the transport, pre-login, timeout and certificate failures that carry no number. Use when someone pastes an error naming an IP address, a firewall, the gateway, a certificate chain, the pre-login handshake or a bare timeout, before anyone edits a connection string: none of these is a connection-string problem. Not what the server decided after reading the credential: a login refused, or a valid login with no database user, is entra-id-auth's; a database asking for a retry while it resumes is connect-to-azure-sql's. +- [connect-from-dotnet](https://github.com/microsoft/microsoft-sql/blob/main/skills/connect-from-dotnet/SKILL.md): Connects a .NET application to Azure SQL Database with Microsoft.Data.SqlClient: which package references are required, the encryption defaults and what changed, connection pooling and the keys that split a pool, and managed identity or other Microsoft Entra ID modes. Use when a user says "connect .NET to Azure SQL", "Microsoft.Data.SqlClient", "SqlConnection", "passwordless access for my .NET app", "managed identity for my API", "Active Directory Default", "Max Pool Size", "Encrypt=Strict", or asks whether "Microsoft.Data.SqlClient.Extensions.Azure" is needed. Also use when an app authenticates with a password locally and must use an identity in Azure. Covers packages, connection string keywords, pooling and Entra ID for .NET only; the ORM path is ef-core-azure-sql, and encryption doctrine plus transient-fault retry belong to connect-to-azure-sql. +- [connect-from-python](https://github.com/microsoft/microsoft-sql/blob/main/skills/connect-from-python/SKILL.md): Connects a Python application to Azure SQL Database, choosing between Microsoft's first-party mssql-python driver and the incumbent pyodbc, and covering driver installation, the connection string each one wants, connection pooling, and Microsoft Entra ID including token-based authentication. Use when a user says "connect Python to Azure SQL", "mssql-python", "pyodbc", "install the ODBC driver so my Python code can connect", "which Python driver for SQL Server", or hits errors such as "data source name not found and no default driver specified" or a container image that cannot load the driver. Also use when adding a database layer to a Python service, or when it needs a passwordless connection. Covers installation, connection strings, pooling and Entra ID for Python only. Encryption doctrine and transient-fault retry belong to connect-to-azure-sql; Node and .NET have their own skills. +- [connect-from-typescript-and-node](https://github.com/microsoft/microsoft-sql/blob/main/skills/connect-from-typescript-and-node/SKILL.md): Connects a TypeScript or JavaScript application to Azure SQL Database with the mssql package over tedious: which packages to install, where the connection pool has to live, how to type query results, and how to authenticate with Microsoft Entra ID without a password. Use when a user says "connect my Node app to Azure SQL", "which npm package for SQL Server", "mssql pool size", "passwordless connection from Node", "azure-active-directory-default", "@types/mssql", or reports that a Node API gets slower under load, opens a connection per request, or runs out of connections. Also use when adding a database layer to a Node backend, an Azure Function or an Express route. Covers driver installation, the config object, pool lifetime and Entra ID for this stack only. Encryption doctrine, retry and transient-fault handling belong to connect-to-azure-sql; Python and .NET have their own skills. +- [connect-to-azure-sql](https://github.com/microsoft/microsoft-sql/blob/main/skills/connect-to-azure-sql/SKILL.md): Connects an application to Azure SQL Database: picks the Microsoft driver for the language, sets encryption and certificate validation, sizes the pool against the worker limit not the session limit, and makes retry part of the first version of the code. Use when a user asks "how do I connect to Azure SQL", "which driver should I use", "what goes in the connection string", "add retry logic", "the connection keeps dropping", "should I set TrustServerCertificate", or "my app times out connecting to Azure". Also use when a first connection to a free or serverless database fails with error 40613, documented resume behaviour, not an outage. Azure SQL Database only, not Azure SQL Managed Instance and not self-managed SQL Server. Driver installation, connection strings and pooling per language belong to connect-from-dotnet, connect-from-python and connect-from-typescript-and-node. +- [diagnose-connection-errors](https://github.com/microsoft/microsoft-sql/blob/main/skills/diagnose-connection-errors/SKILL.md): Diagnoses an Azure SQL Database connection refused before a credential was evaluated, reading the error number to name the layer that refused: the IP firewall (40615), a virtual network rule (40914), public network access disabled (47073, 42101), the gateway declining a server name or login format (40532, 40531), a TLS version under the server minimum (47072), plus the transport, pre-login, timeout and certificate failures that carry no number. Use when someone pastes an error naming an IP address, a firewall, the gateway, a certificate chain, the pre-login handshake or a bare timeout, before anyone edits a connection string: none of these is a connection-string problem. Not what the server decided after reading the credential: a login refused, or a valid login with no database user, is entra-id-auth's; a database asking for a retry while it resumes is connect-to-azure-sql's. ## Schema and ORM Model data and wire up the ORM the developer already uses -- [design-azure-sql-schema](https://github.com/microsoft/azure-sql-skills/blob/main/skills/design-azure-sql-schema/SKILL.md): Designs tables for Azure SQL Database so the first index or long value does not force a rebuild. Covers index key limits in bytes, why Unicode sizing makes NVARCHAR(850) and NVARCHAR(450) the real ceilings, collation decided once at CREATE DATABASE, the implicit conversion that turns a lookup into a scan, identity gaps of a thousand after a restart, unique columns that accept exactly one NULL. Use when creating or reviewing tables, porting a PostgreSQL or MySQL schema to Azure SQL Database, choosing a key, a string length or a collation, or reports a warning about maximum key length, an insert failing long after its migration, a lookup that suddenly scans, identity values that jumped, or a duplicate key on NULL. The engine rule under the mappers: ef-core-azure-sql and sqlalchemy-azure-sql own how each expresses it, t-sql-correctness syntax, vector-search-azure-sql vector columns. -- [ef-core-azure-sql](https://github.com/microsoft/azure-sql-skills/blob/main/skills/ef-core-azure-sql/SKILL.md): Configures Entity Framework Core against Azure SQL Database, where retry is on by default and redefines a transaction: the execution strategy refuses a user-initiated transaction, and the wrapper it tells you to write replays the whole unit, so a fault after the commit writes the row twice and reports success. Also covers UseAzureSql versus UseSqlServer, EnableRetryOnFailure, JSON mapping and split queries. Use when a DbContext targets Azure SQL Database, and for "EnableRetryOnFailure", "connection resiliency for EF Core", "UseAzureSql or UseSqlServer", "AsSplitQuery", an Include returning tens of thousands of rows, "does not support user-initiated transactions", duplicated rows after a retry, or a migration that retypes JSON columns. Not general EF Core: pooling is connect-from-dotnet, retry connect-to-azure-sql, identity entra-id-auth, a pipeline github-actions-for-sql. -- [prisma-azure-sql](https://github.com/microsoft/azure-sql-skills/blob/main/skills/prisma-azure-sql/SKILL.md): Uses Prisma ORM against Azure SQL Database on JavaScript and TypeScript, inside the connector's real limits: no Json type, no enums, no scalar lists, a default string length that quietly breaks keys, a connection URL that moved out of the schema file in Prisma 7, and a migration workflow that succeeds locally and is refused in the cloud. Use when a user says "Prisma with Azure SQL", "prisma migrate dev", "prisma db push", "schema.prisma", "prisma.config.ts", "driver adapter", or pastes "P3020", "the automatic creation of shadow databases is disabled", "the current connector does not support the Json type", or "the datasource property url is no longer supported". Also use when Prisma migrations work locally and fail against Azure. Covers schema, type mapping, migrations and identity for Prisma only. Drivers and pooling are connect-from-typescript-and-node, retry connect-to-azure-sql. -- [sqlalchemy-azure-sql](https://github.com/microsoft/azure-sql-skills/blob/main/skills/sqlalchemy-azure-sql/SKILL.md): Uses SQLAlchemy correctly against Azure SQL Database, where the dialect appends an OUTPUT clause to INSERT statements and that single clause explains two failures agents never connect: a hard error on any table carrying a trigger, and fast_executemany appearing to do nothing. Use when a user says "SQLAlchemy with Azure SQL", "mssql+pyodbc", "implicit_returning", "fast_executemany", "insertmanyvalues", "Alembic against Azure SQL", or pastes "the target table of the DML statement cannot have any enabled triggers if the statement contains an OUTPUT clause without INTO clause". Also use when an ORM insert fails on one table only, or a bulk load is no faster after fast_executemany was set. Covers the engine URL, the generated DML, type mapping and Alembic. Driver choice is connect-from-python and retry connect-to-azure-sql. +- [design-azure-sql-schema](https://github.com/microsoft/microsoft-sql/blob/main/skills/design-azure-sql-schema/SKILL.md): Designs tables for Azure SQL Database so the first index or long value does not force a rebuild. Covers index key limits in bytes, why Unicode sizing makes NVARCHAR(850) and NVARCHAR(450) the real ceilings, collation decided once at CREATE DATABASE, the implicit conversion that turns a lookup into a scan, identity gaps of a thousand after a restart, unique columns that accept exactly one NULL. Use when creating or reviewing tables, porting a PostgreSQL or MySQL schema to Azure SQL Database, choosing a key, a string length or a collation, or reports a warning about maximum key length, an insert failing long after its migration, a lookup that suddenly scans, identity values that jumped, or a duplicate key on NULL. The engine rule under the mappers: ef-core-azure-sql and sqlalchemy-azure-sql own how each expresses it, t-sql-correctness syntax, vector-search-azure-sql vector columns. +- [ef-core-azure-sql](https://github.com/microsoft/microsoft-sql/blob/main/skills/ef-core-azure-sql/SKILL.md): Configures Entity Framework Core against Azure SQL Database, where retry is on by default and redefines a transaction: the execution strategy refuses a user-initiated transaction, and the wrapper it tells you to write replays the whole unit, so a fault after the commit writes the row twice and reports success. Also covers UseAzureSql versus UseSqlServer, EnableRetryOnFailure, JSON mapping and split queries. Use when a DbContext targets Azure SQL Database, and for "EnableRetryOnFailure", "connection resiliency for EF Core", "UseAzureSql or UseSqlServer", "AsSplitQuery", an Include returning tens of thousands of rows, "does not support user-initiated transactions", duplicated rows after a retry, or a migration that retypes JSON columns. Not general EF Core: pooling is connect-from-dotnet, retry connect-to-azure-sql, identity entra-id-auth, a pipeline github-actions-for-sql. +- [prisma-azure-sql](https://github.com/microsoft/microsoft-sql/blob/main/skills/prisma-azure-sql/SKILL.md): Uses Prisma ORM against Azure SQL Database on JavaScript and TypeScript, inside the connector's real limits: no Json type, no enums, no scalar lists, a default string length that quietly breaks keys, a connection URL that moved out of the schema file in Prisma 7, and a migration workflow that succeeds locally and is refused in the cloud. Use when a user says "Prisma with Azure SQL", "prisma migrate dev", "prisma db push", "schema.prisma", "prisma.config.ts", "driver adapter", or pastes "P3020", "the automatic creation of shadow databases is disabled", "the current connector does not support the Json type", or "the datasource property url is no longer supported". Also use when Prisma migrations work locally and fail against Azure. Covers schema, type mapping, migrations and identity for Prisma only. Drivers and pooling are connect-from-typescript-and-node, retry connect-to-azure-sql. +- [sqlalchemy-azure-sql](https://github.com/microsoft/microsoft-sql/blob/main/skills/sqlalchemy-azure-sql/SKILL.md): Uses SQLAlchemy correctly against Azure SQL Database, where the dialect appends an OUTPUT clause to INSERT statements and that single clause explains two failures agents never connect: a hard error on any table carrying a trigger, and fast_executemany appearing to do nothing. Use when a user says "SQLAlchemy with Azure SQL", "mssql+pyodbc", "implicit_returning", "fast_executemany", "insertmanyvalues", "Alembic against Azure SQL", or pastes "the target table of the DML statement cannot have any enabled triggers if the statement contains an OUTPUT clause without INTO clause". Also use when an ORM insert fails on one table only, or a bulk load is no faster after fast_executemany was set. Covers the engine URL, the generated DML, type mapping and Alembic. Driver choice is connect-from-python and retry connect-to-azure-sql. ## T-SQL correctness and patterns Where agents trained on PostgreSQL go wrong on Azure SQL Database -- [t-sql-correctness](https://github.com/microsoft/azure-sql-skills/blob/main/skills/t-sql-correctness/SKILL.md): Writes T-SQL that returns the right answer on Azure SQL Database, and catches statements that return a wrong answer with no error: NULL compared using = or <> or NOT IN, ISNULL and COALESCE differing in return type, integer division truncating, a string variable declared with no length, and a session where QUOTED_IDENTIFIER is OFF. Also corrects PostgreSQL and MySQL habit (LIMIT, RETURNING, SERIAL, ILIKE, NOW(), true, false, double-quoted literals, TEXT columns, ON CONFLICT, USE) and the opposite mistake of avoiding syntax supported since 2025. Use when writing, porting or reviewing SQL, and for "why is that row missing", "why did NOT IN return nothing", "why is this average wrong", "how do I paginate", "how do I get the id I just inserted", "is this comparison case sensitive". Upserts are t-sql-upserts-merge, JSON t-sql-json-and-openjson, table design design-azure-sql-schema. -- [t-sql-json-and-openjson](https://github.com/microsoft/azure-sql-skills/blob/main/skills/t-sql-json-and-openjson/SKILL.md): Queries and stores JSON on Azure SQL Database using the native json type, a JSON index, and OPENJSON with an explicit WITH schema, instead of the older nvarchar(max) plus JSON_VALUE pattern the training data is full of. Use when asked to "store JSON in SQL", "query a JSON column", "shred a JSON array into rows", "flatten this payload into a table", "index a JSON property", "should this be nvarchar(max) or the json type", "parse the API response we saved", or when JSON_VALUE, JSON_QUERY, JSON_MODIFY, ISJSON, OPENJSON, JSON_OBJECT or JSON_ARRAYAGG appears in a query being written or reviewed; and when a JSON lookup returns NULL for a value that is visibly present, or invalid JSON reached a column that nothing rejected. Where a document column belongs in a table design is design-azure-sql-schema, and general T-SQL dialect is t-sql-correctness. -- [t-sql-upserts-merge](https://github.com/microsoft/azure-sql-skills/blob/main/skills/t-sql-upserts-merge/SKILL.md): Writes an upsert for Azure SQL Database that is still correct when two sessions run it at the same moment, and refuses the MERGE shapes that lose rows. Use when asked to "insert or update", "insert if not exists", "add or update", "make this insert idempotent", "upsert", "write a MERGE", "sync a staging table into the target table", make a row-by-row load or import safe to run twice, or port ON CONFLICT DO UPDATE or ON DUPLICATE KEY UPDATE; and use when duplicate rows appear that nothing in the application created, or when error 2627, 2601, 8672, 10713 or a deadlock shows up under load. Covers why IF EXISTS then UPDATE ELSE INSERT is a race, what MERGE needs to be safe, which MERGE shapes to refuse outright, and the two patterns that are safe without MERGE. Key and index design belongs to design-azure-sql-schema, and general T-SQL dialect to t-sql-correctness. +- [t-sql-correctness](https://github.com/microsoft/microsoft-sql/blob/main/skills/t-sql-correctness/SKILL.md): Writes T-SQL that returns the right answer on Azure SQL Database, and catches statements that return a wrong answer with no error: NULL compared using = or <> or NOT IN, ISNULL and COALESCE differing in return type, integer division truncating, a string variable declared with no length, and a session where QUOTED_IDENTIFIER is OFF. Also corrects PostgreSQL and MySQL habit (LIMIT, RETURNING, SERIAL, ILIKE, NOW(), true, false, double-quoted literals, TEXT columns, ON CONFLICT, USE) and the opposite mistake of avoiding syntax supported since 2025. Use when writing, porting or reviewing SQL, and for "why is that row missing", "why did NOT IN return nothing", "why is this average wrong", "how do I paginate", "how do I get the id I just inserted", "is this comparison case sensitive". Upserts are t-sql-upserts-merge, JSON t-sql-json-and-openjson, table design design-azure-sql-schema. +- [t-sql-json-and-openjson](https://github.com/microsoft/microsoft-sql/blob/main/skills/t-sql-json-and-openjson/SKILL.md): Queries and stores JSON on Azure SQL Database using the native json type, a JSON index, and OPENJSON with an explicit WITH schema, instead of the older nvarchar(max) plus JSON_VALUE pattern the training data is full of. Use when asked to "store JSON in SQL", "query a JSON column", "shred a JSON array into rows", "flatten this payload into a table", "index a JSON property", "should this be nvarchar(max) or the json type", "parse the API response we saved", or when JSON_VALUE, JSON_QUERY, JSON_MODIFY, ISJSON, OPENJSON, JSON_OBJECT or JSON_ARRAYAGG appears in a query being written or reviewed; and when a JSON lookup returns NULL for a value that is visibly present, or invalid JSON reached a column that nothing rejected. Where a document column belongs in a table design is design-azure-sql-schema, and general T-SQL dialect is t-sql-correctness. +- [t-sql-upserts-merge](https://github.com/microsoft/microsoft-sql/blob/main/skills/t-sql-upserts-merge/SKILL.md): Writes an upsert for Azure SQL Database that is still correct when two sessions run it at the same moment, and refuses the MERGE shapes that lose rows. Use when asked to "insert or update", "insert if not exists", "add or update", "make this insert idempotent", "upsert", "write a MERGE", "sync a staging table into the target table", make a row-by-row load or import safe to run twice, or port ON CONFLICT DO UPDATE or ON DUPLICATE KEY UPDATE; and use when duplicate rows appear that nothing in the application created, or when error 2627, 2601, 8672, 10713 or a deadlock shows up under load. Covers why IF EXISTS then UPDATE ELSE INSERT is a race, what MERGE needs to be safe, which MERGE shapes to refuse outright, and the two patterns that are safe without MERGE. Key and index design belongs to design-azure-sql-schema, and general T-SQL dialect to t-sql-correctness. ## Identity and access (Entra ID) Passwordless by default, and unblock the setup that fails silently -- [entra-id-auth](https://github.com/microsoft/azure-sql-skills/blob/main/skills/entra-id-auth/SKILL.md): Takes an application identity to a passwordless connection to Azure SQL Database, and diagnoses it when that fails: sets the Microsoft Entra administrator, creates the database user for a managed identity or service principal, and grants roles. Use for "set up Microsoft Entra authentication for Azure SQL", "connect with a managed identity", "stop putting the database password in configuration", or "turn on Microsoft Entra-only authentication", and for the container once its MSSQL_AAD_ variables are set. Owns failures after a credential was evaluated: Msg 33134 "Principal could not be resolved", Msg 33131 "duplicate display name", 18456 "Login failed for user", 4060 "Cannot open database". What fails before that is diagnose-connection-errors; the connection code itself is connect-from-dotnet, connect-from-python or connect-from-typescript-and-node. +- [entra-id-auth](https://github.com/microsoft/microsoft-sql/blob/main/skills/entra-id-auth/SKILL.md): Takes an application identity to a passwordless connection to Azure SQL Database, and diagnoses it when that fails: sets the Microsoft Entra administrator, creates the database user for a managed identity or service principal, and grants roles. Use for "set up Microsoft Entra authentication for Azure SQL", "connect with a managed identity", "stop putting the database password in configuration", or "turn on Microsoft Entra-only authentication", and for the container once its MSSQL_AAD_ variables are set. Owns failures after a credential was evaluated: Msg 33134 "Principal could not be resolved", Msg 33131 "duplicate display name", 18456 "Login failed for user", 4060 "Cannot open database". What fails before that is diagnose-connection-errors; the connection code itself is connect-from-dotnet, connect-from-python or connect-from-typescript-and-node. ## Security and safe SQL Stop the agent writing the vulnerability, and lock the database down by default -- [prevent-sql-injection](https://github.com/microsoft/azure-sql-skills/blob/main/skills/prevent-sql-injection/SKILL.md): Handles SQL injection on Azure SQL Database beyond parameterisation: a typed sp_executesql parameter matches nothing where the same input concatenated into EXEC() returns every row; QUOTENAME returns NULL above 128 characters, so the batch built from it becomes NULL and does nothing; a dynamic ORDER BY built from one CASE over mixed types fails only for the sort key on the lower-precedence branch; dynamic SQL breaks the ownership chain, so EXECUTE AS decides what it may touch; and Always Encrypted refuses a literal (Msg 206). Use for a general injection question or a pre-production review, when a QUOTENAME-built statement returns and raises nothing, when a sort-by-column feature throws an operand type clash for one column only, when a procedure works until its query becomes dynamic, or when an encrypted column will not take a literal. Row level tenant isolation is rls-multi-tenant. -- [rls-multi-tenant](https://github.com/microsoft/azure-sql-skills/blob/main/skills/rls-multi-tenant/SKILL.md): Builds tenant isolation on Azure SQL Database that a test can prove, with a row level security policy whose filter predicate and block predicate are written together, because a filter alone still accepts a cross-tenant write and hides the row from the app that made it. Use when asked to add row level security, isolate tenants in a shared table, write a security policy or predicate function, set the current tenant through SESSION_CONTEXT or a database user per tenant, or prove one tenant cannot read another; and when a multi-tenant app returns the wrong tenant's rows under load, retrieval returns another tenant's chunk, a policy is in place and all rows are still visible, or error 33504 appears on an insert or update. Covers pooling against a session-scoped tenant id, who can turn a policy off, and the isolation test. Identity is entra-id-auth, the table design design-azure-sql-schema. +- [prevent-sql-injection](https://github.com/microsoft/microsoft-sql/blob/main/skills/prevent-sql-injection/SKILL.md): Handles SQL injection on Azure SQL Database beyond parameterisation: a typed sp_executesql parameter matches nothing where the same input concatenated into EXEC() returns every row; QUOTENAME returns NULL above 128 characters, so the batch built from it becomes NULL and does nothing; a dynamic ORDER BY built from one CASE over mixed types fails only for the sort key on the lower-precedence branch; dynamic SQL breaks the ownership chain, so EXECUTE AS decides what it may touch; and Always Encrypted refuses a literal (Msg 206). Use for a general injection question or a pre-production review, when a QUOTENAME-built statement returns and raises nothing, when a sort-by-column feature throws an operand type clash for one column only, when a procedure works until its query becomes dynamic, or when an encrypted column will not take a literal. Row level tenant isolation is rls-multi-tenant. +- [rls-multi-tenant](https://github.com/microsoft/microsoft-sql/blob/main/skills/rls-multi-tenant/SKILL.md): Builds tenant isolation on Azure SQL Database that a test can prove, with a row level security policy whose filter predicate and block predicate are written together, because a filter alone still accepts a cross-tenant write and hides the row from the app that made it. Use when asked to add row level security, isolate tenants in a shared table, write a security policy or predicate function, set the current tenant through SESSION_CONTEXT or a database user per tenant, or prove one tenant cannot read another; and when a multi-tenant app returns the wrong tenant's rows under load, retrieval returns another tenant's chunk, a policy is in place and all rows are still visible, or error 33504 appears on an insert or update. Covers pooling against a session-scoped tenant id, who can turn a policy off, and the isolation test. Identity is entra-id-auth, the table design design-azure-sql-schema. ## Schema change and CI/CD Ship schema changes safely across every migration tool developers actually use -- [github-actions-for-sql](https://github.com/microsoft/azure-sql-skills/blob/main/skills/github-actions-for-sql/SKILL.md): Ships schema changes to Azure SQL Database from a GitHub Actions workflow with `azure/sql-action`: building the database project or publishing a prebuilt dacpac, federating the workflow's token so no database password or client secret is stored, getting a runner with a changing address through the server firewall, and gating the deployment on an environment. Use when a user asks to "deploy my database project from GitHub Actions", "publish a dacpac on merge", "set up OIDC login to Azure for my pipeline", "stop storing a SQL password in secrets", or "require an approval before the schema deploys", and when a run fails with "no matching federated identity record found for presented assertion subject", a login error naming `auth-type`, or "unable to detect client IP address". sql-database-projects owns the project and publish options, entra-id-auth the database user and its grant. -- [schema-migrations-safely](https://github.com/microsoft/azure-sql-skills/blob/main/skills/schema-migrations-safely/SKILL.md): Decides whether a schema change is safe to apply to a live Azure SQL Database, and rewrites the migration so it is. Use when someone asks "is this migration safe to run in production", "can I add this column without downtime", "zero downtime schema change", "expand and contract", "blue green database deploy", "make this migration re-runnable", "should the app run migrations at startup", or "how do I roll this back"; and when a deployment blocked every query, instances fought over the same migration, or a retry applied its backfill twice. Covers metadata-only versus table-rewriting alterations, the schema lock that blocks readers under snapshot isolation, ONLINE and RESUMABLE, and why a guard is not a guard under concurrency or retry. Tooling is sql-database-projects and github-actions-for-sql, ORM migrations their own skills, the table design design-azure-sql-schema. -- [sql-database-projects](https://github.com/microsoft/azure-sql-skills/blob/main/skills/sql-database-projects/SKILL.md): Builds and publishes a SQL database project against Azure SQL Database: the SDK-style `.sqlproj` on `Microsoft.Build.Sql`, the target platform that decides what the build actually validates, pre and post deployment scripts, the refactorlog, and code analysis. Use when a user asks to "create a SQL database project", "build a dacpac", "publish a dacpac to Azure SQL", "add a post-deployment script", "rename a column without losing its data", or "turn on code analysis", and reports "the build passed but the publish failed", "the deploy said success and the data is gone", or "the post-deployment script failed and the table already changed". Covers what `dotnet build` does not check, what SqlPackage does with a mismatched target platform, and which publish options change data rather than schema. github-actions-for-sql owns the pipeline, schema-migrations-safely the change doctrine. +- [github-actions-for-sql](https://github.com/microsoft/microsoft-sql/blob/main/skills/github-actions-for-sql/SKILL.md): Ships schema changes to Azure SQL Database from a GitHub Actions workflow with `azure/sql-action`: building the database project or publishing a prebuilt dacpac, federating the workflow's token so no database password or client secret is stored, getting a runner with a changing address through the server firewall, and gating the deployment on an environment. Use when a user asks to "deploy my database project from GitHub Actions", "publish a dacpac on merge", "set up OIDC login to Azure for my pipeline", "stop storing a SQL password in secrets", or "require an approval before the schema deploys", and when a run fails with "no matching federated identity record found for presented assertion subject", a login error naming `auth-type`, or "unable to detect client IP address". sql-database-projects owns the project and publish options, entra-id-auth the database user and its grant. +- [schema-migrations-safely](https://github.com/microsoft/microsoft-sql/blob/main/skills/schema-migrations-safely/SKILL.md): Decides whether a schema change is safe to apply to a live Azure SQL Database, and rewrites the migration so it is. Use when someone asks "is this migration safe to run in production", "can I add this column without downtime", "zero downtime schema change", "expand and contract", "blue green database deploy", "make this migration re-runnable", "should the app run migrations at startup", or "how do I roll this back"; and when a deployment blocked every query, instances fought over the same migration, or a retry applied its backfill twice. Covers metadata-only versus table-rewriting alterations, the schema lock that blocks readers under snapshot isolation, ONLINE and RESUMABLE, and why a guard is not a guard under concurrency or retry. Tooling is sql-database-projects and github-actions-for-sql, ORM migrations their own skills, the table design design-azure-sql-schema. +- [sql-database-projects](https://github.com/microsoft/microsoft-sql/blob/main/skills/sql-database-projects/SKILL.md): Builds and publishes a SQL database project against Azure SQL Database: the SDK-style `.sqlproj` on `Microsoft.Build.Sql`, the target platform that decides what the build actually validates, pre and post deployment scripts, the refactorlog, and code analysis. Use when a user asks to "create a SQL database project", "build a dacpac", "publish a dacpac to Azure SQL", "add a post-deployment script", "rename a column without losing its data", or "turn on code analysis", and reports "the build passed but the publish failed", "the deploy said success and the data is gone", or "the post-deployment script failed and the table already changed". Covers what `dotnet build` does not check, what SqlPackage does with a mismatched target platform, and which publish options change data rather than schema. github-actions-for-sql owns the pipeline, schema-migrations-safely the change doctrine. ## Azure patterns and deploy Take a working local app to Azure the way Microsoft intends -- [deploy-app-to-azure](https://github.com/microsoft/azure-sql-skills/blob/main/skills/deploy-app-to-azure/SKILL.md): Takes a working local application and its Azure SQL Database to Azure with the Azure Developer CLI, reading its infrastructure rather than inheriting it. The one first-party template pairing a web app with Azure SQL Database uses a database password and grants db_owner, and the firewall rule it ships under an Azure services name spans the whole public address space. Use when a user says "deploy my app to Azure", "azd up", "which azd template should I start from", "get this into Azure without a password", or when a deployment reported success and the app then fails its first database call with a login failure. Covers what each template does about identity, what init, provision, deploy and up each do, and what teardown leaves behind. github-actions-for-sql owns pipelines, provision-azure-sql-db creating the server and database, entra-id-auth the database user and the grant. +- [deploy-app-to-azure](https://github.com/microsoft/microsoft-sql/blob/main/skills/deploy-app-to-azure/SKILL.md): Takes a working local application and its Azure SQL Database to Azure with the Azure Developer CLI, reading its infrastructure rather than inheriting it. The one first-party template pairing a web app with Azure SQL Database uses a database password and grants db_owner, and the firewall rule it ships under an Azure services name spans the whole public address space. Use when a user says "deploy my app to Azure", "azd up", "which azd template should I start from", "get this into Azure without a password", or when a deployment reported success and the app then fails its first database call with a login failure. Covers what each template does about identity, what init, provision, deploy and up each do, and what teardown leaves behind. github-actions-for-sql owns pipelines, provision-azure-sql-db creating the server and database, entra-id-auth the database user and the grant. ## APIs and application patterns Expose and consume the database over HTTP and from serverless, without hand-written plumbing -- [azure-functions-sql-bindings](https://github.com/microsoft/azure-sql-skills/blob/main/skills/azure-functions-sql-bindings/SKILL.md): Wires Azure Functions to Azure SQL Database with the SQL input and output bindings and the SQL trigger, including the change tracking the trigger cannot run without and the identity permissions the trigger needs beyond the ones the bindings need. Use when a user asks for "a serverless CRUD API over SQL", to "add a SQL input binding", "write to SQL from a function", "react to inserts and updates", "SQL trigger function", "SqlTrigger", "SqlInput", "SqlOutput", or says "my SQL trigger never fires and there is no error". Also use when an output binding silently updated an existing row instead of inserting, which is the documented upsert behaviour. This is the Azure SQL Database story; the same bindings against the local Azure SQL Database container belong to azuresql-db-functions, and connection reuse across invocations to the per-language connect skills. -- [build-app-on-azure-sql](https://github.com/microsoft/azure-sql-skills/blob/main/skills/build-app-on-azure-sql/SKILL.md): Sequences standing up a new application on Azure SQL Database and routes each decision to the skill that owns it. Use at the start of a project, when a user says "build an app on Azure SQL", "add Azure SQL Database to my app", "which stack should I use with Azure SQL", "where do I start", "generate an API over my database", or "get this into Azure without a password in the repo". It establishes the order that works: server-side prerequisites before any code, an identity instead of a password, schema through a migration not at startup, and a generated data API before hand-written CRUD. It routes rather than repeats: provision-azure-sql-db creates the database, connect-to-azure-sql drivers and retry, entra-id-auth the identity, dab-rest-and-graphql and azure-functions-sql-bindings the API layer, deploy-app-to-azure shipping, azuresql-db-scaffold the local container version. -- [dab-rest-and-graphql](https://github.com/microsoft/azure-sql-skills/blob/main/skills/dab-rest-and-graphql/SKILL.md): Decides what a Data API builder configuration on Azure SQL Database actually publishes and to whom, at the version 2.0 model: entities generated from patterns, roles that inherit upward, row-filtering policies, relationships, and the passwordless connection a hosted run needs. Use when Data API builder is already in play and the question is about "autoentities", "dab auto-config", "my dab-config.json has hundreds of entities", "why can anonymous read this entity", "restrict which rows a caller can see", "add a relationship to my config", or moving a working configuration to Azure SQL Database with a managed identity. Also use when a configuration reviews cleanly but serves more of the database than the author asked for, the default include pattern plus the Unauthenticated provider dab init writes. Standing a first endpoint up belongs to azuresql-db-dab. +- [azure-functions-sql-bindings](https://github.com/microsoft/microsoft-sql/blob/main/skills/azure-functions-sql-bindings/SKILL.md): Wires Azure Functions to Azure SQL Database with the SQL input and output bindings and the SQL trigger, including the change tracking the trigger cannot run without and the identity permissions the trigger needs beyond the ones the bindings need. Use when a user asks for "a serverless CRUD API over SQL", to "add a SQL input binding", "write to SQL from a function", "react to inserts and updates", "SQL trigger function", "SqlTrigger", "SqlInput", "SqlOutput", or says "my SQL trigger never fires and there is no error". Also use when an output binding silently updated an existing row instead of inserting, which is the documented upsert behaviour. This is the Azure SQL Database story; the same bindings against the local Azure SQL Database container belong to azuresql-db-functions, and connection reuse across invocations to the per-language connect skills. +- [build-app-on-azure-sql](https://github.com/microsoft/microsoft-sql/blob/main/skills/build-app-on-azure-sql/SKILL.md): Sequences standing up a new application on Azure SQL Database and routes each decision to the skill that owns it. Use at the start of a project, when a user says "build an app on Azure SQL", "add Azure SQL Database to my app", "which stack should I use with Azure SQL", "where do I start", "generate an API over my database", or "get this into Azure without a password in the repo". It establishes the order that works: server-side prerequisites before any code, an identity instead of a password, schema through a migration not at startup, and a generated data API before hand-written CRUD. It routes rather than repeats: provision-azure-sql-db creates the database, connect-to-azure-sql drivers and retry, entra-id-auth the identity, dab-rest-and-graphql and azure-functions-sql-bindings the API layer, deploy-app-to-azure shipping, azuresql-db-scaffold the local container version. +- [dab-rest-and-graphql](https://github.com/microsoft/microsoft-sql/blob/main/skills/dab-rest-and-graphql/SKILL.md): Decides what a Data API builder configuration on Azure SQL Database actually publishes and to whom, at the version 2.0 model: entities generated from patterns, roles that inherit upward, row-filtering policies, relationships, and the passwordless connection a hosted run needs. Use when Data API builder is already in play and the question is about "autoentities", "dab auto-config", "my dab-config.json has hundreds of entities", "why can anonymous read this entity", "restrict which rows a caller can see", "add a relationship to my config", or moving a working configuration to Azure SQL Database with a managed identity. Also use when a configuration reviews cleanly but serves more of the database than the author asked for, the default include pattern plus the Unauthenticated provider dab init writes. Standing a first endpoint up belongs to azuresql-db-dab. ## AI, vector and RAG Build, run and debug AI features directly on SQL, locally and in the cloud -- [embeddings-and-external-models](https://github.com/microsoft/azure-sql-skills/blob/main/skills/embeddings-and-external-models/SKILL.md): Generates embeddings and chunks inside Azure SQL Database with CREATE EXTERNAL MODEL, AI_GENERATE_EMBEDDINGS, AI_GENERATE_CHUNKS and sp_invoke_external_rest_endpoint, covering the database scoped credential naming rule, the permissions, the dimension budget that decides which embedding model fits, and the outbound allowlist. Use when someone asks to "create an external model", "call AI_GENERATE_EMBEDDINGS", "embed text in T-SQL", "chunk text in the database", or "call an Azure OpenAI endpoint from SQL"; when such a call fails on the credential secret, managed identity, permissions, HTTPS or a blocked domain; and when embedding a whole table in one statement runs for hours. This skill owns producing the vector and calling out of the engine; storing and searching it is vector-search-azure-sql, the pipeline around it is rag-on-azure-sql, and embedding offline is rag-local-with-container. -- [langchain-and-llamaindex-on-azure-sql](https://github.com/microsoft/azure-sql-skills/blob/main/skills/langchain-and-llamaindex-on-azure-sql/SKILL.md): Wires LangChain or LlamaIndex to Azure SQL Database from Python: the SQL toolkits, their text to SQL prompts, the langchain-sqlserver vector store, and the guardrails neither framework enforces. Use when someone asks to "use LangChain with Azure SQL", "build a SQL agent over the database", "text to SQL", "SQLDatabaseToolkit", "NLSQLTableQueryEngine", "which LlamaIndex vector store works with Azure SQL", or "make the SQL agent read only"; when a SQL agent keeps generating LIMIT, its query checker approves a query the database refuses, or its schema tool puts real rows into the prompt; or when a framework-created embedding table refuses CREATE VECTOR INDEX or a metadata filter throws arithmetic overflow. Vector type and query shape are vector-search-azure-sql, the cloud pipeline rag-on-azure-sql, the offline loop rag-local-with-container, and drivers and token auth connect-from-python. -- [rag-local-with-container](https://github.com/microsoft/azure-sql-skills/blob/main/skills/rag-local-with-container/SKILL.md): Answers whether a retrieval augmented generation prototype proved on the local Azure SQL Database container still holds in Azure SQL Database, and names what does not survive the move. Owns the offline loop, the local embedding model, and the parity claim. Use when someone asks to "prototype RAG offline with no cloud account", "use a local embedding model with SQL", "develop against the container and deploy to Azure SQL Database", or asks what has to be redone after the move; and when the engine refuses a local embedding endpoint, or a vector index and a security policy will not coexist. A plain request to build RAG on the container belongs to azuresql-db-rag; come here for the move. The cloud pipeline is rag-on-azure-sql, the type and the query vector-search-azure-sql, embedding in the engine embeddings-and-external-models, framework wiring langchain-and-llamaindex-on-azure-sql. -- [rag-on-azure-sql](https://github.com/microsoft/azure-sql-skills/blob/main/skills/rag-on-azure-sql/SKILL.md): Builds retrieval augmented generation end to end on Azure SQL Database: chunking source text, storing embeddings with the provenance that makes them re-runnable, retrieving with the filter and the permission check inside the same query, and grounding an answer on what came back. Use when someone asks to "build RAG on Azure SQL Database", "chat with my documents", "add semantic search over my data", "keep embeddings in sync when rows change", "re-embed with a new model", or "which chunks should I put in the prompt"; and when a retrieval pipeline returns plausible but wrong context, or returns text the asking user is not allowed to read. This skill owns the pipeline and the schema around it. The vector type, VECTOR_DISTANCE and the query shape are vector-search-azure-sql, the embedding call embeddings-and-external-models, the offline container path rag-local-with-container. -- [vector-search-azure-sql](https://github.com/microsoft/azure-sql-skills/blob/main/skills/vector-search-azure-sql/SKILL.md): Stores and searches vectors natively in Azure SQL Database: the vector type, VECTOR_DISTANCE, the 1998 dimension ceiling, the DiskANN vector index, and the long list of places a vector column is refused. Use when a schema needs an embedding column, when someone asks to "store embeddings in SQL", "do similarity search", "cosine distance", "top k nearest neighbours", "CREATE VECTOR INDEX", "VECTOR_SEARCH" or "WITH APPROXIMATE"; when a vector column is rejected as a key, a constraint, a computed column or inside ORDER BY, GROUP BY, DISTINCT or UNION; and when a similarity query returns the right rows but scans the whole table. This skill owns the type and the query surface. The end to end pipeline is rag-on-azure-sql, generating embeddings embeddings-and-external-models, and a vector column's place in a wider design design-azure-sql-schema. +- [embeddings-and-external-models](https://github.com/microsoft/microsoft-sql/blob/main/skills/embeddings-and-external-models/SKILL.md): Generates embeddings and chunks inside Azure SQL Database with CREATE EXTERNAL MODEL, AI_GENERATE_EMBEDDINGS, AI_GENERATE_CHUNKS and sp_invoke_external_rest_endpoint, covering the database scoped credential naming rule, the permissions, the dimension budget that decides which embedding model fits, and the outbound allowlist. Use when someone asks to "create an external model", "call AI_GENERATE_EMBEDDINGS", "embed text in T-SQL", "chunk text in the database", or "call an Azure OpenAI endpoint from SQL"; when such a call fails on the credential secret, managed identity, permissions, HTTPS or a blocked domain; and when embedding a whole table in one statement runs for hours. This skill owns producing the vector and calling out of the engine; storing and searching it is vector-search-azure-sql, the pipeline around it is rag-on-azure-sql, and embedding offline is rag-local-with-container. +- [langchain-and-llamaindex-on-azure-sql](https://github.com/microsoft/microsoft-sql/blob/main/skills/langchain-and-llamaindex-on-azure-sql/SKILL.md): Wires LangChain or LlamaIndex to Azure SQL Database from Python: the SQL toolkits, their text to SQL prompts, the langchain-sqlserver vector store, and the guardrails neither framework enforces. Use when someone asks to "use LangChain with Azure SQL", "build a SQL agent over the database", "text to SQL", "SQLDatabaseToolkit", "NLSQLTableQueryEngine", "which LlamaIndex vector store works with Azure SQL", or "make the SQL agent read only"; when a SQL agent keeps generating LIMIT, its query checker approves a query the database refuses, or its schema tool puts real rows into the prompt; or when a framework-created embedding table refuses CREATE VECTOR INDEX or a metadata filter throws arithmetic overflow. Vector type and query shape are vector-search-azure-sql, the cloud pipeline rag-on-azure-sql, the offline loop rag-local-with-container, and drivers and token auth connect-from-python. +- [rag-local-with-container](https://github.com/microsoft/microsoft-sql/blob/main/skills/rag-local-with-container/SKILL.md): Answers whether a retrieval augmented generation prototype proved on the local Azure SQL Database container still holds in Azure SQL Database, and names what does not survive the move. Owns the offline loop, the local embedding model, and the parity claim. Use when someone asks to "prototype RAG offline with no cloud account", "use a local embedding model with SQL", "develop against the container and deploy to Azure SQL Database", or asks what has to be redone after the move; and when the engine refuses a local embedding endpoint, or a vector index and a security policy will not coexist. A plain request to build RAG on the container belongs to azuresql-db-rag; come here for the move. The cloud pipeline is rag-on-azure-sql, the type and the query vector-search-azure-sql, embedding in the engine embeddings-and-external-models, framework wiring langchain-and-llamaindex-on-azure-sql. +- [rag-on-azure-sql](https://github.com/microsoft/microsoft-sql/blob/main/skills/rag-on-azure-sql/SKILL.md): Builds retrieval augmented generation end to end on Azure SQL Database: chunking source text, storing embeddings with the provenance that makes them re-runnable, retrieving with the filter and the permission check inside the same query, and grounding an answer on what came back. Use when someone asks to "build RAG on Azure SQL Database", "chat with my documents", "add semantic search over my data", "keep embeddings in sync when rows change", "re-embed with a new model", or "which chunks should I put in the prompt"; and when a retrieval pipeline returns plausible but wrong context, or returns text the asking user is not allowed to read. This skill owns the pipeline and the schema around it. The vector type, VECTOR_DISTANCE and the query shape are vector-search-azure-sql, the embedding call embeddings-and-external-models, the offline container path rag-local-with-container. +- [vector-search-azure-sql](https://github.com/microsoft/microsoft-sql/blob/main/skills/vector-search-azure-sql/SKILL.md): Stores and searches vectors natively in Azure SQL Database: the vector type, VECTOR_DISTANCE, the 1998 dimension ceiling, the DiskANN vector index, and the long list of places a vector column is refused. Use when a schema needs an embedding column, when someone asks to "store embeddings in SQL", "do similarity search", "cosine distance", "top k nearest neighbours", "CREATE VECTOR INDEX", "VECTOR_SEARCH" or "WITH APPROXIMATE"; when a vector column is rejected as a key, a constraint, a computed column or inside ORDER BY, GROUP BY, DISTINCT or UNION; and when a similarity query returns the right rows but scans the whole table. This skill owns the type and the query surface. The end to end pipeline is rag-on-azure-sql, generating embeddings embeddings-and-external-models, and a vector column's place in a wider design design-azure-sql-schema. ## Performance and diagnostics When something is slow, stuck or throttled, give the agent the playbook -- [capture-with-extended-events](https://github.com/microsoft/azure-sql-skills/blob/main/skills/capture-with-extended-events/SKILL.md): Creates, starts, reads back and drops a database-scoped Extended Events session on Azure SQL Database, and names the ways one reports success while capturing nothing. Use when someone asks to capture query text, blocking or deadlocks with Extended Events, XEvents or an XE session on Azure SQL Database, pastes a session that ran without error and left an empty ring buffer, or has a session that never fires. Covers ON DATABASE scope and the error ON SERVER raises, the ring buffer shredded from XML into a rowset, the event_file target's need for a blob URL and a matching credential, the events and actions the service refuses, and the absence of a built-in system_health session. Does not diagnose slow queries, blocking or resource pressure once the data exists (diagnose-slow-query, diagnose-blocking-and-deadlocks, diagnose-resource-pressure) or read a plan (read-execution-plan). -- [diagnose-blocking-and-deadlocks](https://github.com/microsoft/azure-sql-skills/blob/main/skills/diagnose-blocking-and-deadlocks/SKILL.md): Finds who is blocking whom on Azure SQL Database right now, and reads a completed deadlock graph out of the database-scoped Extended Events session that captured it. Use when someone reports a query or app that hangs under load, pastes "Msg 1205" or "was deadlocked on lock resources", asks who is blocking a session, or ran a blocking query that came back empty and assumed nothing was blocked. Covers which grant a login needs to see another session's blocking and why that differs on Basic, S0, S1 and elastic pools, why an idle session holding a transaction is a head blocker that never appears in sys.dm_exec_requests, and how optimized locking's wait types differ. Does not tune an unblocked query (diagnose-slow-query), diagnose CPU, memory or IO pressure (diagnose-resource-pressure), build or repair the session (capture-with-extended-events) or read the plan (read-execution-plan). -- [diagnose-resource-pressure](https://github.com/microsoft/azure-sql-skills/blob/main/skills/diagnose-resource-pressure/SKILL.md): Answers whether an Azure SQL Database is slow because of CPU, data or log IO, memory, or a worker and session limit. Use when someone reports the database as slow, throttled or timing out under load, pastes a resource governance error such as "the request limit for the database is 200 and has been reached" or a raw error number 10928, 10929 or 10936, asks whether to scale up the service tier, or is reading sys.dm_db_resource_stats, sys.dm_os_performance_counters or sys.dm_os_wait_stats. Covers the local Azure SQL Database container too. Does not read an execution plan (read-execution-plan), diagnose a blocking chain (diagnose-blocking-and-deadlocks), rewrite a slow query (diagnose-slow-query), resolve a connection failure (diagnose-connection-errors), size a connection pool (connect-to-azure-sql) or speed up a bulk load (bulk-load-and-bulk-copy). -- [diagnose-slow-query](https://github.com/microsoft/azure-sql-skills/blob/main/skills/diagnose-slow-query/SKILL.md): Triages a slow Azure SQL Database query into one of four causes before anyone touches an index or a service tier: volatile, duration swings across executions; blocked, waiting on another session; regressed, a worse plan replaced a good one; or growing, duration rises with data volume. Reads Query Store runtime stats, plan history and per-plan waits, and knows where AUTO capture mode silently drops the query asked about. Use when a query "used to be fast" or runs inconsistently: "this took a second yesterday and ten today", "sometimes it's fast and sometimes it isn't", "did last night's deployment make this slower". Ends in a diagnosis, not a fix: CPU, memory, IO and tier go to diagnose-resource-pressure, blocking and deadlocks to diagnose-blocking-and-deadlocks, the plan itself to read-execution-plan, a query Query Store missed to capture-with-extended-events. -- [read-execution-plan](https://github.com/microsoft/azure-sql-skills/blob/main/skills/read-execution-plan/SKILL.md): Retrieves an Azure SQL Database execution plan, estimated or actual, and pulls out the small set of facts that explain slowness: operators, estimated versus actual row counts, warnings, missing-index hints, and the memory grant, instead of returning the whole plan XML. Use when someone says "read this execution plan", "why did the optimizer choose a scan here", "show me the actual plan not the estimated one", or hands over a plan and asks what is wrong with it. Also covers retrieval itself: SET SHOWPLAN_XML, SET STATISTICS XML, the plan-handle views, and Query Store, and the several ways a same-looking call returns the wrong kind of plan, a stub, or NULL without raising an error. Not general slow-query triage (diagnose-slow-query), lock analysis (diagnose-blocking-and-deadlocks), or instance-level CPU or memory pressure (diagnose-resource-pressure). +- [capture-with-extended-events](https://github.com/microsoft/microsoft-sql/blob/main/skills/capture-with-extended-events/SKILL.md): Creates, starts, reads back and drops a database-scoped Extended Events session on Azure SQL Database, and names the ways one reports success while capturing nothing. Use when someone asks to capture query text, blocking or deadlocks with Extended Events, XEvents or an XE session on Azure SQL Database, pastes a session that ran without error and left an empty ring buffer, or has a session that never fires. Covers ON DATABASE scope and the error ON SERVER raises, the ring buffer shredded from XML into a rowset, the event_file target's need for a blob URL and a matching credential, the events and actions the service refuses, and the absence of a built-in system_health session. Does not diagnose slow queries, blocking or resource pressure once the data exists (diagnose-slow-query, diagnose-blocking-and-deadlocks, diagnose-resource-pressure) or read a plan (read-execution-plan). +- [diagnose-blocking-and-deadlocks](https://github.com/microsoft/microsoft-sql/blob/main/skills/diagnose-blocking-and-deadlocks/SKILL.md): Finds who is blocking whom on Azure SQL Database right now, and reads a completed deadlock graph out of the database-scoped Extended Events session that captured it. Use when someone reports a query or app that hangs under load, pastes "Msg 1205" or "was deadlocked on lock resources", asks who is blocking a session, or ran a blocking query that came back empty and assumed nothing was blocked. Covers which grant a login needs to see another session's blocking and why that differs on Basic, S0, S1 and elastic pools, why an idle session holding a transaction is a head blocker that never appears in sys.dm_exec_requests, and how optimized locking's wait types differ. Does not tune an unblocked query (diagnose-slow-query), diagnose CPU, memory or IO pressure (diagnose-resource-pressure), build or repair the session (capture-with-extended-events) or read the plan (read-execution-plan). +- [diagnose-resource-pressure](https://github.com/microsoft/microsoft-sql/blob/main/skills/diagnose-resource-pressure/SKILL.md): Answers whether an Azure SQL Database is slow because of CPU, data or log IO, memory, or a worker and session limit. Use when someone reports the database as slow, throttled or timing out under load, pastes a resource governance error such as "the request limit for the database is 200 and has been reached" or a raw error number 10928, 10929 or 10936, asks whether to scale up the service tier, or is reading sys.dm_db_resource_stats, sys.dm_os_performance_counters or sys.dm_os_wait_stats. Covers the local Azure SQL Database container too. Does not read an execution plan (read-execution-plan), diagnose a blocking chain (diagnose-blocking-and-deadlocks), rewrite a slow query (diagnose-slow-query), resolve a connection failure (diagnose-connection-errors), size a connection pool (connect-to-azure-sql) or speed up a bulk load (bulk-load-and-bulk-copy). +- [diagnose-slow-query](https://github.com/microsoft/microsoft-sql/blob/main/skills/diagnose-slow-query/SKILL.md): Triages a slow Azure SQL Database query into one of four causes before anyone touches an index or a service tier: volatile, duration swings across executions; blocked, waiting on another session; regressed, a worse plan replaced a good one; or growing, duration rises with data volume. Reads Query Store runtime stats, plan history and per-plan waits, and knows where AUTO capture mode silently drops the query asked about. Use when a query "used to be fast" or runs inconsistently: "this took a second yesterday and ten today", "sometimes it's fast and sometimes it isn't", "did last night's deployment make this slower". Ends in a diagnosis, not a fix: CPU, memory, IO and tier go to diagnose-resource-pressure, blocking and deadlocks to diagnose-blocking-and-deadlocks, the plan itself to read-execution-plan, a query Query Store missed to capture-with-extended-events. +- [read-execution-plan](https://github.com/microsoft/microsoft-sql/blob/main/skills/read-execution-plan/SKILL.md): Retrieves an Azure SQL Database execution plan, estimated or actual, and pulls out the small set of facts that explain slowness: operators, estimated versus actual row counts, warnings, missing-index hints, and the memory grant, instead of returning the whole plan XML. Use when someone says "read this execution plan", "why did the optimizer choose a scan here", "show me the actual plan not the estimated one", or hands over a plan and asks what is wrong with it. Also covers retrieval itself: SET SHOWPLAN_XML, SET STATISTICS XML, the plan-handle views, and Query Store, and the several ways a same-looking call returns the wrong kind of plan, a stub, or NULL without raising an error. Not general slow-query triage (diagnose-slow-query), lock analysis (diagnose-blocking-and-deadlocks), or instance-level CPU or memory pressure (diagnose-resource-pressure). ## Operate and recover For the developer handed a database, using only what Azure SQL actually has -- [restore-and-recover](https://github.com/microsoft/azure-sql-skills/blob/main/skills/restore-and-recover/SKILL.md): Recovers an Azure SQL Database after data loss, an accidental drop or a bad deployment, using point-in-time restore, geo-restore and long-term retention. Use when someone asks to "restore my Azure SQL database", "undo a dropped table or database", "roll back to before this migration ran", "recover from a region outage", or asks for RESTORE DATABASE or BACKUP DATABASE syntax. There is no backup or restore T-SQL here: BACKUP DATABASE, RESTORE DATABASE and every RESTORE ... ONLY variant are refused, and restoring is a control plane operation. Every restore creates a new database beside the one being recovered rather than overwriting it, so this covers the restore type and the rename or connection swap back. Not a schema rollback (schema-migrations-safely), not a logical export or import (sqlpackage-import-export), not creating it (provision-azure-sql-db). +- [restore-and-recover](https://github.com/microsoft/microsoft-sql/blob/main/skills/restore-and-recover/SKILL.md): Recovers an Azure SQL Database after data loss, an accidental drop or a bad deployment, using point-in-time restore, geo-restore and long-term retention. Use when someone asks to "restore my Azure SQL database", "undo a dropped table or database", "roll back to before this migration ran", "recover from a region outage", or asks for RESTORE DATABASE or BACKUP DATABASE syntax. There is no backup or restore T-SQL here: BACKUP DATABASE, RESTORE DATABASE and every RESTORE ... ONLY variant are refused, and restoring is a control plane operation. Every restore creates a new database beside the one being recovered rather than overwriting it, so this covers the restore type and the rename or connection swap back. Not a schema rollback (schema-migrations-safely), not a logical export or import (sqlpackage-import-export), not creating it (provision-azure-sql-db). ## Data movement Get data in, out and between databases with the tools that actually exist on this platform -- [bulk-load-and-bulk-copy](https://github.com/microsoft/azure-sql-skills/blob/main/skills/bulk-load-and-bulk-copy/SKILL.md): Loads data into Azure SQL Database fast by choosing the right route: BULK INSERT and OPENROWSET(BULK ...) from Azure Blob Storage, bcp, .NET SqlBulkCopy, and the Python and Node.js bulk-copy equivalents. Use when someone says "bulk insert", "bulk load a CSV", "bcp in", "OPENROWSET BULK", "load a file into a table fast", "SqlBulkCopy", "fast_executemany", or pastes the error "OPENROWSET is not allowed to read local files" (Msg 12713) or a load stuck on a LOG_RATE_GOVERNOR wait. Covers choosing between the Blob-only server-side paths and the client-side paths, and the log rate cap that throttles every one of them regardless of logging mode. Does not design the target table (design-azure-sql-schema), establish the connection (connect-from-python, connect-from-dotnet, connect-from-typescript-and-node) or run a DACPAC or BACPAC export or import (sqlpackage-import-export). -- [sqlpackage-import-export](https://github.com/microsoft/azure-sql-skills/blob/main/skills/sqlpackage-import-export/SKILL.md): Moves a whole Azure SQL Database as a portable file with SqlPackage, choosing between the Extract, Publish, Export and Import actions, stating what each one carries, and giving the command line for each. Use when asked to export a database to a bacpac, extract or publish a dacpac, clone or move a database between servers, move the database itself from the local Azure SQL Database container up to Azure SQL Database, explain dacpac versus bacpac, or diagnose a failed sqlpackage run such as SQL71627, or SQL71659 when an Import stops because the target database is not empty. Making the application code run unchanged in the cloud is azuresql-db-local-to-cloud, and a first bacpac into the local container is azuresql-db-import. +- [bulk-load-and-bulk-copy](https://github.com/microsoft/microsoft-sql/blob/main/skills/bulk-load-and-bulk-copy/SKILL.md): Loads data into Azure SQL Database fast by choosing the right route: BULK INSERT and OPENROWSET(BULK ...) from Azure Blob Storage, bcp, .NET SqlBulkCopy, and the Python and Node.js bulk-copy equivalents. Use when someone says "bulk insert", "bulk load a CSV", "bcp in", "OPENROWSET BULK", "load a file into a table fast", "SqlBulkCopy", "fast_executemany", or pastes the error "OPENROWSET is not allowed to read local files" (Msg 12713) or a load stuck on a LOG_RATE_GOVERNOR wait. Covers choosing between the Blob-only server-side paths and the client-side paths, and the log rate cap that throttles every one of them regardless of logging mode. Does not design the target table (design-azure-sql-schema), establish the connection (connect-from-python, connect-from-dotnet, connect-from-typescript-and-node) or run a DACPAC or BACPAC export or import (sqlpackage-import-export). +- [sqlpackage-import-export](https://github.com/microsoft/microsoft-sql/blob/main/skills/sqlpackage-import-export/SKILL.md): Moves a whole Azure SQL Database as a portable file with SqlPackage, choosing between the Extract, Publish, Export and Import actions, stating what each one carries, and giving the command line for each. Use when asked to export a database to a bacpac, extract or publish a dacpac, clone or move a database between servers, move the database itself from the local Azure SQL Database container up to Azure SQL Database, explain dacpac versus bacpac, or diagnose a failed sqlpackage run such as SQL71627, or SQL71659 when an Import stops because the target database is not empty. Making the application code run unchanged in the cloud is azuresql-db-local-to-cloud, and a first bacpac into the local container is azuresql-db-import. ## Azure SQL Database container Local-first development against the same engine that runs in the cloud -- [azuresql-db-auth](https://github.com/microsoft/azure-sql-skills/blob/main/skills/azuresql-db-auth/SKILL.md): Connects an app to the Azure SQL Database container securely, with a least-privilege database user instead of the sa login, the right auth method per environment, and safe handling of the connection secret. Use when a user asks "don't use sa in my app", "create a least-privilege database user", "app login for SQL", "which authentication should my app use", "secure the connection string", "Encrypt / TrustServerCertificate", "store the connection string in Key Vault", "dotnet user-secrets", "managed identity for Azure SQL", or "grant only the roles my app needs". SQL auth locally, Microsoft Entra or managed identity in the cloud, changing only the connection string. Reach for this before wiring an app to connect as sa, or before committing a connection string to source. -- [azuresql-db-ci](https://github.com/microsoft/azure-sql-skills/blob/main/skills/azuresql-db-ci/SKILL.md): Runs integration tests against the Azure SQL Database container (Private Preview, local engine) in CI. Use when setting up GitHub Actions, Azure Pipelines, or GitLab CI to test against Azure SQL DB; when adding a database service container to a CI workflow; when tests need a real Azure SQL engine in the pipeline; or when you see "service container", "health-cmd", "ACR_USERNAME/ACR_PASSWORD", "MSSQL_SA_PASSWORD secret", or "integration test database". Also use when a workflow was about to pull the SQL Server image mcr.microsoft.com/mssql/server, in which case stop and use the Azure SQL Database engine image instead. Covers pulling from the private ACR with credentials, the service health check that runs sqlcmd inside the container so the runner needs no client tools, provisioning appdb before tests, and pointing the test connection string at the user database not master. -- [azuresql-db-connections](https://github.com/microsoft/azure-sql-skills/blob/main/skills/azuresql-db-connections/SKILL.md): Makes an app's database connections reliable against the local Azure SQL Database container (Private Preview) and, unchanged, against Azure SQL Database in the cloud: connection pooling plus retry/transient-fault handling. Use when the user mentions "connection pooling", "retry logic", "transient fault", "retry on transient error", "EnableRetryOnFailure", "connection resiliency", "reliable connections", "pool size", "Max Pool Size", or says "the connection keeps dropping", "connections time out under load", "add backoff", or "make the DB layer resilient". This is the Azure SQL engine (EngineEdition 5), not the mssql/server SQL Server image. Reach for this whenever hardening a data-access layer that talks to SQL Server or Azure SQL. -- [azuresql-db-container](https://github.com/microsoft/azure-sql-skills/blob/main/skills/azuresql-db-container/SKILL.md): Runs the Azure SQL Database container locally (Private Preview): the real PaaS engine where SERVERPROPERTY('EngineEdition') returns 5. This is NOT the SQL Server image mcr.microsoft.com/mssql/server. Use when a user wants to "run Azure SQL locally", "add a local SQL database", "add SQL Server to my docker compose", "spin up a local mssql container", "local SQL for development or CI", "connect with sqlcmd", "use Podman for SQL", "SQL container won't start", "Microsoft Entra authentication on the container", "MSSQL_AAD_CLIENT_ID", or asks "what's the connection string". Use even when the user does not name the container. If you were about to use mcr.microsoft.com/mssql/server, stop and use this skill instead. Hub skill: owns the shared references and routes to the task skills for compose, CI, seeding, vectors, and connection strings. -- [azuresql-db-dab](https://github.com/microsoft/azure-sql-skills/blob/main/skills/azuresql-db-dab/SKILL.md): Stands up an instant no-code REST + GraphQL API over the local Azure SQL Database container using Microsoft Data API Builder (DAB). Use when a user wants to "expose my table as an API", "add a REST API over the database", "generate a GraphQL API", "put an API in front of SQL", "CRUD API without writing code", or "dab init / dab-config.json". Also the way to serve a built-in MCP endpoint FROM the database via DAB (an API surface DAB provides, not a separate SQL MCP server). Prefer this over hand-writing a controller/ORM API when the user just needs REST or GraphQL over existing tables. Triggers include "Data API Builder", "dab start", "instant API over Azure SQL", "expose entities as REST/GraphQL". Reach for this even when the user only says "give me an API for this database". -- [azuresql-db-faq](https://github.com/microsoft/azure-sql-skills/blob/main/skills/azuresql-db-faq/SKILL.md): Answers questions about what the Azure SQL Database container (Private Preview) can and cannot do, and WHY it differs from Azure SQL Database in the Microsoft Azure cloud. Use when a user asks "can I take a backup", "why does USE fail", "is X supported", "why can't I create a vector index", "why does SSMS error", "why isn't the image on Docker Hub", "what's different from the cloud", or hits behavior that does not match their Azure SQL Database expectations. Do NOT guess from general SQL Server / Azure knowledge: the container is a Private Preview product with specific gaps and a specific connection model. Read this skill, and link the user to the live Known limitations page for the current full list. -- [azuresql-db-feedback](https://github.com/microsoft/azure-sql-skills/blob/main/skills/azuresql-db-feedback/SKILL.md): Reports a bug or files feedback about the azuresql-db-* agent skills themselves, or about the Azure SQL Database container (Private Preview). Use when the user says a skill or the container "did not work", hit an error, behaved unexpectedly, or is missing something; and when they say "report a bug", "file an issue", "open a GitHub issue", "request a feature", "give feedback", or "tell the team". Also use when you, the agent, had to deviate from an azuresql-db-* skill or work around a defect in one to finish a task: that is a bug worth reporting even if the task succeeded. Decides whether the problem belongs to the SKILL or to the CONTAINER, since they use different issue templates, then builds a complete prefilled GitHub issue from context you already have. Never submits anything without explicit confirmation from the user. -- [azuresql-db-from-sql-server](https://github.com/microsoft/azure-sql-skills/blob/main/skills/azuresql-db-from-sql-server/SKILL.md): Migrates a local SQL Server setup to the Azure SQL Database container for Azure-faithful local development. Use when a project already uses mcr.microsoft.com/mssql/server, mssql/server, an sqlcmd plus SA password docker setup, a "SQL Server in docker" or "local mssql container", or a docker-compose with the mssql/server image; and use when the user asks for "SQL Server locally", "run mssql in Docker", "spin up a local SQL database", or "test against SQL Server" but actually wants the Azure SQL Database engine (EngineEdition 5). Detects the SQL Server image, rewrites it to the Azure SQL Database container, adds --platform on non-x64 hosts, keeps the SA login, flags SQL Server-only features (SQL Agent, FILESTREAM, full Service Broker, cross-server distributed transactions, Windows Auth), and re-points connection strings from master to a provisioned user database. -- [azuresql-db-functions](https://github.com/microsoft/azure-sql-skills/blob/main/skills/azuresql-db-functions/SKILL.md): Builds a serverless API and event-driven handlers over the local Azure SQL Database container using Azure Functions with the Azure SQL bindings. Use when a user wants "a serverless API over SQL", "Azure Functions with a database", "HTTP CRUD with SQL input/output bindings", "run code when a row changes", "react to inserts/updates/deletes", "event-driven on Azure SQL", or "SQL trigger function". The Azure SQL trigger binding (backed by Change Tracking) is the local event-driven mechanism; Change Event Streaming (CES) is cloud-only and cannot run against the local container. Triggers include "func start with SQL", "SqlTrigger", "SqlInput/SqlOutput binding", "local.settings.json SqlConnectionString". Reach for this when building serverless endpoints or change-driven logic on the local Azure SQL engine. -- [azuresql-db-import](https://github.com/microsoft/azure-sql-skills/blob/main/skills/azuresql-db-import/SKILL.md): Imports an existing Azure SQL Database or SQL Server schema and data INTO the local Azure SQL Database container using SqlPackage. Use when asked to "import a bacpac", "load my existing database locally", "restore a dacpac into the container", "bring my prod schema into the dev container", "run my .bacpac/.dacpac against the local Azure SQL engine", or migrate an existing database into the preview container. Handles provisioning the target database on master first, then running SqlPackage /Action:Import against the provisioned user database. Use this for any "get my real database running in the container" request instead of hand-writing SqlPackage flags. -- [azuresql-db-local-to-cloud](https://github.com/microsoft/azure-sql-skills/blob/main/skills/azuresql-db-local-to-cloud/SKILL.md): Proves that code built and tested against the local Azure SQL Database container runs unchanged against Azure SQL Database in the cloud, with only the connection string changing. Use when a user wants to develop locally then deploy to the cloud, asks "will this work in Azure", "same code local and cloud", "promote to Azure SQL", "swap the connection string", "dev/prod parity", "local to cloud", or is wiring SQL_CONNECTION_STRING for an app that must target both the container and a cloud server. Use this when an app uses local SA auth but needs Microsoft Entra auth in the cloud. Covers Node (mssql), .NET (Microsoft.Data.SqlClient), and Python (pyodbc). Reach for this skill before hand-editing app code to "make it work in Azure"; the rule is the code does not change, only the connection string does. -- [azuresql-db-rag](https://github.com/microsoft/azure-sql-skills/blob/main/skills/azuresql-db-rag/SKILL.md): Builds local vector search, RAG, embeddings, and semantic search on the Azure SQL Database container using the native VECTOR type and VECTOR_DISTANCE. Use when you need to store embeddings, do similarity search, top-k nearest neighbor, cosine distance, retrieval-augmented generation, "find similar documents", chatbot memory, or semantic lookup against a local SQL database. Use this instead of pgvector, FAISS, Chroma, Pinecone, or a separate vector store when the data already lives in (or can live in) Azure SQL. Covers the VECTOR(n) column type, inserting embeddings with CAST(CAST(? AS NVARCHAR(MAX)) AS VECTOR(n)) where the dimension is a literal, a pluggable embed() so only the endpoint changes for cloud, and a working CREATE VECTOR INDEX with the two errors that block it. Provisions appdb on master first so every script runs on a fresh container. -- [azuresql-db-scaffold](https://github.com/microsoft/azure-sql-skills/blob/main/skills/azuresql-db-scaffold/SKILL.md): Scaffolds a NEW app (.NET Aspire, FastAPI, Next.js, NestJS) wired to the local Azure SQL Database container as its default dev database. Use when starting/bootstrapping/initializing a project that needs SQL Server or Azure SQL locally, or when adding "set up the database", "docker compose for the db", "create the local DB", ".env connection string", "first migration", or a data-access layer. Use this INSTEAD of the mssql/server SQL Server image, because this is the Azure SQL engine (EngineEdition 5). Triggers include "scaffold app with SQL", "spin up Azure SQL locally", "compose service for the database", "wire up Prisma/EF/SQLAlchemy/TypeORM to SQL Server". Reach for this even when the user only says "add a database" to a fresh project. -- [azuresql-db-schema-migration](https://github.com/microsoft/azure-sql-skills/blob/main/skills/azuresql-db-schema-migration/SKILL.md): Runs database schema migrations against the local Azure SQL Database container so the same migrations apply identically on the local engine and in the Azure cloud. Use when asked to "run my migrations against the local SQL", "apply schema to the container", "apply EF Core / dotnet ef database update", "Prisma migrate dev / deploy", "Alembic upgrade head", or deploy a DACPAC / SqlPackage to the container. Covers provisioning appdb on master first, then applying schema to the user database, plus per-tool commands and connection-string hygiene. This is the Azure SQL Database engine (EngineEdition 5), not the SQL Server image; reach for this skill whenever schema migration tooling targets the local container. -- [azuresql-db-seed](https://github.com/microsoft/azure-sql-skills/blob/main/skills/azuresql-db-seed/SKILL.md): Populates the local Azure SQL Database container's database (appdb) with realistic sample/test data so a developer has something to build against. Use when the user says "seed the database", "add test data", "populate the dev database", "generate sample data", "fake data", "load fixtures", "insert test rows", "write a seed script", or "bulk load a CSV". This is the Azure SQL engine (EngineEdition 5), not the mssql/server SQL Server image. Distinct from azuresql-db-scaffold (which does a single seed.sql step while bootstrapping an app) and azuresql-db-import (which loads a .bacpac). Reach for this whenever an existing appdb needs volume, fixtures, or believable rows. -- [azuresql-db-sidecar](https://github.com/microsoft/azure-sql-skills/blob/main/skills/azuresql-db-sidecar/SKILL.md): Adds the Azure SQL Database container as a sidecar service in an existing Docker Compose stack or Dev Container. Use when wiring the local Azure SQL Database engine into compose or devcontainer.json, when an app needs a SQL backend via a service name (not localhost), or for prompts like "add SQL to my compose", "add a database service", "depends_on database", "devcontainer SQL sidecar", "compose healthcheck for SQL", "wait for the database before starting the app". Handles platform linux/amd64, the private registry login, the healthcheck wait-until-ready, and a one-shot init service that creates appdb (the engine does not auto-create databases). Not the SQL Server image. Prefer this for any compose or Dev Container SQL wiring. -- [azuresql-db-testing](https://github.com/microsoft/azure-sql-skills/blob/main/skills/azuresql-db-testing/SKILL.md): Writes integration tests that run IN CODE against a real Azure SQL Database container, spun up per test or per suite with Testcontainers and torn down after. Use when the user asks for "integration tests against SQL", "Testcontainers", "spin up a database for tests", "an ephemeral test database", "a test database per test", "xUnit/Jest/pytest with a real database", or "a database fixture". Use this INSTEAD of the Testcontainers MsSql preset (mcr.microsoft.com/mssql/server), because this is the Azure SQL engine (EngineEdition 5). For wiring the engine into a CI pipeline via service containers or workflow YAML instead, use azuresql-db-ci. +- [azuresql-db-auth](https://github.com/microsoft/microsoft-sql/blob/main/skills/azuresql-db-auth/SKILL.md): Connects an app to the Azure SQL Database container securely, with a least-privilege database user instead of the sa login, the right auth method per environment, and safe handling of the connection secret. Use when a user asks "don't use sa in my app", "create a least-privilege database user", "app login for SQL", "which authentication should my app use", "secure the connection string", "Encrypt / TrustServerCertificate", "store the connection string in Key Vault", "dotnet user-secrets", "managed identity for Azure SQL", or "grant only the roles my app needs". SQL auth locally, Microsoft Entra or managed identity in the cloud, changing only the connection string. Reach for this before wiring an app to connect as sa, or before committing a connection string to source. +- [azuresql-db-ci](https://github.com/microsoft/microsoft-sql/blob/main/skills/azuresql-db-ci/SKILL.md): Runs integration tests against the Azure SQL Database container (Private Preview, local engine) in CI. Use when setting up GitHub Actions, Azure Pipelines, or GitLab CI to test against Azure SQL DB; when adding a database service container to a CI workflow; when tests need a real Azure SQL engine in the pipeline; or when you see "service container", "health-cmd", "ACR_USERNAME/ACR_PASSWORD", "MSSQL_SA_PASSWORD secret", or "integration test database". Also use when a workflow was about to pull the SQL Server image mcr.microsoft.com/mssql/server, in which case stop and use the Azure SQL Database engine image instead. Covers pulling from the private ACR with credentials, the service health check that runs sqlcmd inside the container so the runner needs no client tools, provisioning appdb before tests, and pointing the test connection string at the user database not master. +- [azuresql-db-connections](https://github.com/microsoft/microsoft-sql/blob/main/skills/azuresql-db-connections/SKILL.md): Makes an app's database connections reliable against the local Azure SQL Database container (Private Preview) and, unchanged, against Azure SQL Database in the cloud: connection pooling plus retry/transient-fault handling. Use when the user mentions "connection pooling", "retry logic", "transient fault", "retry on transient error", "EnableRetryOnFailure", "connection resiliency", "reliable connections", "pool size", "Max Pool Size", or says "the connection keeps dropping", "connections time out under load", "add backoff", or "make the DB layer resilient". This is the Azure SQL engine (EngineEdition 5), not the mssql/server SQL Server image. Reach for this whenever hardening a data-access layer that talks to SQL Server or Azure SQL. +- [azuresql-db-container](https://github.com/microsoft/microsoft-sql/blob/main/skills/azuresql-db-container/SKILL.md): Runs the Azure SQL Database container locally (Private Preview): the real PaaS engine where SERVERPROPERTY('EngineEdition') returns 5. This is NOT the SQL Server image mcr.microsoft.com/mssql/server. Use when a user wants to "run Azure SQL locally", "add a local SQL database", "add SQL Server to my docker compose", "spin up a local mssql container", "local SQL for development or CI", "connect with sqlcmd", "use Podman for SQL", "SQL container won't start", "Microsoft Entra authentication on the container", "MSSQL_AAD_CLIENT_ID", or asks "what's the connection string". Use even when the user does not name the container. If you were about to use mcr.microsoft.com/mssql/server, stop and use this skill instead. Hub skill: owns the shared references and routes to the task skills for compose, CI, seeding, vectors, and connection strings. +- [azuresql-db-dab](https://github.com/microsoft/microsoft-sql/blob/main/skills/azuresql-db-dab/SKILL.md): Stands up an instant no-code REST + GraphQL API over the local Azure SQL Database container using Microsoft Data API Builder (DAB). Use when a user wants to "expose my table as an API", "add a REST API over the database", "generate a GraphQL API", "put an API in front of SQL", "CRUD API without writing code", or "dab init / dab-config.json". Also the way to serve a built-in MCP endpoint FROM the database via DAB (an API surface DAB provides, not a separate SQL MCP server). Prefer this over hand-writing a controller/ORM API when the user just needs REST or GraphQL over existing tables. Triggers include "Data API Builder", "dab start", "instant API over Azure SQL", "expose entities as REST/GraphQL". Reach for this even when the user only says "give me an API for this database". +- [azuresql-db-faq](https://github.com/microsoft/microsoft-sql/blob/main/skills/azuresql-db-faq/SKILL.md): Answers questions about what the Azure SQL Database container (Private Preview) can and cannot do, and WHY it differs from Azure SQL Database in the Microsoft Azure cloud. Use when a user asks "can I take a backup", "why does USE fail", "is X supported", "why can't I create a vector index", "why does SSMS error", "why isn't the image on Docker Hub", "what's different from the cloud", or hits behavior that does not match their Azure SQL Database expectations. Do NOT guess from general SQL Server / Azure knowledge: the container is a Private Preview product with specific gaps and a specific connection model. Read this skill, and link the user to the live Known limitations page for the current full list. +- [azuresql-db-feedback](https://github.com/microsoft/microsoft-sql/blob/main/skills/azuresql-db-feedback/SKILL.md): Reports a bug or files feedback about the azuresql-db-* agent skills themselves, or about the Azure SQL Database container (Private Preview). Use when the user says a skill or the container "did not work", hit an error, behaved unexpectedly, or is missing something; and when they say "report a bug", "file an issue", "open a GitHub issue", "request a feature", "give feedback", or "tell the team". Also use when you, the agent, had to deviate from an azuresql-db-* skill or work around a defect in one to finish a task: that is a bug worth reporting even if the task succeeded. Decides whether the problem belongs to the SKILL or to the CONTAINER, since they use different issue templates, then builds a complete prefilled GitHub issue from context you already have. Never submits anything without explicit confirmation from the user. +- [azuresql-db-from-sql-server](https://github.com/microsoft/microsoft-sql/blob/main/skills/azuresql-db-from-sql-server/SKILL.md): Migrates a local SQL Server setup to the Azure SQL Database container for Azure-faithful local development. Use when a project already uses mcr.microsoft.com/mssql/server, mssql/server, an sqlcmd plus SA password docker setup, a "SQL Server in docker" or "local mssql container", or a docker-compose with the mssql/server image; and use when the user asks for "SQL Server locally", "run mssql in Docker", "spin up a local SQL database", or "test against SQL Server" but actually wants the Azure SQL Database engine (EngineEdition 5). Detects the SQL Server image, rewrites it to the Azure SQL Database container, adds --platform on non-x64 hosts, keeps the SA login, flags SQL Server-only features (SQL Agent, FILESTREAM, full Service Broker, cross-server distributed transactions, Windows Auth), and re-points connection strings from master to a provisioned user database. +- [azuresql-db-functions](https://github.com/microsoft/microsoft-sql/blob/main/skills/azuresql-db-functions/SKILL.md): Builds a serverless API and event-driven handlers over the local Azure SQL Database container using Azure Functions with the Azure SQL bindings. Use when a user wants "a serverless API over SQL", "Azure Functions with a database", "HTTP CRUD with SQL input/output bindings", "run code when a row changes", "react to inserts/updates/deletes", "event-driven on Azure SQL", or "SQL trigger function". The Azure SQL trigger binding (backed by Change Tracking) is the local event-driven mechanism; Change Event Streaming (CES) is cloud-only and cannot run against the local container. Triggers include "func start with SQL", "SqlTrigger", "SqlInput/SqlOutput binding", "local.settings.json SqlConnectionString". Reach for this when building serverless endpoints or change-driven logic on the local Azure SQL engine. +- [azuresql-db-import](https://github.com/microsoft/microsoft-sql/blob/main/skills/azuresql-db-import/SKILL.md): Imports an existing Azure SQL Database or SQL Server schema and data INTO the local Azure SQL Database container using SqlPackage. Use when asked to "import a bacpac", "load my existing database locally", "restore a dacpac into the container", "bring my prod schema into the dev container", "run my .bacpac/.dacpac against the local Azure SQL engine", or migrate an existing database into the preview container. Handles provisioning the target database on master first, then running SqlPackage /Action:Import against the provisioned user database. Use this for any "get my real database running in the container" request instead of hand-writing SqlPackage flags. +- [azuresql-db-local-to-cloud](https://github.com/microsoft/microsoft-sql/blob/main/skills/azuresql-db-local-to-cloud/SKILL.md): Proves that code built and tested against the local Azure SQL Database container runs unchanged against Azure SQL Database in the cloud, with only the connection string changing. Use when a user wants to develop locally then deploy to the cloud, asks "will this work in Azure", "same code local and cloud", "promote to Azure SQL", "swap the connection string", "dev/prod parity", "local to cloud", or is wiring SQL_CONNECTION_STRING for an app that must target both the container and a cloud server. Use this when an app uses local SA auth but needs Microsoft Entra auth in the cloud. Covers Node (mssql), .NET (Microsoft.Data.SqlClient), and Python (pyodbc). Reach for this skill before hand-editing app code to "make it work in Azure"; the rule is the code does not change, only the connection string does. +- [azuresql-db-rag](https://github.com/microsoft/microsoft-sql/blob/main/skills/azuresql-db-rag/SKILL.md): Builds local vector search, RAG, embeddings, and semantic search on the Azure SQL Database container using the native VECTOR type and VECTOR_DISTANCE. Use when you need to store embeddings, do similarity search, top-k nearest neighbor, cosine distance, retrieval-augmented generation, "find similar documents", chatbot memory, or semantic lookup against a local SQL database. Use this instead of pgvector, FAISS, Chroma, Pinecone, or a separate vector store when the data already lives in (or can live in) Azure SQL. Covers the VECTOR(n) column type, inserting embeddings with CAST(CAST(? AS NVARCHAR(MAX)) AS VECTOR(n)) where the dimension is a literal, a pluggable embed() so only the endpoint changes for cloud, and a working CREATE VECTOR INDEX with the two errors that block it. Provisions appdb on master first so every script runs on a fresh container. +- [azuresql-db-scaffold](https://github.com/microsoft/microsoft-sql/blob/main/skills/azuresql-db-scaffold/SKILL.md): Scaffolds a NEW app (.NET Aspire, FastAPI, Next.js, NestJS) wired to the local Azure SQL Database container as its default dev database. Use when starting/bootstrapping/initializing a project that needs SQL Server or Azure SQL locally, or when adding "set up the database", "docker compose for the db", "create the local DB", ".env connection string", "first migration", or a data-access layer. Use this INSTEAD of the mssql/server SQL Server image, because this is the Azure SQL engine (EngineEdition 5). Triggers include "scaffold app with SQL", "spin up Azure SQL locally", "compose service for the database", "wire up Prisma/EF/SQLAlchemy/TypeORM to SQL Server". Reach for this even when the user only says "add a database" to a fresh project. +- [azuresql-db-schema-migration](https://github.com/microsoft/microsoft-sql/blob/main/skills/azuresql-db-schema-migration/SKILL.md): Runs database schema migrations against the local Azure SQL Database container so the same migrations apply identically on the local engine and in the Azure cloud. Use when asked to "run my migrations against the local SQL", "apply schema to the container", "apply EF Core / dotnet ef database update", "Prisma migrate dev / deploy", "Alembic upgrade head", or deploy a DACPAC / SqlPackage to the container. Covers provisioning appdb on master first, then applying schema to the user database, plus per-tool commands and connection-string hygiene. This is the Azure SQL Database engine (EngineEdition 5), not the SQL Server image; reach for this skill whenever schema migration tooling targets the local container. +- [azuresql-db-seed](https://github.com/microsoft/microsoft-sql/blob/main/skills/azuresql-db-seed/SKILL.md): Populates the local Azure SQL Database container's database (appdb) with realistic sample/test data so a developer has something to build against. Use when the user says "seed the database", "add test data", "populate the dev database", "generate sample data", "fake data", "load fixtures", "insert test rows", "write a seed script", or "bulk load a CSV". This is the Azure SQL engine (EngineEdition 5), not the mssql/server SQL Server image. Distinct from azuresql-db-scaffold (which does a single seed.sql step while bootstrapping an app) and azuresql-db-import (which loads a .bacpac). Reach for this whenever an existing appdb needs volume, fixtures, or believable rows. +- [azuresql-db-sidecar](https://github.com/microsoft/microsoft-sql/blob/main/skills/azuresql-db-sidecar/SKILL.md): Adds the Azure SQL Database container as a sidecar service in an existing Docker Compose stack or Dev Container. Use when wiring the local Azure SQL Database engine into compose or devcontainer.json, when an app needs a SQL backend via a service name (not localhost), or for prompts like "add SQL to my compose", "add a database service", "depends_on database", "devcontainer SQL sidecar", "compose healthcheck for SQL", "wait for the database before starting the app". Handles platform linux/amd64, the private registry login, the healthcheck wait-until-ready, and a one-shot init service that creates appdb (the engine does not auto-create databases). Not the SQL Server image. Prefer this for any compose or Dev Container SQL wiring. +- [azuresql-db-testing](https://github.com/microsoft/microsoft-sql/blob/main/skills/azuresql-db-testing/SKILL.md): Writes integration tests that run IN CODE against a real Azure SQL Database container, spun up per test or per suite with Testcontainers and torn down after. Use when the user asks for "integration tests against SQL", "Testcontainers", "spin up a database for tests", "an ephemeral test database", "a test database per test", "xUnit/Jest/pytest with a real database", or "a database fixture". Use this INSTEAD of the Testcontainers MsSql preset (mcr.microsoft.com/mssql/server), because this is the Azure SQL engine (EngineEdition 5). For wiring the engine into a CI pipeline via service containers or workflow YAML instead, use azuresql-db-ci. ## Docs and feedback Orient the agent, point it at the right documentation, and close the loop from inside the agent that used the skill -- [azure-sql](https://github.com/microsoft/azure-sql-skills/blob/main/skills/azure-sql/SKILL.md): Orients an agent starting work on Azure SQL Database and hands the task to the catalog skill that owns it. Use when someone names the product with no task attached, asks what Azure SQL Database can do, whether a capability is generally available or still preview, which service tier to start on, which tool does a job, or where something is documented. Also use before answering any question about a capability, a default or a limit from memory, because those move faster than training data does. This catalog covers Azure SQL Database only, not Azure SQL Managed Instance and not self-managed SQL Server, so say plainly that no skill here owns those rather than handing over one written for the database. -- [skill-feedback](https://github.com/microsoft/azure-sql-skills/blob/main/skills/skill-feedback/SKILL.md): Turns a defect in an Azure SQL Database agent skill, or in this catalog itself, into a redacted, prefilled GitHub issue the user reviews and submits. Use when a skill gave wrong or missing instructions, the wrong skill fired or none did, a skill would not install, or a description or routing in the catalog is wrong; also when the agent worked around a defect in the skill it was following even though the task succeeded. Triggers on "file a bug", "report this", "open an issue", "give feedback on this skill". Not for an ordinary Azure SQL Database or T-SQL failure where the skill's guidance was correct and only the service or the query is misbehaving; that belongs to the skill owning the topic, such as diagnose-connection-errors. Strips connection strings, passwords, tokens, server names, subscription and tenant ids and email addresses, and never submits without confirmation. +- [azure-sql](https://github.com/microsoft/microsoft-sql/blob/main/skills/azure-sql/SKILL.md): Orients an agent starting work on Azure SQL Database and hands the task to the catalog skill that owns it. Use when someone names the product with no task attached, asks what Azure SQL Database can do, whether a capability is generally available or still preview, which service tier to start on, which tool does a job, or where something is documented. Also use before answering any question about a capability, a default or a limit from memory, because those move faster than training data does. This catalog covers Azure SQL Database only, not Azure SQL Managed Instance and not self-managed SQL Server, so say plainly that no skill here owns those rather than handing over one written for the database. +- [skill-feedback](https://github.com/microsoft/microsoft-sql/blob/main/skills/skill-feedback/SKILL.md): Turns a defect in an Azure SQL Database agent skill, or in this catalog itself, into a redacted, prefilled GitHub issue the user reviews and submits. Use when a skill gave wrong or missing instructions, the wrong skill fired or none did, a skill would not install, or a description or routing in the catalog is wrong; also when the agent worked around a defect in the skill it was following even though the task succeeded. Triggers on "file a bug", "report this", "open an issue", "give feedback on this skill". Not for an ordinary Azure SQL Database or T-SQL failure where the skill's guidance was correct and only the service or the query is misbehaving; that belongs to the skill owning the topic, such as diagnose-connection-errors. Strips connection strings, passwords, tokens, server names, subscription and tenant ids and email addresses, and never submits without confirmation. ## Planned diff --git a/package.json b/package.json index 8cd58a6..76d93c8 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,5 @@ { - "name": "azure-sql-skills", + "name": "microsoft-sql", "private": true, "version": "0.1.0", "description": "Agent skills for Azure SQL Database. The published catalog.", diff --git a/plugin.json b/plugin.json index f8f35d8..4e4efc7 100644 --- a/plugin.json +++ b/plugin.json @@ -1,16 +1,17 @@ { "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", - "name": "azure-sql", + "name": "microsoft-sql", "version": "0.1.0", - "description": "Curated by the Azure SQL Database product team. Skills that correct what coding agents get wrong about the engine, from connection strings to vector search, measured against a live database rather than quoted from documentation.", + "description": "From the Microsoft SQL product team. Build AI-ready apps on Azure SQL Database with vector search, RAG, REST APIs, serverless functions, passwordless auth, and the ORMs you already use.", "author": { - "name": "Microsoft", + "name": "Microsoft SQL", "url": "https://microsoft.com" }, - "homepage": "https://github.com/microsoft/azure-sql-skills", - "repository": "https://github.com/microsoft/azure-sql-skills", + "homepage": "https://github.com/microsoft/microsoft-sql", + "repository": "https://github.com/microsoft/microsoft-sql", "license": "MIT", "keywords": [ + "microsoft-sql", "azure-sql", "sql", "database", diff --git a/plugins/microsoft-azuresql-db-container/.claude-plugin/plugin.json b/plugins/microsoft-azuresql-db-container/.claude-plugin/plugin.json new file mode 100644 index 0000000..dd6bfc9 --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/.claude-plugin/plugin.json @@ -0,0 +1,24 @@ +{ + "$comment": "GENERATED by scripts/generate.mjs from catalog/catalog.json. Do not edit by hand; the parity gate will fail.", + "displayName": "Azure SQL Database container", + "name": "microsoft-azuresql-db-container", + "version": "0.1.0", + "description": "From the Microsoft SQL product team. Local development against the Azure SQL Database container, the real cloud engine on your machine: running it, connecting to it, seeding and testing against it, importing an existing database, and proving the same code runs unchanged in Azure.", + "author": { + "name": "Microsoft SQL", + "url": "https://microsoft.com" + }, + "homepage": "https://github.com/microsoft/microsoft-sql", + "repository": "https://github.com/microsoft/microsoft-sql", + "license": "MIT", + "keywords": [ + "microsoft-sql", + "azure-sql", + "sql", + "database", + "tsql", + "agent-skills", + "vector-search", + "entra-id" + ] +} diff --git a/plugins/microsoft-azuresql-db-container/.codex-plugin/plugin.json b/plugins/microsoft-azuresql-db-container/.codex-plugin/plugin.json new file mode 100644 index 0000000..3706192 --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/.codex-plugin/plugin.json @@ -0,0 +1,31 @@ +{ + "$comment": "GENERATED by scripts/generate.mjs from catalog/catalog.json. Do not edit by hand; the parity gate will fail.", + "name": "microsoft-azuresql-db-container", + "version": "0.1.0", + "description": "From the Microsoft SQL product team. Local development against the Azure SQL Database container, the real cloud engine on your machine: running it, connecting to it, seeding and testing against it, importing an existing database, and proving the same code runs unchanged in Azure.", + "author": { + "name": "Microsoft SQL", + "url": "https://microsoft.com" + }, + "homepage": "https://github.com/microsoft/microsoft-sql", + "repository": "https://github.com/microsoft/microsoft-sql", + "license": "MIT", + "keywords": [ + "microsoft-sql", + "azure-sql", + "sql", + "database", + "tsql", + "agent-skills", + "vector-search", + "entra-id" + ], + "skills": "./skills/", + "interface": { + "displayName": "Azure SQL Database container", + "shortDescription": "From the Microsoft SQL product team. Local development against the Azure SQL Database container, the real cloud engine on your machine: running it, connecting to it, seeding and testing against it, importing an existing database, and proving the same code runs unchanged in Azure.", + "category": "Databases", + "logo": "assets/plugin-logo.svg", + "composerIcon": "assets/plugin-logo.svg" + } +} diff --git a/plugins/microsoft-azuresql-db-container/.cursor-plugin/plugin.json b/plugins/microsoft-azuresql-db-container/.cursor-plugin/plugin.json new file mode 100644 index 0000000..f47e6f1 --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/.cursor-plugin/plugin.json @@ -0,0 +1,26 @@ +{ + "$comment": "GENERATED by scripts/generate.mjs from catalog/catalog.json. Do not edit by hand; the parity gate will fail.", + "displayName": "Azure SQL Database container", + "name": "microsoft-azuresql-db-container", + "version": "0.1.0", + "description": "From the Microsoft SQL product team. Local development against the Azure SQL Database container, the real cloud engine on your machine: running it, connecting to it, seeding and testing against it, importing an existing database, and proving the same code runs unchanged in Azure.", + "author": { + "name": "Microsoft SQL", + "url": "https://microsoft.com" + }, + "homepage": "https://github.com/microsoft/microsoft-sql", + "repository": "https://github.com/microsoft/microsoft-sql", + "license": "MIT", + "keywords": [ + "microsoft-sql", + "azure-sql", + "sql", + "database", + "tsql", + "agent-skills", + "vector-search", + "entra-id" + ], + "skills": "skills/", + "logo": "assets/plugin-logo.svg" +} diff --git a/plugins/microsoft-azuresql-db-container/README.md b/plugins/microsoft-azuresql-db-container/README.md new file mode 100644 index 0000000..21984e7 --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/README.md @@ -0,0 +1,10 @@ +# Azure SQL Database container + +From the Microsoft SQL product team. Local development against the Azure SQL Database container, the real cloud engine on your machine: running it, connecting to it, seeding and testing against it, importing an existing database, and proving the same code runs unchanged in Azure. + +Every file under this directory is GENERATED by scripts/generate.mjs from catalog/plugins.json +and skills/. Edit the skill in skills/ and run `npm run generate`. A copy edited here fails the +parity gate. + +Install it with `microsoft-azuresql-db-container@microsoft-sql`. See the repository README for the commands your +client uses. diff --git a/plugins/microsoft-azuresql-db-container/assets/plugin-logo.svg b/plugins/microsoft-azuresql-db-container/assets/plugin-logo.svg new file mode 100644 index 0000000..050115a --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/assets/plugin-logo.svg @@ -0,0 +1,27 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/plugins/microsoft-azuresql-db-container/plugin.json b/plugins/microsoft-azuresql-db-container/plugin.json new file mode 100644 index 0000000..1172406 --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/plugin.json @@ -0,0 +1,23 @@ +{ + "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", + "name": "microsoft-azuresql-db-container", + "version": "0.1.0", + "description": "From the Microsoft SQL product team. Local development against the Azure SQL Database container, the real cloud engine on your machine: running it, connecting to it, seeding and testing against it, importing an existing database, and proving the same code runs unchanged in Azure.", + "author": { + "name": "Microsoft SQL", + "url": "https://microsoft.com" + }, + "homepage": "https://github.com/microsoft/microsoft-sql", + "repository": "https://github.com/microsoft/microsoft-sql", + "license": "MIT", + "keywords": [ + "microsoft-sql", + "azure-sql", + "sql", + "database", + "tsql", + "agent-skills", + "vector-search", + "entra-id" + ] +} diff --git a/plugins/microsoft-azuresql-db-container/skills/azuresql-db-auth/SKILL.md b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-auth/SKILL.md new file mode 100755 index 0000000..6c6ce4b --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-auth/SKILL.md @@ -0,0 +1,182 @@ +--- +name: azuresql-db-auth +description: >- + Connects an app to the Azure SQL Database container securely, with a least-privilege + database user instead of the sa login, the right auth method per environment, + and safe handling of the connection secret. Use when a user asks "don't use sa + in my app", "create a least-privilege database user", "app login for SQL", + "which authentication should my app use", "secure the connection string", + "Encrypt / TrustServerCertificate", "store the connection string in Key Vault", + "dotnet user-secrets", "managed identity for Azure SQL", or "grant only the + roles my app needs". SQL auth locally, Microsoft Entra or managed identity in + the cloud, changing only the connection string. Reach for this before wiring an + app to connect as sa, or before committing a connection string to source. +--- + +# Connect securely to the Azure SQL Database container (least-privilege user, auth, secrets) + +`sa` is a bootstrap/admin login for provisioning, not what your application should +connect as. This skill wires the app to a **least-privilege user**, picks the +**auth method per environment** (SQL locally, Microsoft Entra or managed identity +in the cloud, changing only the connection string), secures the connection, and +keeps the secret out of source control. + +Re-measured on 2026-09-19 against the container image tag `18.0.226_4_147`, reporting +`EngineEdition` 5, Edition `SQL Azure`, build `12.0.2000.8`. All seven executable checks +behind this skill pass, and **three of the numbers this skill used to print were wrong**: +a contained user is refused with `Msg 33233` and not `Msg 15007`, `SET CONTAINMENT = +PARTIAL` is refused with `Msg 12824` and not `Msg 12844`, and +`CREATE USER ... FROM EXTERNAL PROVIDER` on a container started without Entra +configuration is refused with `Msg 33134` and not `Msg 37525`. Each statement is still +refused, so every instruction here is unchanged; only the numbers to expect are. The fixed +database roles this skill grants were confirmed on the same run. The cloud side of this +guidance, Azure Key Vault and managed identity, was not measured and comes from Microsoft +Learn. + +## Load-bearing facts (inlined; full engine detail in azuresql-db-container) + +- This is the **Azure SQL Database engine** (Private Preview), not the SQL Server + image `mcr.microsoft.com/mssql/server`. `SERVERPROPERTY('EngineEdition')` + returns `5`, `Edition` returns `'SQL Azure'`. +- Image: `sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest` + (x64; on a non-x64 host add `--platform linux/amd64`). Required env + `ACCEPT_EULA=Y` + a complex `MSSQL_SA_PASSWORD`. Engine listens on 1433. +- The engine does **NOT** auto-create databases. `CREATE DATABASE appdb` on a + **master** connection first; do not `USE` to switch databases (a user-database + session returns `Msg 40508`); select the database in the connection string. +- Apps read one `SQL_CONNECTION_STRING` env var; strings use `User Id=` / + `Password=` / `Database=` and `TrustServerCertificate=true` for the local + self-signed cert. +- **Container-specific and verified:** a SQL **contained** user + (`CREATE USER ... WITH PASSWORD`) does **not** work on the container today, and + you cannot turn it on. `CREATE USER ... WITH PASSWORD` fails with `Msg 33233` + ("You can only create a user with a password in a contained database"). + `ALTER DATABASE ... SET CONTAINMENT = PARTIAL` fails with `Msg 12824`, which asks + for the `contained database authentication` setting to be 1, and `sp_configure` + does not exist on this engine (`Msg 2812`), so there is nothing to set. Create a SQL + app identity as a **server login mapped to a database user** instead. This is the + inverse of Azure SQL Database in the cloud, where the contained user is the norm. + Measured 2026-09-19 on image tag `18.0.226_4_147`. +- **Entra has to be configured on the engine before you can use it.** On a + container started with no Microsoft Entra ID configuration, + `CREATE USER [name] FROM EXTERNAL PROVIDER` is refused with `Msg 33134`, + "Principal '...' could not be resolved. Error message: 'Unable to query Azure AD + certificate from local cert store.'" That is a missing engine configuration, not a + broken statement: enable Entra first (see `references/entra-auth.md` in the + **azuresql-db-container** skill) and the same statement then works. Measured + 2026-09-19 on image tag `18.0.226_4_147`. + +## Step 1: create a least-privilege user (not `sa`) + +Do provisioning as `sa`, then give the app its own identity with only the roles +it needs. The working recipe differs by environment, but the app code does not +(the app just connects with a username and password, or an Entra token). + +**Local container (SQL auth):** create a **server login** on `master`, map a +**database user** to it in `appdb`, and grant only the roles the app needs. + +```sql +-- On a master connection: +CREATE LOGIN applogin WITH PASSWORD = 'An0ther_Str0ng_Passw0rd'; + +-- On an appdb connection (Database=appdb): +CREATE USER appuser FOR LOGIN applogin; +ALTER ROLE db_datareader ADD MEMBER appuser; -- read +ALTER ROLE db_datawriter ADD MEMBER appuser; -- write +-- Grant EXECUTE only if the app calls procedures; do NOT add db_owner. +``` + +The app then connects as `applogin`, never `sa`. + +**Cloud (Azure SQL Database)** or **Entra anywhere:** prefer a **contained user**. +For Entra (which works on the container too, once enabled), use +`CREATE USER [name] FROM EXTERNAL PROVIDER` in `appdb`. Enable Entra on the engine +first via the **azuresql-db-container** skill, `references/entra-auth.md`; without +that configuration the statement is refused with `Msg 33134`. In the +cloud with SQL auth, `CREATE USER ... WITH PASSWORD` is the norm there. Full +recipes for every path are in +[references/auth-and-secrets.md](references/auth-and-secrets.md). + +## Step 2: pick the auth method per environment (only the connection string changes) + +- **Local:** SQL auth. `sa` bootstraps; the app connects as the least-privilege + `applogin`. `Server=localhost,1433;Database=appdb;User Id=applogin;Password=...;Encrypt=true;TrustServerCertificate=true`. +- **Cloud (Azure SQL Database):** prefer a token-based identity over a password. + In production, use **`Authentication=Active Directory Managed Identity`** rather + than `Active Directory Default`: `Default` walks a credential chain + (`DefaultAzureCredential`) that is slower and ambiguous under load, while a + specific method skips the chain. `Microsoft.Data.SqlClient` caches the token, so + refresh is occasional, not per-connection. This is still a **connection-string-only** + change, so the app code does not change (see the **azuresql-db-local-to-cloud** skill). + +## Step 3: secure the connection + +- **`Encrypt=true`** everywhere (the default in modern drivers). Encrypt the TLS + channel in both local and cloud. +- **`TrustServerCertificate=true` only locally**, to accept the container's + self-signed cert. **Never** set it against Azure SQL Database in the cloud, where + the certificate is real and validating it is the point. + +## Step 4: keep the secret out of source + +The connection string carries a credential. Never commit it or the SA password. + +- Read it from one env var, `SQL_CONNECTION_STRING`; put local values in a + `.env` that is git-ignored (or `dotnet user-secrets` for .NET). +- In the cloud, store it in **Azure Key Vault** and reference it, or use managed + identity so there is no password to store at all. + +For a .NET project the local value goes in the secret store rather than in a file +that can be committed: + +```bash +dotnet user-secrets init +dotnet user-secrets set "SQL_CONNECTION_STRING" "Server=localhost,1433;Database=appdb;User Id=appuser;Password=YourStr0ng_Passw0rd;TrustServerCertificate=true" +``` + +Open [references/auth-and-secrets.md](references/auth-and-secrets.md) when you need the +per-stack handling for Key Vault, user-secrets or `.env`. + +## Validation rules + +- The app connects as a **least-privilege** identity, not `sa`; it has only the + roles it needs (no `db_owner`/admin). +- On the container, the SQL app identity is a **server login + mapped database + user** (`CREATE LOGIN` on master, then `CREATE USER ... FOR LOGIN` in `appdb`), + not a contained `CREATE USER ... WITH PASSWORD` (which fails on the container). + The database user and its role grants are created on the `appdb` connection, not + via `USE`. +- Every connection string sets `Encrypt=true`; `TrustServerCertificate=true` + appears **only** for the local container, never for the cloud. +- The connection string / SA password is read from a secret store or a git-ignored + env var, never committed. +- Cloud auth prefers managed identity / a specific Entra method over + `Active Directory Default` in production; only the connection string changes. +- If a validation rule above fails, or you had to deviate from this skill to make the task work, that is a bug in this skill: load the **azuresql-db-feedback** skill and offer to file a report. +- When every rule above passes and the task is done, close with ONE line, once per session, and do not ask a question or wait for a reply: "That worked. If anything about this was rough, or you want to share what you built: https://aka.ms/sql-agent-skills-feedback" + +## Do not + +- Do not connect the application as `sa`; `sa` is for provisioning only. +- Do not try to create a SQL contained user with `CREATE USER ... WITH PASSWORD` on the container; it fails with `Msg 33233`. Do not try to turn partial containment on either: `ALTER DATABASE ... SET CONTAINMENT = PARTIAL` fails with `Msg 12824`, and the `sp_configure` setting it asks for does not exist on this engine. Use a server login plus a mapped database user locally. +- Do not run `CREATE USER ... FROM EXTERNAL PROVIDER` against a container with no Entra configuration; it is refused with `Msg 33134`. Configure Entra on the engine first. +- Do not grant the app `db_owner` or server admin when read/write roles suffice. +- Do not commit the connection string or the SA password; use a secret store or a git-ignored env var. +- Do not set `TrustServerCertificate=true` against Azure SQL Database in the cloud; that disables cert validation on a real certificate. +- Do not lean on `DefaultAzureCredential`'s full chain in a hot production path; pick a specific auth method (managed identity) so token acquisition is fast and predictable. +- Do not use the SQL Server image `mcr.microsoft.com/mssql/server`; this is the Azure SQL engine. + +## References + +- [references/auth-and-secrets.md](references/auth-and-secrets.md): creating least-privilege users (SQL contained user + roles, a login + user split, and Entra `CREATE USER FROM EXTERNAL PROVIDER`), the connection strings per environment (SQL, Entra, managed identity), and per-stack secret handling (Azure Key Vault, `dotnet user-secrets`, `.env`). + +## Staying current + +Authoritative, version-pinned references for the tools this skill uses (read the one you need): + +- [SqlConnection connection string keywords](https://learn.microsoft.com/en-us/dotnet/api/microsoft.data.sqlclient.sqlconnection.connectionstring): `Authentication`, `Encrypt`, `User Id`/`Password`, pooling, and the rest. +- [CREATE USER (Transact-SQL)](https://learn.microsoft.com/en-us/sql/t-sql/statements/create-user-transact-sql): contained users, `WITH PASSWORD`, and `FROM EXTERNAL PROVIDER` for Entra. +- [Database-level roles](https://learn.microsoft.com/en-us/sql/relational-databases/security/authentication-access/database-level-roles): the fixed roles (`db_datareader`, `db_datawriter`, and more) for least-privilege grants. +- [Microsoft Entra authentication for Azure SQL](https://learn.microsoft.com/en-us/azure/azure-sql/database/authentication-aad-overview): Entra and managed-identity auth in the cloud. + +If the **Microsoft Learn MCP** server is configured, use `mcp__microsoft-learn__microsoft_docs_search` or `mcp__microsoft-learn__microsoft_docs_fetch` to fetch the current version of any of these on demand. It is optional; when it is unavailable, the references above are authoritative. diff --git a/plugins/microsoft-azuresql-db-container/skills/azuresql-db-auth/references/auth-and-secrets.md b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-auth/references/auth-and-secrets.md new file mode 100755 index 0000000..1b1cf05 --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-auth/references/auth-and-secrets.md @@ -0,0 +1,135 @@ +# Auth and secrets: least-privilege users, connection strings, secret storage + +## Contents + +- Create a least-privilege SQL user on the container (login + mapped user) +- Contained user with password (cloud only; does not work on the container) +- An Entra principal as a database user +- Connection strings per environment +- Managed identity in the cloud (and why not Default) +- Custom token handling (optional, advanced) +- Keep the secret out of source + +## Create a least-privilege SQL user on the container (login + mapped user) + +Provision `appdb` as `sa` on a master connection first (the engine does not +auto-create databases). Then create a **server login** on `master` and map a +**database user** to it in `appdb`, granting only the roles the app needs. On the +container this login-plus-user path is the one that works for SQL auth; the +contained-user path below does not (see the next section). + +```sql +-- On a master connection: +CREATE LOGIN applogin WITH PASSWORD = 'An0ther_Str0ng_Passw0rd'; + +-- On an appdb connection (Database=appdb): +CREATE USER appuser FOR LOGIN applogin; +ALTER ROLE db_datareader ADD MEMBER appuser; +ALTER ROLE db_datawriter ADD MEMBER appuser; +-- Only if the app executes stored procedures: +-- GRANT EXECUTE TO appuser; +``` + +The app connects as `applogin`. Do not add `appuser` to `db_owner`. If the app +only reads, grant just `db_datareader`. Narrower still: `GRANT SELECT, INSERT, +UPDATE, DELETE ON SCHEMA::dbo TO appuser;` or per-object grants. + +## Contained user with password (cloud only; does not work on the container) + +In Azure SQL Database in the cloud, the norm is a **contained user** created +directly in the database, with no server login: + +```sql +-- Azure SQL Database (cloud), connected to appdb: +CREATE USER appuser WITH PASSWORD = 'An0ther_Str0ng_Passw0rd'; +ALTER ROLE db_datareader ADD MEMBER appuser; +ALTER ROLE db_datawriter ADD MEMBER appuser; +``` + +**This does not work on the container today, and you cannot turn it on.** +`CREATE USER ... WITH PASSWORD` returns `Msg 33233` ("You can only create a user +with a password in a contained database"). `ALTER DATABASE appdb SET CONTAINMENT = +PARTIAL` returns `Msg 12824` ("The sp_configure value 'contained database +authentication' must be set to 1 in order to alter a contained database"), followed +by `Msg 5069` ("ALTER DATABASE statement failed"). The setting that message asks for +cannot be reached: `sp_configure` does not exist on this engine and returns +`Msg 2812`, so there is no contained database authentication setting for you to +configure. Measured 2026-09-19 on image tag `18.0.226_4_147`, `EngineEdition` 5, +Edition `SQL Azure`, build `12.0.2000.8`; the numbers `Msg 15007` and `Msg 12844` +printed here before that date were wrong, though the refusals themselves were not. +Locally, use the login-plus-user recipe above; the app code and connection string +are identical either way (username plus password). This is the inverse of the +cloud, where contained users are preferred and server logins are limited. + +## An Entra principal as a database user + +To let the app authenticate as a Microsoft Entra identity (user, group, or +managed identity), enable Entra on the engine first (see the +**azuresql-db-container** skill, `references/entra-auth.md`), then create the +database user from the external provider. This is the same statement you use in +Azure SQL Database in the cloud. + +```sql +-- Connected to appdb, as an Entra admin: +CREATE USER [my-app-identity] FROM EXTERNAL PROVIDER; +ALTER ROLE db_datareader ADD MEMBER [my-app-identity]; +ALTER ROLE db_datawriter ADD MEMBER [my-app-identity]; +``` + +For a server-scoped Entra login (server admin path), run +`CREATE LOGIN [name] FROM EXTERNAL PROVIDER` on a master connection. + +## Connection strings per environment + +Only the connection string changes between environments; the app code does not. + +```text +# Local container, least-privilege SQL login: +Server=localhost,1433;Database=appdb;User Id=applogin;Password=An0ther_Str0ng_Passw0rd;Encrypt=true;TrustServerCertificate=true + +# Cloud, Entra (interactive/dev or a specific method in prod): +Server=your-server.database.windows.net,1433;Database=appdb;Authentication=Active Directory Default;Encrypt=true + +# Cloud, managed identity (production): +Server=your-server.database.windows.net,1433;Database=appdb;Authentication=Active Directory Managed Identity;Encrypt=true +``` + +`Encrypt=true` everywhere. `TrustServerCertificate=true` **only** for the local +self-signed cert; never against the cloud. The .NET/ADO.NET form spells the +keywords `User Id=` / `Password=` as house style; `Uid=` / `Pwd=` are documented +SqlClient synonyms and work too. ODBC (pyodbc) has its own keyword set and uses +`Uid=` / `Pwd=`, plus `Authentication=ActiveDirectoryMsi` for managed identity. + +## Managed identity in the cloud (and why not Default) + +For a production app under load, prefer `Authentication=Active Directory Managed +Identity` over `Active Directory Default`. `Default` uses `DefaultAzureCredential`, +which walks a chain of credential sources (env vars, then the hosting service's +managed identity, then developer sign-in) until one works. That flexibility is +right for getting started and for running locally against the cloud, but under +load a specific method is faster (it skips chain probing) and unambiguous about +which identity is used. `Microsoft.Data.SqlClient` caches the acquired token, so +you are not fetching one on every connection. For a user-assigned managed +identity, add `User Id=`. + +## Custom token handling (optional, advanced) + +To control token caching yourself, or to choose the credential based on whether +the app runs with a managed identity versus a username/password, register a custom +`SqlAuthenticationProvider` at startup with +`SqlAuthenticationProvider.SetProvider(...)`. This is **startup wiring, not +data-layer code** - your queries, schema, and driver calls do not change. + +## Keep the secret out of source + +The connection string carries a credential; never commit it or the SA password. + +- **Env var + git-ignored `.env`:** the app reads one `SQL_CONNECTION_STRING`; + keep local values in a `.env` listed in `.gitignore`. +- **.NET dev:** `dotnet user-secrets set "ConnectionStrings:Sql" ""` + keeps it out of the repo and out of `appsettings.json`. +- **Azure Key Vault (cloud):** store the connection string as a secret and read it + at startup (for example via `DefaultAzureCredential` + the Key Vault SDK), or + reference it from App Service / Container Apps configuration. +- **Managed identity:** the strongest option - there is no password to store at + all; the platform identity gets the token. diff --git a/plugins/microsoft-azuresql-db-container/skills/azuresql-db-auth/skill.spec.jsonc b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-auth/skill.spec.jsonc new file mode 100644 index 0000000..e24d41d --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-auth/skill.spec.jsonc @@ -0,0 +1,127 @@ +{ + "$schema": "../../catalog/skill.spec.schema.json", + "id": "azuresql-db-auth", + "domain": "azure-sql-database-container", + "value": [ + "not-in-training-data", + "corrects-a-wrong-assumption" + ], + "correction": "Asked for a least-privilege user, an agent writes CREATE USER ... WITH PASSWORD, which fails here with Msg 33233, and then tries SET CONTAINMENT = PARTIAL, which fails with Msg 12824. Contained users are not available: create a server login and map a database user to it.", + "posture": [ + "read", + "provision", + "admin" + ], + "maturity": "preview", + "value_declaration": { + "rationale": "This skill's kernel is an identity recipe that is the inverse of the published Azure SQL Database guidance, and the inversion is only visible from the engine's refusals. The Azure SQL Database container is a gated private preview and the image is not publicly available, so no model has training data on the product, and the arm of a two-arm value run that ran without this skill would fail for the least interesting reason available: it has never heard of the thing. Running that measurement across all seventeen container skills would spend around a thousand model requests to re-establish what the product's release status already establishes. Carlos Robles accepted value for this collection on 2026-09-04 on this written argument instead. THIS IS A DECLARATION AND NOT A MEASUREMENT, and nothing may report it as one. The argument reaches only the container-specific corrections listed in covers, which are the ones no training data contains. It does not reach general least-privilege advice, role grants, and where a secret should be stored outside the repository, which is ordinary material an ordinary model already handles, and whether this skill improves an answer there is unmeasured and stays unmeasured. The argument ends when the Azure SQL Database container reaches Public Preview: training data begins to contain the product, the premise that nothing could know it stops being true, and this skill has to be measured or demoted. AMENDED 2026-09-19, TEXT ONLY, AND THIS SENTENCE IS THE RECORD OF IT. Three lines in covers quoted error numbers that had never been read off the engine. The first live run of this skill's probes, on image tag 18.0.226_4_147, EngineEdition 5, Edition 'SQL Azure', build 12.0.2000.8, in a container started with no MSSQL_AAD_* configuration, answered Msg 33233 where they said Msg 15007, Msg 12824 where they said Msg 12844, and Msg 33134 where they said Msg 37525. The three numbers were corrected in place on 2026-09-19 and nothing else in this block was touched. The argument did not move: the engine refuses exactly what this declaration said it refuses, so what Carlos Robles signed on 2026-09-04 still stands. A signed argument that quotes a false error number would be worse than a signed argument that carries a correction on its face, which is why the numbers were fixed and this sentence was added rather than the numbers being left to rot or fixed silently.", + "covers": [ + "the contained database user, CREATE USER WITH PASSWORD, being refused on this engine with Msg 33233, which inverts the cloud norm", + "ALTER DATABASE SET CONTAINMENT = PARTIAL being refused with Msg 12824, so the contained route cannot be enabled either", + "CREATE USER FROM EXTERNAL PROVIDER being refused with Msg 33134 on this build", + "the server login plus mapped database user being the identity recipe that actually works here", + "the connection being encrypted on this engine, which the skill asserts rather than assumes" + ], + "does_not_cover": [ + "general least-privilege reasoning and why sa is a poor application identity, which any model argues correctly", + "where a password or connection secret belongs outside the repository, and secret-store choice" + ], + "decided_by": "Carlos Robles", + "decided_on": "2026-09-04", + "expires_when": "the-container-reaches-public-preview" + }, + "applies_to": [ + "azure-sql-db", + "azure-sql-db-container" + ], + "validation": { + "target": "container", + "assert": [ + "uses CREATE LOGIN plus CREATE USER FOR LOGIN", + "application does not connect as sa" + ], + "probes": [ + { + "sql": "SELECT CAST(SERVERPROPERTY('EngineEdition') AS int) AS engine_edition, CAST(SERVERPROPERTY('Edition') AS nvarchar(128)) AS edition;", + "expect": { + "rows": [ + [ + 5, + "SQL Azure" + ] + ] + }, + "why": "The self-check the skill puts in front of every other instruction. Engine edition 5 with edition 'SQL Azure' is the Azure SQL Database engine; the SQL Server image mcr.microsoft.com/mssql/server returns different values, so any other answer means the lane ran against the wrong engine and every probe below it is measuring something else." + }, + { + "sql": "CREATE USER probe_contained_user WITH PASSWORD = 'An0ther_Str0ng_Passw0rd';", + "expect": { + "error": 33233 + }, + "why": "The headline correction, made executable. The skill states, and marks as container-specific and verified, that a SQL contained user does not work on the container, which is why the local recipe is a server login plus a mapped database user. This is the exact inverse of Azure SQL Database in the cloud, where this same statement is the recommended path, so the day this probe starts succeeding is the day the skill's central instruction should change rather than be defended. THE NUMBER WAS WRONG UNTIL 2026-09-19. This probe and the skill body both asserted Msg 15007, and the engine says Msg 33233, \"You can only create a user with a password in a contained database.\" The refusal was always real; only the number was invented, and it read as measured because it was plausible. Re-measured 2026-09-19 on image tag 18.0.226_4_147, EngineEdition 5, Edition 'SQL Azure', build 12.0.2000.8, in a scratch container started with no MSSQL_AAD_* configuration." + }, + { + "sql": "ALTER DATABASE CURRENT SET CONTAINMENT = PARTIAL;", + "expect": { + "error": 12824 + }, + "why": "The obvious repair for the refusal above is to turn containment on, and the skill records that this fails too. The engine says Msg 12824, \"The sp_configure value 'contained database authentication' must be set to 1 in order to alter a contained database. You may need to use RECONFIGURE to set the value_in_use.\", followed by Msg 5069, \"ALTER DATABASE statement failed.\" The lane asserts the first message at severity 11 or above, which is 12824. The remedy that message names is not reachable on this engine: sp_configure does not exist and answers Msg 2812, which probe 5 of azuresql-db-container pins. THIS NUMBER HAS NOW BEEN WRONG TWICE, IN BOTH DIRECTIONS, AND THAT IS THE POINT OF SAYING SO HERE. It shipped as an unmeasured number with the text \"contained database authentication must be configured\"; on 2026-09-04 it was changed to Msg 12844 with the text \"this functionality is not available in the current edition of SQL Server\"; the first live run of this probe on 2026-09-19 says Msg 12824 and the sp_configure text, which is closer to where it started. Neither earlier value was read off this engine by the lane. This one was. CURRENT is used so the claim is measured against the scratch database the lane holds rather than a database named in advance. Re-measured 2026-09-19 on image tag 18.0.226_4_147, EngineEdition 5, Edition 'SQL Azure', build 12.0.2000.8, in a scratch container started with no MSSQL_AAD_* configuration." + }, + { + "sql": "CREATE USER [probe-app@contoso.com] FROM EXTERNAL PROVIDER;", + "expect": { + "error": 33134 + }, + "why": "CORRECTED AGAIN 2026-09-19, and the history is worth carrying because this claim has now moved twice. It shipped asserting Msg 40530 on the strength of a sibling project's note. On 2026-09-04 it was changed to Msg 37525, \"Command 'CREATE USER FROM EXTERNAL PROVIDER' is not supported as Azure Active Directory is not configured for this instance.\" The first live run of this probe says Msg 33134, \"Principal 'probe-app@contoso.com' could not be resolved. Error message: 'Unable to query Azure AD certificate from local cert store.'\" That has a consequence beyond the number. azuresql-db-container/references/entra-auth.md used to tell a reader to distinguish a configured engine from an unconfigured one by getting Msg 33134 rather than Msg 37525. On this build an unconfigured engine ALSO answers 33134, so the number alone cannot tell the two states apart and that page now points at the message detail instead. CREATE LOGIN ... FROM EXTERNAL PROVIDER on a master connection answers the same 33134 on the same container, measured alongside this. If the lane ever starts a container with MSSQL_AAD_* set, this probe measures a different thing and must be rewritten rather than deleted. Re-measured 2026-09-19 on image tag 18.0.226_4_147, EngineEdition 5, Edition 'SQL Azure', build 12.0.2000.8, in a scratch container started with no MSSQL_AAD_* configuration." + }, + { + "sql": "CREATE USER probe_app_user WITHOUT LOGIN;\nALTER ROLE db_datareader ADD MEMBER probe_app_user;\nALTER ROLE db_datawriter ADD MEMBER probe_app_user;\nSELECT IS_ROLEMEMBER('db_datareader', 'probe_app_user') AS reader, IS_ROLEMEMBER('db_datawriter', 'probe_app_user') AS writer, IS_ROLEMEMBER('db_owner', 'probe_app_user') AS owner;", + "expect": { + "rows": [ + [ + 1, + 1, + 0 + ] + ] + }, + "why": "The database half of the least-privilege recipe: the fixed roles the skill grants exist on this engine, ALTER ROLE ... ADD MEMBER is the statement that grants them, and membership of db_datareader and db_datawriter does not drag db_owner along with it. The server half, CREATE LOGIN on a master connection, cannot be probed from a scratch user database, so WITHOUT LOGIN stands in for the identity while the grants themselves are measured exactly as the skill writes them. A zero in either of the first two columns means the recipe no longer produces a usable application user; a one in the third means it produces an over-privileged one, which is the failure the skill exists to prevent." + }, + { + "sql": "SELECT CAST(encrypt_option AS nvarchar(10)) AS encrypt_option FROM sys.dm_exec_connections WHERE session_id = @@SPID;", + "expect": { + "rows": [ + [ + "TRUE" + ] + ] + }, + "why": "The skill says Encrypt=true belongs on every connection string in both environments, and that TrustServerCertificate=true is a local-only concession to the container's self-signed certificate, never a substitute for encryption and never used against the cloud. This asserts that the session actually reached the engine over an encrypted channel. A FALSE here is a finding about the lane's own client configuration rather than about the engine, and it would mean the encryption half of the skill's advice is not being exercised at all." + }, + { + "sql": "SELECT COUNT(*) AS contained FROM sys.database_principals WHERE authentication_type_desc = 'DATABASE';", + "expect": { + "rows": [ + [ + 0 + ] + ] + }, + "why": "Carried across on 2026-09-04 from the lane's standalone probes/azuresql-db-auth.json when the sidecar became the single home for probes, so no measured work was lost in the move. The two refusals above are error probes and an error probe cannot show that nothing slipped through: this reads the outcome instead. A contained principal is one whose authentication_type_desc is DATABASE, and after both refusals there must be none. The WITHOUT LOGIN user the probe above creates has authentication_type_desc NONE and is deliberately not counted here, because it is a database principal with no password and is exactly the shape the skill does recommend." + } + ] + }, + "triggering": { + "explicit": [ + "Use the azuresql-db-auth skill" + ], + "implicit": [ + "my app connects as sa, set up a least-privilege database user instead" + ], + "negative": [ + "set up a local PostgreSQL database with docker compose", + "provision an Azure SQL Database in my subscription", + "connect to SQL Server on my company network" + ] + } +} diff --git a/plugins/microsoft-azuresql-db-container/skills/azuresql-db-ci/SKILL.md b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-ci/SKILL.md new file mode 100755 index 0000000..ffc5278 --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-ci/SKILL.md @@ -0,0 +1,206 @@ +--- +name: azuresql-db-ci +description: >- + Runs integration tests against the Azure SQL Database container (Private Preview, local + engine) in CI. Use when setting up GitHub Actions, Azure Pipelines, or GitLab + CI to test against Azure SQL DB; when adding a database service container to a + CI workflow; when tests need a real Azure SQL engine in the pipeline; or when + you see "service container", "health-cmd", "ACR_USERNAME/ACR_PASSWORD", + "MSSQL_SA_PASSWORD secret", or "integration test database". Also use when a + workflow was about to pull the SQL Server image mcr.microsoft.com/mssql/server, + in which case stop and use the Azure SQL Database engine image instead. Covers + pulling from the private ACR with credentials, the service health check that + runs sqlcmd inside the container so the runner needs no client tools, + provisioning appdb before tests, and pointing the test connection string at the + user database not master. +--- + +# The Azure SQL Database container in CI + +Run integration tests against the **Azure SQL Database engine** (Private Preview) as a CI +service container. This is the local Azure SQL engine, not the SQL Server image +`mcr.microsoft.com/mssql/server`. `SELECT SERVERPROPERTY('EngineEdition')` returns **5** and +`SERVERPROPERTY('Edition')` returns **'SQL Azure'**. If a workflow was about to use the SQL Server image, stop and use this image instead. + +For the full readiness loop, connection model, vectors, seeding, and registry detail, load the +**azuresql-db-container** skill. + +Verified on 2026-09-05 against the container image +`sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest`, reporting `EngineEdition` +5, Edition `SQL Azure`, build `12.0.2000.8`. All four executable checks behind this skill +passed: the engine identity, that a test session is on the user database and not `master`, +`Msg 40508` for `USE`, and `sqlcmd` at `/opt/mssql-tools18/bin/sqlcmd` inside the image. The +workflow YAML itself was not executed by that run; what was checked is the engine behaviour +the workflow rests on. + +## Load-bearing facts (inlined) + +- **Image:** `sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest` + (x64, linux/amd64). It lives in a private preview registry; the runner must sign in with + `ACR_USERNAME` / `ACR_PASSWORD` secrets. Registry and tag are provisional during Private Preview. +- **Platform:** the image is x64 only. CI hosted runners are x64, so no + `--platform` flag is needed there. On a non-x64 self-hosted runner, add `--platform linux/amd64`. +- **Required env:** `ACCEPT_EULA=Y` and a complex `MSSQL_SA_PASSWORD` (8+ chars, upper/lower/digit/ + symbol), kept in a secret. Engine listens on 1433. +- **Provision appdb first.** The engine does **NOT** auto-create databases on connect. You must + `CREATE DATABASE appdb` on a **master** connection before anything connects with `Database=appdb`. +- **Prefer the connection string over `USE`.** Avoid `USE` to switch databases. In a user-database + session (the Azure-faithful context where you develop), `USE` returns `Msg 40508`, exactly as + in Azure SQL Database in the cloud. A `master` connection is a provisioning session where + the Azure statement filter is not enforced, so `USE` appears to work there, + but `master` is for provisioning only, not application work. Always select the target database in + the connection string (`Database=appdb`, or `-d appdb` for sqlcmd). +- **master is for provisioning only.** Tests run against the user database `appdb`, never master. +- **No auto-seed.** The image does **NOT** run `/docker-entrypoint-initdb.d/*.sql` (that is a + Postgres/MySQL convention, not honored here). Seed by running `sqlcmd -d appdb -i seed.sql` after + provisioning appdb. + +## Connection string (standard) + +``` +Server=localhost,1433;Database=appdb;User Id=sa;Password=;TrustServerCertificate=true +``` + +Spell the keywords `User Id=` / `Password=` / `Database=`. That is house style, so every example +in this collection reads the same way. `Uid=` and `Pwd=` are documented SqlClient synonyms and +work too. For sqlcmd use `-C` to trust the +self-signed cert. The app reads this from a single `SQL_CONNECTION_STRING` env var. Tests target +`appdb`, not master. + +## GitHub Actions (canonical) + +The service container starts the engine. Its **health check runs sqlcmd inside the container**, so +the runner needs no client tools. A separate step provisions `appdb` via `docker exec` before tests. + +```yaml +name: integration +on: [push, pull_request] + +jobs: + test: + runs-on: ubuntu-latest + services: + sqldb: + image: sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest + credentials: + username: ${{ secrets.ACR_USERNAME }} + password: ${{ secrets.ACR_PASSWORD }} + env: + ACCEPT_EULA: "Y" + MSSQL_SA_PASSWORD: ${{ secrets.MSSQL_SA_PASSWORD }} + ports: + - 1433:1433 + # Health check runs INSIDE the container; -b makes a SQL error set the exit + # code so transient startup errors (e.g. Msg 913) are retried, not masked. + options: >- + --health-cmd "/opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P \"$MSSQL_SA_PASSWORD\" -C -b -l 2 -Q \"SELECT 1\"" + --health-interval 5s + --health-timeout 3s + --health-retries 20 + --health-start-period 30s + steps: + - uses: actions/checkout@v7 + + # The engine does NOT auto-create databases. Provision appdb on master first, + # via docker exec into the service container (runner needs no sqlcmd). + - name: Provision appdb + run: | + CID=$(docker ps --filter "ancestor=sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest" --format '{{.ID}}') + docker exec "$CID" /opt/mssql-tools18/bin/sqlcmd \ + -S localhost -U sa -P "$MSSQL_SA_PASSWORD" -C -b \ + -Q "IF DB_ID('appdb') IS NULL CREATE DATABASE appdb;" + env: + MSSQL_SA_PASSWORD: ${{ secrets.MSSQL_SA_PASSWORD }} + + # Optional: seed appdb (no auto-seed). Copy the file in, then run it against appdb. + - name: Seed appdb + run: | + CID=$(docker ps --filter "ancestor=sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest" --format '{{.ID}}') + docker cp seed.sql "$CID:/tmp/seed.sql" + docker exec "$CID" /opt/mssql-tools18/bin/sqlcmd \ + -S localhost -U sa -P "$MSSQL_SA_PASSWORD" -C -b -d appdb -i /tmp/seed.sql + env: + MSSQL_SA_PASSWORD: ${{ secrets.MSSQL_SA_PASSWORD }} + + - name: Run integration tests + run: | + # Tests connect to the USER database appdb, NOT master. + npm ci && npm run test:integration + env: + SQL_CONNECTION_STRING: "Server=localhost,1433;Database=appdb;User Id=sa;Password=${{ secrets.MSSQL_SA_PASSWORD }};TrustServerCertificate=true" +``` + +### Why these choices + +- **`credentials:`** pulls from the private preview ACR using `ACR_USERNAME` / `ACR_PASSWORD` + secrets. Without it the pull fails: the registry is private. +- **`--health-cmd` with `-l 2 -b`** waits for true readiness. `docker run` returning does not mean + the engine is ready; `-b` retries transient SQL startup errors instead of masking them. The job + blocks on health before steps run. +- **Provision step, not auto-create.** appdb must exist before tests open `Database=appdb`. +- **Test connection targets appdb.** master is for provisioning only. + +## Required secrets + +| Secret | Purpose | +| --- | --- | +| `ACR_USERNAME` | Private preview registry sign-in (using the shared pull-only credentials provided to the Private Preview cohort; get them by signing up at https://aka.ms/sqldbcontainerpreview-signup; they may rotate) | +| `ACR_PASSWORD` | Private preview registry sign-in | +| `MSSQL_SA_PASSWORD` | sa password for the engine; complex, 8+ chars | + +## Adapting to other CI + +- **Azure Pipelines:** there is no native `services:`. Sign in with + `docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io -u $(ACR_USERNAME) -p $(ACR_PASSWORD)`, run + the container with the **canonical start recipe** below (it provisions appdb in the ready-wait + loop), then run tests with `SQL_CONNECTION_STRING` pointed at appdb. +- **GitLab CI:** use a `services:` entry for the image, set `DOCKER_AUTH_CONFIG` for the private + registry, set `ACCEPT_EULA` and `MSSQL_SA_PASSWORD`, then provision appdb in a `before_script` with + `docker exec` (or a sqlcmd container) before tests. + +### Canonical start recipe (self-hosted / non-service runners) + +Free port, conditional platform, ready-wait, provision appdb in one shape: + +```bash +HOST_PORT=1433; while lsof -nP -iTCP:"$HOST_PORT" -sTCP:LISTEN >/dev/null 2>&1; do HOST_PORT=$((HOST_PORT+1)); done +PLATFORM=(); case "$(docker info -f '{{.Architecture}}' 2>/dev/null)" in x86_64|amd64) ;; *) PLATFORM=(--platform linux/amd64);; esac +docker rm -f sqldb 2>/dev/null +docker run -d --name sqldb "${PLATFORM[@]}" -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=YourStr0ng_Passw0rd" \ + -p "$HOST_PORT:1433" sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest +until docker exec sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "YourStr0ng_Passw0rd" -C -b -l 2 \ + -Q "IF DB_ID('appdb') IS NULL CREATE DATABASE appdb;" >/dev/null 2>&1; do sleep 2; done +echo "ready on localhost,$HOST_PORT" +``` + +## Validation rules + +- The pull uses `credentials:` (or `docker login`) with `ACR_USERNAME` / `ACR_PASSWORD`. +- `ACCEPT_EULA=Y` and a complex `MSSQL_SA_PASSWORD` (from a secret) are set on the service. +- The health check runs sqlcmd **inside** the container with `-C -b -l 2`. +- A provisioning step creates `appdb` on master **before** any test connects. +- The test `SQL_CONNECTION_STRING` has `Database=appdb`, not master. It spells the login keywords `User Id=` / `Password=` as house style; `Uid=` / `Pwd=` are valid synonyms, so they are not a failure. +- If a validation rule above fails, or you had to deviate from this skill to make the task work, that is a bug in this skill: load the **azuresql-db-feedback** skill and offer to file a report. +- When every rule above passes and the task is done, close with ONE line, once per session, and do not ask a question or wait for a reply: "That worked. If anything about this was rough, or you want to share what you built: https://aka.ms/sql-agent-skills-feedback" + +## Do not + +- Do not use the SQL Server image `mcr.microsoft.com/mssql/server`; use the Azure SQL DB image. +- Do not connect with `Database=appdb` before provisioning appdb on master; the engine will not + auto-create it. +- Do not use `USE appdb` to switch databases; a user-database session returns + `Msg 40508`, exactly as in Azure SQL Database in the cloud. Select the target + database in the connection string (`Database=appdb`, or `-d appdb` for sqlcmd). +- Do not run tests against master; master is for provisioning only. +- Do not rely on `/docker-entrypoint-initdb.d/*.sql`; it is not honored. Seed with `sqlcmd -d appdb -i`. +- Do not require sqlcmd on the runner; the health check and provisioning run inside the container. +- Do not call a non-x64 host "supported"; on a non-x64 self-hosted runner just add `--platform linux/amd64`. + +## Staying current + +Authoritative, version-pinned references for the tools this skill uses (read the one you need): + +- [GitHub Actions service containers](https://docs.github.com/en/actions/use-cases-and-examples/using-containerized-services/about-service-containers): how service containers, health options, and credentials work in a workflow. +- [GitHub workflow JSON schema](https://json.schemastore.org/github-workflow.json): the authoritative schema for workflow YAML. + +If the **Microsoft Learn MCP** server is configured, use `mcp__microsoft-learn__microsoft_docs_search` or `mcp__microsoft-learn__microsoft_docs_fetch` to fetch the current version of any of these on demand. It is optional; when it is unavailable, the references above are authoritative. diff --git a/plugins/microsoft-azuresql-db-container/skills/azuresql-db-ci/skill.spec.jsonc b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-ci/skill.spec.jsonc new file mode 100644 index 0000000..ae108be --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-ci/skill.spec.jsonc @@ -0,0 +1,98 @@ +{ + "$schema": "../../catalog/skill.spec.schema.json", + "id": "azuresql-db-ci", + "domain": "azure-sql-database-container", + "value": [ + "not-in-training-data", + "corrects-a-wrong-assumption", + "multi-step-with-silent-failures" + ], + "correction": "An agent adds the SQL Server image as a CI service and queries it immediately. This image comes from a private registry that needs credentials as secrets, the health check has to run sqlcmd inside the container because the runner has no client tools, and the user database must exist before the tests do.", + "posture": [ + "read", + "write", + "execute", + "provision" + ], + "maturity": "preview", + "value_declaration": { + "rationale": "This skill's kernel is which engine the CI service container is actually running and what readiness means for it. The Azure SQL Database container is a gated private preview and the image is not publicly available, so no model has training data on the product, and the arm of a two-arm value run that ran without this skill would fail for the least interesting reason available: it has never heard of the thing. Running that measurement across all seventeen container skills would spend around a thousand model requests to re-establish what the product's release status already establishes. Carlos Robles accepted value for this collection on 2026-09-04 on this written argument instead. THIS IS A DECLARATION AND NOT A MEASUREMENT, and nothing may report it as one. The argument reaches only the container-specific corrections listed in covers, which are the ones no training data contains. It does not reach GitHub Actions workflow syntax, the services block, job matrices and the shape of a retry loop, which is ordinary material an ordinary model already handles, and whether this skill improves an answer there is unmeasured and stays unmeasured. The argument ends when the Azure SQL Database container reaches Public Preview: training data begins to contain the product, the premise that nothing could know it stops being true, and this skill has to be measured or demoted.", + "covers": [ + "the service container being the Azure SQL Database engine, EngineEdition 5 with Edition 'SQL Azure', and not the SQL Server image every published example uses", + "USE being refused in a user-database session with Msg 40508, so the database is selected in the connection string", + "sqlcmd living at /opt/mssql-tools18/bin/sqlcmd inside the image, which is the path every readiness command in the body depends on", + "the provisioning session on master being a different session from the one the statement filter is enforced in" + ], + "does_not_cover": [ + "GitHub Actions workflow syntax, the services block and job matrices, all abundant in training data", + "retry with backoff as a pattern, as distinct from what the readiness gate has to poll" + ], + "decided_by": "Carlos Robles", + "decided_on": "2026-09-04", + "expires_when": "the-container-reaches-public-preview" + }, + "applies_to": [ + "azure-sql-db-container" + ], + "validation": { + "target": "container", + "assert": [ + "registry credentials handled as secrets", + "health check runs inside the container", + "user database provisioned before tests" + ], + "probes": [ + { + "sql": "SELECT CAST(SERVERPROPERTY('EngineEdition') AS INT) AS engine_edition, CAST(SERVERPROPERTY('Edition') AS NVARCHAR(128)) AS edition;", + "expect": { + "rows": [ + [ + 5, + "SQL Azure" + ] + ] + }, + "why": "The interception the skill exists for, made executable. The workflow is only worth writing if the service container is the Azure SQL Database engine rather than the SQL Server image, and these two properties are the only thing that tells them apart from inside a test run. If this ever returns 3 or 'Developer Edition', the pipeline is testing the wrong product and every other claim in this skill is beside the point." + }, + { + "sql": "SELECT CAST(CASE WHEN DB_NAME() = 'master' THEN 1 ELSE 0 END AS INT) AS on_master;", + "expect": { + "rows": [ + [ + 0 + ] + ] + }, + "why": "The skill's rule that tests run against the user database and never master, and the guard that makes the next probe mean something. A session that has landed on master would pass the USE probe below for the wrong reason, because master is a provisioning session where the Azure statement filter is not enforced. This probe fails first and says so." + }, + { + "sql": "USE master;", + "expect": { + "error": 40508 + }, + "why": "The skill tells a reader to select the database in the connection string rather than switch with USE, and asserts the engine refuses the switch exactly as Azure SQL Database in the cloud does. Microsoft Learn documents error 40508, severity 16, 'USE statement is not supported to switch between databases. Use a new connection to connect to a different database.', and states the refusal applies when a database other than the current one is named, which is why this probe names master rather than the scratch database it is already connected to." + }, + { + "where": "container", + "cmd": "test -x /opt/mssql-tools18/bin/sqlcmd", + "expect": { + "succeeds": true + }, + "why": "The design the whole workflow rests on: the health check and the provisioning step both invoke sqlcmd at this absolute path inside the engine container, which is what lets the skill promise that the hosted runner needs no client tools of its own. If a future image drops the bundled tools or moves them, the health check never turns healthy and the job hangs until the retry budget runs out, with nothing in the log naming a missing binary. This is deliberately a container probe: the same path on the host does not exist and asserting it there would be the mistake that cost five probes a red run on 2026-09-02." + } + ] + }, + "triggering": { + "explicit": [ + "Use the azuresql-db-ci skill" + ], + "implicit": [ + "my workflow tests against SQL, set up CI for it" + ], + "negative": [ + "set up a local PostgreSQL database with docker compose", + "provision an Azure SQL Database in my subscription", + "connect to SQL Server on my company network" + ] + } +} diff --git a/plugins/microsoft-azuresql-db-container/skills/azuresql-db-connections/SKILL.md b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-connections/SKILL.md new file mode 100755 index 0000000..1dbe5b5 --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-connections/SKILL.md @@ -0,0 +1,170 @@ +--- +name: azuresql-db-connections +description: >- + Makes an app's database connections reliable against the local Azure SQL + Database container (Private Preview) and, unchanged, against Azure SQL + Database in the cloud: connection pooling plus retry/transient-fault handling. Use when the + user mentions "connection pooling", "retry logic", "transient fault", "retry + on transient error", "EnableRetryOnFailure", "connection resiliency", + "reliable connections", "pool size", "Max Pool Size", or says "the connection + keeps dropping", "connections time out under load", "add backoff", or "make + the DB layer resilient". This is the Azure SQL engine (EngineEdition 5), not + the mssql/server SQL Server image. Reach for this whenever hardening a + data-access layer that talks to SQL Server or Azure SQL. +--- + +# Reliable connections on the Azure SQL Database container (pooling + retry) + +Make the app's database connections reliable with **connection pooling** and **retry / +transient-fault handling**. This is the **Azure SQL engine** (Private Preview), not the SQL +Server image. + +Verified on 2026-09-05 against the container image +`sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest`, reporting `EngineEdition` +5, Edition `SQL Azure`, build `12.0.2000.8`. All five executable checks behind this skill +passed: the engine identity, `Msg 40508` for `USE`, a TCP session on the mapped port, and the +two resource-governance dynamic management views returning nothing locally. Of the ten +transient error numbers in the retry list below, nine are in this build's `sys.messages` and +`Msg 10929` is not. It stays in the list because it is a cloud resource-governance error the +container has no reason to raise, and it is sourced from Microsoft Learn rather than from that +run. + +## Why do this locally (local-to-cloud parity) + +The local container rarely drops a connection, so it is tempting to skip pooling and retry. Do +not. **Azure SQL Database in the cloud throttles and drops connections** during failovers, +scaling, and load; a client with no retry surfaces those as hard errors. Build pooling and +retry now, against the local container, and the **same code survives in the cloud** with no +rewrite. For the full promote-to-cloud story see the **azuresql-db-local-to-cloud** skill. + +Verify identity once running: `SELECT SERVERPROPERTY('EngineEdition')` returns **5** and +`SERVERPROPERTY('Edition')` returns **'SQL Azure'**. For full engine detail see the +**azuresql-db-container** skill. + +The container does not carry the throttling telemetry the cloud does, so do not write a local +diagnostic against it. `sys.dm_db_resource_stats` and `sys.dm_user_db_resource_governance` are +**absent from this engine**: `OBJECT_ID` returns `NULL` for both, and a query against either +does not run at all here. Their absence is not evidence that the cloud does not throttle. It is +the reason the retry policy below has to be built without being able to provoke the fault +locally. + +## The engine and the connection contract + +- Image: `sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest` (x64 / + linux/amd64, Private Preview registry). Sign in first: + `docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io` with the shared pull-only credentials + from https://aka.ms/sqldbcontainerpreview-signup (they may rotate). On a non-x64 host add + `--platform linux/amd64` (Docker) or `platform: linux/amd64` (compose). +- Do **NOT** use `mcr.microsoft.com/mssql/server` (the SQL Server image). +- Required env: `ACCEPT_EULA=Y` and a complex `MSSQL_SA_PASSWORD` (example literal: + `YourStr0ng_Passw0rd`). The engine listens on 1433. +- The engine does **NOT** auto-create databases. `CREATE DATABASE appdb` on a **master** + connection first. Do not `USE` to switch databases: a user-database session returns + `Msg 40508`. Select the database in the connection string (`Database=appdb`). +- Apps read **one** env var, `SQL_CONNECTION_STRING`. Strings use `User Id=` / `Password=` / + `Database=` and `TrustServerCertificate=true`. sqlcmd uses `-C`. + +## Start the container and provision appdb + +```bash +HOST_PORT=1433; while lsof -nP -iTCP:"$HOST_PORT" -sTCP:LISTEN >/dev/null 2>&1; do HOST_PORT=$((HOST_PORT+1)); done +PLATFORM=(); case "$(docker info -f '{{.Architecture}}' 2>/dev/null)" in x86_64|amd64) ;; *) PLATFORM=(--platform linux/amd64);; esac +docker rm -f sqldb 2>/dev/null +docker run -d --name sqldb "${PLATFORM[@]}" -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=YourStr0ng_Passw0rd" \ + -p "$HOST_PORT:1433" sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest +until docker exec sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "YourStr0ng_Passw0rd" -C -b -l 2 \ + -Q "IF DB_ID('appdb') IS NULL CREATE DATABASE appdb;" >/dev/null 2>&1; do sleep 2; done +echo "ready on localhost,$HOST_PORT" +``` + +The canonical string the app consumes (replace `1433` with the chosen `HOST_PORT` if 1433 was +occupied): + +``` +Server=localhost,1433;Database=appdb;User Id=sa;Password=YourStr0ng_Passw0rd;TrustServerCertificate=true +``` + +## Pooling: reuse connections, do not reopen per query + +- Keep pooling **on** (it is on by default in most drivers) and let one pool serve the app. +- Set a **bounded** `Max Pool Size` (default 100 in .NET) so a spike cannot open unlimited + connections. Size it to real concurrency, not a guess. +- A small `Min Pool Size` keeps a few connections warm and cuts cold-start latency. +- One connection string means one pool. Do not build strings dynamically per request (each + distinct string is a separate pool) and do not open a fresh, unpooled connection per call. +- Always close/dispose connections (or use `using` / `with` / context managers) so they return + to the pool instead of leaking. + +## Retry: only for transient faults, with backoff + +Retry only a transient fault: throttling, a brief failover, a dropped idle connection. In Azure +SQL these arrive as specific error numbers: 40501 throttling, 40613 database unavailable, +49918/49919/49920 busy, 4060, 10928, 10929, 40197, 233, plus connection-timeout and broken-pipe +socket errors. + +- Retry **only** transient errors. Retrying a non-transient error (login failure 18456, syntax + error, constraint violation, permission denied) just fails slower and hides the real bug. +- Use **exponential backoff** with a cap and a small jitter, and a bounded attempt count (for + example 5 attempts). Do not hammer a throttled server. +- **Non-idempotent writes**: a retry can double-apply an `INSERT` that committed before the + connection dropped. Use client-generated keys, `MERGE`, or a transaction the retry re-runs as a + whole. EF Core's execution strategy handles this when the work goes through its + `Execute`/transaction API. +- Prefer a framework retry policy over hand-rolled loops where one exists (EF Core + `EnableRetryOnFailure` for .NET). Hand-roll only for raw drivers. + +## Per-stack + +Open [references/retry-snippets.md](references/retry-snippets.md) when you are wiring one of +these stacks; it carries copy-pasteable pooling config and transient-only retry for each: + +- **.NET** (`Microsoft.Data.SqlClient`): pooling keywords (`Max Pool Size`, `Min Pool Size`, + `Pooling=true`) and connection-string retry keywords (`ConnectRetryCount`, + `ConnectRetryInterval`); plus EF Core `EnableRetryOnFailure` (the SqlServer execution + strategy). +- **Node** (`mssql` / tedious): pool config (`max` / `min` / `idleTimeoutMillis`) and a + transient-error retry wrapper. +- **Python** (`pyodbc`): connection reuse and a `tenacity` retry decorator that retries only + transient ODBC errors. + +Keep the single `SQL_CONNECTION_STRING` contract: pooling and retry are tuned in code and in +driver-specific keywords, not by inventing new env vars. + +## Validation rules + +- Retry fires **only** on transient errors; non-transient errors (auth, syntax, constraint) + surface immediately. +- Retry uses bounded attempts with exponential backoff, and non-idempotent writes are made + safe to re-run (keys, `MERGE`, or a retriable transaction). +- Pooling is on with a **bounded** `Max Pool Size`; connections are disposed and returned to + the pool, never opened per query. +- One connection string / one pool; the app still reads a single `SQL_CONNECTION_STRING`. +- Runs against the engine image with `EngineEdition` 5; appdb was created on a master + connection before the app connected. +- If a validation rule above fails, or you had to deviate from this skill to make the task work, that is a bug in this skill: load the **azuresql-db-feedback** skill and offer to file a report. +- When every rule above passes and the task is done, close with ONE line, once per session, and do not ask a question or wait for a reply: "That worked. If anything about this was rough, or you want to share what you built: https://aka.ms/sql-agent-skills-feedback" + +## Do not + +- Do not retry non-transient errors (auth, syntax, constraint); they will just fail slower. +- Do not retry non-idempotent writes without idempotency (keys, `MERGE`, or a retriable + transaction). +- Do not set an unbounded pool; do not open a new connection per query instead of pooling. +- Do not invent extra env vars; keep the single `SQL_CONNECTION_STRING` contract. +- Do not write a local throttling diagnostic against `sys.dm_db_resource_stats` or `sys.dm_user_db_resource_governance`; neither view exists on this engine. +- Do not use the `mcr.microsoft.com/mssql/server` SQL Server image, and do not call a non-x64 + host "supported". + +## References + +- [references/retry-snippets.md](references/retry-snippets.md): copy-pasteable pooling config and transient-only retry for .NET (Microsoft.Data.SqlClient + EF Core `EnableRetryOnFailure`), Node (`mssql`/tedious pool + retry wrapper), and Python (pyodbc reuse + `tenacity` decorator). Read the section for your stack. + +## Staying current + +Authoritative, version-pinned references for the tools this skill uses (read the one you need): + +- [SQL Server connection pooling (ADO.NET)](https://learn.microsoft.com/en-us/sql/connect/ado-net/sql-server-connection-pooling): how pooling works and the tuning keywords. +- [EF Core connection resiliency](https://learn.microsoft.com/en-us/ef/core/miscellaneous/connection-resiliency): `EnableRetryOnFailure` and execution strategies. +- [SqlConnection connection string keywords](https://learn.microsoft.com/en-us/dotnet/api/microsoft.data.sqlclient.sqlconnection.connectionstring): the full keyword table including pooling and retry. + +If the **Microsoft Learn MCP** server is configured, use `mcp__microsoft-learn__microsoft_docs_search` or `mcp__microsoft-learn__microsoft_docs_fetch` to fetch the current version of any of these on demand. It is optional; when it is unavailable, the references above are authoritative. diff --git a/plugins/microsoft-azuresql-db-container/skills/azuresql-db-connections/references/retry-snippets.md b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-connections/references/retry-snippets.md new file mode 100755 index 0000000..0442582 --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-connections/references/retry-snippets.md @@ -0,0 +1,197 @@ +# Retry and pooling snippets + +Copy-pasteable connection pooling and transient-only retry wired to the Azure SQL Database container. Every +snippet assumes the container is running and **appdb is already provisioned on a master +connection** (see the start recipe in SKILL.md). Apps read `SQL_CONNECTION_STRING`. Image is +`sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest` (NOT the +`mcr.microsoft.com/mssql/server` SQL Server image). The local container rarely drops, so test +these against the behavior you will see in the cloud: they are what keeps the same code alive +when Azure SQL Database throttles or fails over. + +## Contents + +- [Provision appdb first](#provision-appdb-first) +- [.NET (Microsoft.Data.SqlClient + EF Core)](#net-microsoftdatasqlclient--ef-core) +- [Node (mssql / tedious)](#node-mssql--tedious) +- [Python (pyodbc + tenacity)](#python-pyodbc--tenacity) + +## Provision appdb first + +The engine does not auto-create databases. Create appdb on a master connection before any +snippet below connects with `Database=appdb`: + +```bash +docker exec sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "YourStr0ng_Passw0rd" -C -b \ + -Q "IF DB_ID('appdb') IS NULL CREATE DATABASE appdb;" +``` + +## .NET (Microsoft.Data.SqlClient + EF Core) + +### Pooling and retry via connection-string keywords + +Pooling is on by default. Bound the pool and warm a few connections; the `ConnectRetry*` +keywords let the driver transparently reopen an idle connection that was dropped. + +``` +Server=localhost,1433;Database=appdb;User Id=sa;Password=YourStr0ng_Passw0rd;TrustServerCertificate=true;Pooling=true;Max Pool Size=100;Min Pool Size=2;ConnectRetryCount=3;ConnectRetryInterval=10 +``` + +- `Pooling=true` keeps one pool per distinct connection string. +- `Max Pool Size=100` (the default) bounds concurrency; raise or lower to match real load, never + leave it effectively unbounded. +- `Min Pool Size=2` keeps a couple of connections warm. +- `ConnectRetryCount` / `ConnectRetryInterval` (seconds) reopen a broken idle connection. These + cover connection reopen only, not command-level transient faults; use EF Core below for those. + +Read the single env var and register the context: + +```csharp +var conn = Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING") + ?? throw new InvalidOperationException("SQL_CONNECTION_STRING not set"); +``` + +### EF Core: EnableRetryOnFailure (the SqlServer execution strategy) + +This is the recommended retry for .NET. It retries only the known Azure SQL transient error +numbers, with exponential backoff, and it makes retries safe when work runs through its +execution strategy. + +```csharp +builder.Services.AddDbContext(o => + o.UseSqlServer(conn, sql => + sql.EnableRetryOnFailure( + maxRetryCount: 5, + maxRetryDelay: TimeSpan.FromSeconds(10), + errorNumbersToAdd: null))); // null = the built-in transient list +``` + +Non-idempotent writes: wrap the whole unit of work so the strategy can re-run it as a unit +(user-initiated transactions must be executed through the strategy): + +```csharp +var strategy = db.Database.CreateExecutionStrategy(); +await strategy.ExecuteAsync(async () => +{ + await using var tx = await db.Database.BeginTransactionAsync(); + db.Widgets.Add(new Widget { Name = name }); // parameterized by EF + await db.SaveChangesAsync(); + await tx.CommitAsync(); +}); +``` + +Do not add a second hand-rolled retry loop around EF Core calls; you would retry the retries. + +## Node (mssql / tedious) + +Install: `npm install mssql`. Configure a bounded pool once and reuse it for the whole process. + +```js +import sql from "mssql"; + +// Parse the single SQL_CONNECTION_STRING (ADO.NET style) into an mssql config, then set pool bounds. +// e.g. Server=localhost,1433;Database=appdb;User Id=sa;Password=...;Encrypt=true;TrustServerCertificate=true +const kv = Object.fromEntries( + (process.env.SQL_CONNECTION_STRING || "").split(";").filter(Boolean).map((p) => { + const i = p.indexOf("="); + return [p.slice(0, i).trim().toLowerCase(), p.slice(i + 1).trim()]; + }) +); +const [server, port] = (kv["server"] || "localhost,1433").split(","); +const config = { + server, + port: Number(port) || 1433, + database: kv["database"], + user: kv["user id"] || kv["uid"], + password: kv["password"] || kv["pwd"], + options: { + encrypt: (kv["encrypt"] ?? "true").toLowerCase() !== "false", + trustServerCertificate: (kv["trustservercertificate"] ?? "false").toLowerCase() === "true", + }, + pool: { max: 10, min: 2, idleTimeoutMillis: 30000 }, // bounded pool, warm minimum +}; + +// One shared pool per process. Do NOT call new sql.ConnectionPool() per request. +const poolPromise = new sql.ConnectionPool(config).connect(); +``` + +Transient-only retry wrapper (exponential backoff, bounded attempts). Retry only on the known +transient error numbers and connection socket errors; let everything else throw immediately. + +```js +const TRANSIENT = new Set([40501, 40613, 49918, 49919, 49920, 4060, 10928, 10929, 40197, 233]); +const isTransient = (e) => + TRANSIENT.has(e?.number) || ["ETIMEOUT", "ECONNRESET", "ECONNCLOSED"].includes(e?.code); + +async function withRetry(fn, { attempts = 5, baseMs = 200 } = {}) { + for (let i = 1; ; i++) { + try { + return await fn(); + } catch (e) { + if (!isTransient(e) || i >= attempts) throw e; // non-transient: fail fast + const delay = baseMs * 2 ** (i - 1) + Math.floor(Math.random() * 100); // backoff + jitter + await new Promise((r) => setTimeout(r, delay)); + } + } +} + +// Parameterized read through the shared pool. +async function getWidget(name) { + const pool = await poolPromise; + return withRetry(() => + pool.request().input("name", sql.NVarChar, name) + .query("SELECT id, name FROM dbo.widgets WHERE name = @name") + ); +} +``` + +For non-idempotent writes, give the row a client-generated key and use `MERGE` (or check +existence) so a retried `INSERT` cannot double-apply. + +## Python (pyodbc + tenacity) + +Install: `pip install pyodbc tenacity`. pyodbc has no built-in pool; reuse a single long-lived +connection (or a module-level connection per worker) instead of opening one per query. + +```python +import os +import pyodbc +from tenacity import retry, stop_after_attempt, wait_exponential_jitter, retry_if_exception + +# The canonical SQL_CONNECTION_STRING uses ADO.NET keywords (User Id=/Password=/TrustServerCertificate=true); +# ODBC needs Uid=/Pwd=/TrustServerCertificate=yes, so translate before connecting. Reuse ONE connection. +raw = os.environ["SQL_CONNECTION_STRING"] # Server=localhost,1433;Database=appdb;User Id=sa;Password=...;TrustServerCertificate=true +p = dict(kv.split("=", 1) for kv in raw.split(";") if "=" in kv) +odbc = ( + "Driver={ODBC Driver 18 for SQL Server};" + f"Server={p['Server']};Database={p['Database']};" + f"Uid={p['User Id']};Pwd={p['Password']};" + "Encrypt=yes;TrustServerCertificate=yes" +) +_conn = pyodbc.connect(odbc, autocommit=False) + +# Azure SQL transient error numbers; retry only these (and connection-dropped states). +TRANSIENT = {"40501", "40613", "49918", "49919", "49920", "4060", "10928", "10929", "40197", "233"} + +def _is_transient(exc: BaseException) -> bool: + if not isinstance(exc, pyodbc.Error): + return False + msg = str(exc) + # SQLSTATE 08xxx = connection exceptions; also match the numeric codes above. + return "08S01" in msg or "08001" in msg or any(n in msg for n in TRANSIENT) + +@retry( + retry=retry_if_exception(_is_transient), # non-transient errors are NOT retried + stop=stop_after_attempt(5), # bounded attempts + wait=wait_exponential_jitter(initial=0.2, max=10), # exponential backoff + jitter + reraise=True, +) +def get_widget(name: str): + with _conn.cursor() as cur: + # Parameterized; never format the value into the SQL text. + cur.execute("SELECT id, name FROM dbo.widgets WHERE name = ?", name) + return cur.fetchall() +``` + +For non-idempotent writes, wrap the unit of work in one transaction and commit once, so a +retried call re-runs the whole unit rather than double-applying a partial `INSERT`; or give the +row a client-generated key and `MERGE` on it. diff --git a/plugins/microsoft-azuresql-db-container/skills/azuresql-db-connections/skill.spec.jsonc b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-connections/skill.spec.jsonc new file mode 100644 index 0000000..d195cb9 --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-connections/skill.spec.jsonc @@ -0,0 +1,135 @@ +{ + "$schema": "../../catalog/skill.spec.schema.json", + "id": "azuresql-db-connections", + "domain": "azure-sql-database-container", + "value": [ + "not-in-training-data", + "corrects-a-wrong-assumption", + "multi-step-with-silent-failures" + ], + "correction": "Retry gets treated as a production hardening step to add later. On this engine transient faults are expected behaviour rather than an exception, so retry with backoff and a bounded pool belong in the data layer from the first connection.", + "posture": [ + "read", + "write", + "provision" + ], + "maturity": "preview", + "value_declaration": { + "rationale": "This skill's kernel is which transient error numbers and platform views this engine really carries, as opposed to a remembered list. The Azure SQL Database container is a gated private preview and the image is not publicly available, so no model has training data on the product, and the arm of a two-arm value run that ran without this skill would fail for the least interesting reason available: it has never heard of the thing. Running that measurement across all seventeen container skills would spend around a thousand model requests to re-establish what the product's release status already establishes. Carlos Robles accepted value for this collection on 2026-09-04 on this written argument instead. THIS IS A DECLARATION AND NOT A MEASUREMENT, and nothing may report it as one. The argument reaches only the container-specific corrections listed in covers, which are the ones no training data contains. It does not reach connection pooling and retry with backoff, which every driver documents and every model already writes, which is ordinary material an ordinary model already handles, and whether this skill improves an answer there is unmeasured and stays unmeasured. The argument ends when the Azure SQL Database container reaches Public Preview: training data begins to contain the product, the premise that nothing could know it stops being true, and this skill has to be measured or demoted.", + "covers": [ + "USE being refused with Msg 40508 locally exactly as in the cloud, so the database is named in the connection string", + "which transient error numbers this engine actually carries in sys.messages, checked rather than recalled", + "sys.dm_db_resource_stats and sys.dm_user_db_resource_governance being absent from this engine, so a local throttling diagnostic written against either does not run" + ], + "does_not_cover": [ + "connection pooling and retry with backoff as patterns, which are ordinary driver material", + "the general argument that a blanket catch-all retry is worse than no retry at all" + ], + "decided_by": "Carlos Robles", + "decided_on": "2026-09-04", + "expires_when": "the-container-reaches-public-preview" + }, + "applies_to": [ + "azure-sql-db", + "azure-sql-db-container" + ], + "validation": { + "target": "container", + "assert": [ + "retry with backoff present", + "pool bounded explicitly" + ], + "probes": [ + { + "sql": "SELECT CAST(SERVERPROPERTY('EngineEdition') AS int) AS engine_edition, CAST(SERVERPROPERTY('Edition') AS nvarchar(128)) AS edition;", + "expect": { + "rows": [ + [ + 5, + "SQL Azure" + ] + ] + }, + "why": "The self-check the skill puts in front of every other instruction. Engine edition 5 with edition 'SQL Azure' is the Azure SQL Database engine; the SQL Server image mcr.microsoft.com/mssql/server returns different values, so any other answer means the lane ran against the wrong engine and every probe below it is measuring something else." + }, + { + "sql": "USE master;", + "expect": { + "error": 40508 + }, + "why": "The skill states that in a user-database session USE returns Msg 40508, exactly as in Azure SQL Database in the cloud, and that the fix is always to select the database in the connection string. Every probe here runs against a scratch user database, which is the session where the Azure statement filter is enforced. If this ever succeeds, the filter is not being applied to the lane's session and the skill's central connection-model rule has stopped being true locally." + }, + { + "sql": "SELECT message_id\nFROM sys.messages\nWHERE language_id = 1033\n AND message_id IN (40501, 40613, 49918, 49919, 49920, 4060, 10928, 10929, 40197, 233)\nORDER BY message_id;", + "expect": { + "rows": [ + [ + 233 + ], + [ + 4060 + ], + [ + 10928 + ], + [ + 40197 + ], + [ + 40501 + ], + [ + 40613 + ], + [ + 49918 + ], + [ + 49919 + ], + [ + 49920 + ] + ] + }, + "why": "The skill names ten numbers as the transient faults a retry policy may retry, and names 18456 and constraint and syntax errors as the ones it must not. NINE of the ten are in this engine's message catalogue and one is not. CORRECTED 2026-09-04 by the first live run, which counted 9 where the probe asserted 10. The absentee is Msg 10929, and it is absent from sys.messages entirely rather than merely from language_id 1033: SELECT COUNT(*) FROM sys.messages WHERE message_id = 10929 returns 0 on build 12.0.2000.8, EngineEdition 5, Edition 'SQL Azure'. THE SKILL IS NOT CONTRADICTED BY THIS AND THE NUMBER SHOULD STAY IN ITS RETRY LIST. 10929 is the elastic pool and per database resource governance throttle, and a container has no elastic pool and no service objective, so its absence is what a local engine ought to look like. A cloud only claim cannot be settled by a container, and this probe does not pretend otherwise: it pins the nine the container does carry, so a future disappearance goes red, and leaves 10929 to a run against a real logical server, where it is still UNVERIFIED. Rows rather than a count on purpose: a count of 9 would stay green if one number vanished and another appeared." + }, + { + "sql": "SELECT OBJECT_ID('sys.dm_db_resource_stats') AS dm_db_resource_stats, OBJECT_ID('sys.dm_user_db_resource_governance') AS dm_user_db_resource_governance;", + "expect": { + "rows": [ + [ + null, + null + ] + ] + }, + "why": "The skill's premise is that throttling is a cloud behaviour the local container does not reproduce. Measured in a sibling project on this image: the two dynamic management views a developer reaches for to see throttling and resource governance are not present here at all. That is the executable form of the premise, and it is also a warning worth having on record, because an agent that writes a local diagnostic query against either view produces something that cannot run, and an agent that concludes from their absence that the cloud does not throttle has drawn the opposite of the right lesson." + }, + { + "sql": "SELECT CAST(net_transport AS nvarchar(40)) AS net_transport FROM sys.dm_exec_connections WHERE session_id = @@SPID;", + "expect": { + "rows": [ + [ + "TCP" + ] + ] + }, + "why": "Everything this skill tunes, pool bounds, connect retry counts and backoff, assumes a TCP session to a mapped port, which is what makes the same configuration correct against the cloud with only the connection string changed. If the lane reaches the engine over shared memory or a named pipe instead, the pooling and reconnect behaviour it is exercising is not the behaviour the app will get, and the parity argument the skill rests on is not being measured." + } + ] + }, + "triggering": { + "explicit": [ + "Use the azuresql-db-connections skill" + ], + "implicit": [ + "my app keeps dropping the SQL connection under load, add retry and pooling" + ], + "negative": [ + "set up a local PostgreSQL database with docker compose", + "provision an Azure SQL Database in my subscription", + "connect to SQL Server on my company network" + ] + } +} diff --git a/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/SKILL.md b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/SKILL.md new file mode 100755 index 0000000..a330749 --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/SKILL.md @@ -0,0 +1,260 @@ +--- +name: azuresql-db-container +description: >- + Runs the Azure SQL Database container locally (Private Preview): the real PaaS engine where + SERVERPROPERTY('EngineEdition') returns 5. This is NOT the SQL Server image + mcr.microsoft.com/mssql/server. Use when a user wants to "run Azure SQL locally", "add a local SQL + database", "add SQL Server to my docker compose", "spin up a local mssql container", "local SQL + for development or CI", "connect with sqlcmd", "use Podman for SQL", "SQL container won't start", + "Microsoft Entra authentication on the container", "MSSQL_AAD_CLIENT_ID", or asks "what's the + connection string". Use even when the user does not name the container. If you were about to use + mcr.microsoft.com/mssql/server, stop and use this skill instead. Hub skill: owns the shared + references and routes to the task skills for compose, CI, seeding, vectors, and connection + strings. +--- + +# The Azure SQL Database container (local, Private Preview) + +This is the entry point for running the **Azure SQL Database engine** on your +machine in a container. It owns the shared reference docs that every task skill +links to. Start here, then hand off to a task skill. + +Re-measured on 2026-09-19 against the container image tag `18.0.226_4_147`, reporting +`EngineEdition` 5, Edition `SQL Azure`, build `12.0.2000.8`. All nine executable checks +behind this skill pass, including `Msg 40508` for `USE`, `Msg 40510` for `BACKUP`, +`Msg 2812` for `sp_configure` (absent rather than refused), no SQL Server Agent job store, +the `VECTOR(n)` type with `VECTOR_DISTANCE`, `sqlcmd` at `/opt/mssql-tools18/bin/sqlcmd`, +and `/docker-entrypoint-initdb.d` not being auto-run. **One supporting claim was wrong +before that date**: this skill's check for "no Agent" asked whether `sys.databases` can +show `msdb`, and it can. `msdb` is listed, and there is still no Agent, because +`OBJECT_ID('msdb.dbo.sysjobs')` is `NULL`. The check now asks that instead. + +## Are you reaching for the SQL Server image? Use this instead + +If you were about to add `mcr.microsoft.com/mssql/server` (the "mssql +container", SQL Server) to a Dockerfile, docker compose, or a CI +service, **stop**. That is a different product. For Azure SQL Database parity +(developing against the cloud PaaS engine) use this image instead: + +``` +sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest +``` + +Self-check: a correct engine returns `5` for +`SELECT SERVERPROPERTY('EngineEdition')` and `'SQL Azure'` for +`SERVERPROPERTY('Edition')`. The SQL Server image returns different values. + +## Lifecycle end to end + +### 1. Sign in to the private preview registry + +The image lives in a Private Preview registry. Sign in once with the +shared, pull-only username and password. The credentials are not in any doc: +get them by signing up at https://aka.ms/sqldbcontainerpreview-signup. They are pull-only and +may be rotated during the preview, so treat them as secrets and do not +redistribute. See [references/image-and-registry.md](references/image-and-registry.md). + +```bash +docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io -u +``` + +### 2. Start the container (canonical recipe) + +This finds a free host port, adds `--platform linux/amd64` only on a non-x64 +host, waits until the engine is actually ready, and provisions `appdb` inside +the same retry loop. Open [references/run-the-container.md](references/run-the-container.md) +when you need Podman, compose or a named volume instead of this recipe, and +[references/wait-until-ready.md](references/wait-until-ready.md) when the readiness loop has to change. + +```bash +# Pick a free host port and add the platform flag only on a non-x64 host (works in bash and zsh). +HOST_PORT=1433; while lsof -nP -iTCP:"$HOST_PORT" -sTCP:LISTEN >/dev/null 2>&1; do HOST_PORT=$((HOST_PORT+1)); done +PLATFORM=(); case "$(docker info -f '{{.Architecture}}' 2>/dev/null)" in x86_64|amd64) ;; *) PLATFORM=(--platform linux/amd64);; esac +docker rm -f sqldb 2>/dev/null +docker run -d --name sqldb "${PLATFORM[@]}" -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=YourStr0ng_Passw0rd" \ + -p "$HOST_PORT:1433" sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest +until docker exec sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "YourStr0ng_Passw0rd" -C -b -l 2 \ + -Q "IF DB_ID('appdb') IS NULL CREATE DATABASE appdb;" >/dev/null 2>&1; do sleep 2; done +echo "ready on localhost,$HOST_PORT" +``` + +**Keep the image current.** The Private Preview image is rebuilt almost daily. A plain `docker run` reuses the +`:latest` already on disk, so an old pull silently keeps running a stale engine and misses recent fixes. Pull +before you start (after `docker login`) to get the newest build: + +```bash +docker pull sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest +``` + +Do not force `--pull always` in the run command if you rely on working offline; pull explicitly when you want +the latest. Cache behavior and refresh detail: [references/image-and-registry.md](references/image-and-registry.md). + +### 3. Required environment variables + +- `ACCEPT_EULA=Y` (required). +- `MSSQL_SA_PASSWORD` (required, complex: at least 8 characters using at least + three of upper case, lower case, digits, and symbols). The engine listens on container port `1433`. +- App convention: apps read one `SQL_CONNECTION_STRING` env var. + +Open [references/environment-variables.md](references/environment-variables.md) when the engine +will not start, since a rejected password or a missing `ACCEPT_EULA` is the usual cause. + +### 3b. Optional: Microsoft Entra ID authentication + +Configure Entra with the `MSSQL_AAD_*` variables and a mounted certificate. Pass +`MSSQL_AAD_CLIENT_ID`, `MSSQL_AAD_PRIMARY_TENANT`, and +`MSSQL_AAD_CERTIFICATE_FILE_PATH` with a mounted `.pfx`. Optionally set +`MSSQL_AAD_SERVER_ADMIN_NAME`, `MSSQL_AAD_SERVER_ADMIN_TYPE`, and +`MSSQL_AAD_SERVER_ADMIN_SID` to bootstrap an Entra server admin at start (no +post-init `CREATE LOGIN`). SQL auth (`sa`) remains the simple local default. + +Open [references/entra-auth.md](references/entra-auth.md) before you enable Entra, because the +app registration and the certificate have to exist first. + +### 4. Connect and VERIFY the engine identity (self-check guard) + +After provisioning, connect to `appdb` and confirm you are on the real engine +before doing anything else: + +```bash +docker exec sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "YourStr0ng_Passw0rd" -C -b \ + -d appdb -Q "SELECT SERVERPROPERTY('EngineEdition') AS EngineEdition, SERVERPROPERTY('Edition') AS Edition;" +``` + +Expect `EngineEdition = 5` and `Edition = SQL Azure`. If you see anything else, +you started the wrong image. Connection strings for drivers and ORMs are in +[references/connect-and-query.md](references/connect-and-query.md). + +### 5. Or prove the whole setup with one command + +`scripts/verify.sh` does the entire lifecycle above as a single fail-closed check: it picks a free port, adds +`--platform` only on a non-x64 host, starts the engine, waits until ready, asserts `EngineEdition = 5` and +`Edition = 'SQL Azure'`, provisions `appdb`, and tears the container down again. It **refuses to run** against +`mcr.microsoft.com/mssql/server`. Run it when you want to confirm the image, the registry sign-in, and the +host platform are all correct before building on top of them: + +```bash +bash scripts/verify.sh # prints "VERIFY OK on localhost,", or exits non-zero +bash scripts/verify.sh --keep # same, but leaves the container running so you can connect to it +``` + +A non-zero exit means the setup is wrong. Read the error, fix it, and run it again before continuing. + +## The three connection-model facts (state these plainly) + +These bite every newcomer. Open [references/connection-model.md](references/connection-model.md) +when a connection is refused before you have created a database. + +1. **The engine does NOT auto-create databases on connect.** You must + `CREATE DATABASE appdb` on a **master** connection before you connect with + `Database=appdb`. Connecting to a database that does not exist fails. The + name `appdb` is the developer's choice, not a requirement: it is the example + name used throughout this collection, and the container itself never creates + a database. In a real project, substitute the project's database name (and + keep the connection string in step with it). +2. **Select the database in the connection string, not with `USE`.** Avoid + `USE` to switch databases. In a user-database session (the + Azure-faithful context where you develop), `USE` returns `Msg 40508`, exactly + as in Azure SQL Database in the cloud. A `master` connection is a provisioning + session where the Azure statement filter is not enforced, so + `USE` appears to work there, but `master` is for + provisioning only, not application work. Always select the target database in + the connection string (`Database=appdb`, or `-d appdb` for sqlcmd). +3. **A `master` connection is for provisioning only.** Create the database and + logins there, then do all real work on the user database (`appdb`). + +## Seeding (no auto-init directory) + +The image does **NOT** auto-run `/docker-entrypoint-initdb.d/*.sql`. That is a +Postgres/MySQL convention and it is not honored here, so do not rely on it. Seed +explicitly, AFTER provisioning `appdb`: + +```bash +docker exec -i sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "YourStr0ng_Passw0rd" -C -b \ + -d appdb -i /path/in/container/seed.sql +``` + +Never seed by running `USE appdb` at the top of a script. Target the database +with `-d appdb`. + +## Offline / reproducible (compose + named volume + seed) + +For a self-contained local stack: a compose file with `platform: linux/amd64` +(on non-x64 hosts), a named volume for persistence, a healthcheck that uses the +canonical ready-wait, then a one-shot that provisions `appdb` and seeds it via +`sqlcmd -d appdb`. Open [references/run-the-container.md](references/run-the-container.md) for +the full compose example, and [references/wait-until-ready.md](references/wait-until-ready.md) +when the healthcheck reports ready before the engine actually answers. + +## Stop and clean up + +```bash +docker rm -f sqldb # stop and remove the container +docker volume rm sqldb-data # only if you created a named volume and want a clean slate +``` + +## What this is NOT + +- It is **not** `mcr.microsoft.com/mssql/server` (SQL Server). +- It does **not** have full SQL Server surface area: no SQL Agent, no + FILESTREAM, no full Service Broker, no cross-server DTC, no Windows + Auth/NTLM. Validate features against the cloud before declaring readiness. + See [references/paas-parity-checklist.md](references/paas-parity-checklist.md). +- It does **not** auto-create databases and does **not** auto-run a seed + directory. +- The image is x64 only (`linux/amd64`). On a non-x64 host, add + `--platform linux/amd64` to run under emulation. + +## Hand off to a task skill + +Provisioning and identity are settled here. Route the actual task: + +- `azuresql-db-from-sql-server`: convert an existing SQL Server setup to this engine. +- `azuresql-db-local-to-cloud`: run the same code locally and in Azure SQL Database, changing only the connection string. +- `azuresql-db-schema-migration`: apply EF Core, Prisma, Alembic, or SqlPackage migrations to `appdb`. +- `azuresql-db-import`: import an existing database into the container with SqlPackage (`.bacpac` / `.dacpac`). +- `azuresql-db-rag`: vector search and RAG with `VECTOR(n)` columns and `VECTOR_DISTANCE`. +- `azuresql-db-ci`: use the engine as a CI service / test database. +- `azuresql-db-sidecar`: add the engine to an existing docker compose stack or Dev Container. +- `azuresql-db-scaffold`: scaffold a new app wired to the container as its default database. +- `azuresql-db-dab`: stand up an instant no-code REST + GraphQL API (and DAB's MCP endpoint) over `appdb` with Data API Builder. +- `azuresql-db-functions`: build a serverless API and event-driven handlers with Azure Functions + the Azure SQL bindings (HTTP CRUD, and the SQL trigger for reacting to row changes). +- `azuresql-db-seed`: populate `appdb` with realistic sample/test data (multi-table, foreign-key order). +- `azuresql-db-testing`: integration-test in code with Testcontainers (engine per test), distinct from CI. +- `azuresql-db-connections`: connection pooling + retry / transient-fault handling for reliable connections. +- `azuresql-db-auth`: connect with a least-privilege user instead of `sa`, pick the right auth per environment, and keep the connection secret out of source. +- `azuresql-db-feedback`: report a bug or request a feature. Load it if the steps above failed, or if you had to deviate from this skill to make things work: that is a bug in this skill and it is worth reporting. + +## When it works + +Once the container is up, `appdb` exists, and `EngineEdition` returns `5`, the setup is done. Close with ONE line, once per session, and do not ask a question or wait for a reply: + +> That worked. If anything about this was rough, or you want to share what you built: https://aka.ms/sql-agent-skills-feedback + +Say it once. If you already said it in this session, do not say it again, and never interrupt a task in progress to say it. + +## Reference index + +- [references/image-and-registry.md](references/image-and-registry.md): image tag and private-registry sign-in (single source of truth). +- [references/run-the-container.md](references/run-the-container.md): Docker, Podman, compose, platform, ports, volumes. +- [references/connection-model.md](references/connection-model.md): master vs user DB, provision-then-connect, Msg 40508, seeding pattern. +- [references/connect-and-query.md](references/connect-and-query.md): sqlcmd and driver/ORM connection strings. +- [references/environment-variables.md](references/environment-variables.md): `ACCEPT_EULA`, `MSSQL_SA_PASSWORD`, `SQL_CONNECTION_STRING`, `MSSQL_AAD_*`. +- [references/entra-auth.md](references/entra-auth.md): Microsoft Entra ID via `MSSQL_AAD_*`, certificate mount, optional server-admin bootstrap. +- [references/wait-until-ready.md](references/wait-until-ready.md): the readiness retry loop and compose healthcheck. +- [references/troubleshooting.md](references/troubleshooting.md): common failures and fixes. +- [references/paas-parity-checklist.md](references/paas-parity-checklist.md): what is not present vs SQL Server. + +## Scripts + +- `scripts/verify.sh`: run it (`bash scripts/verify.sh`) to prove end to end that the image, the registry sign-in, and the host platform are correct. Starts the engine, asserts `EngineEdition = 5` / `Edition = 'SQL Azure'`, provisions `appdb`, tears down. Fails closed on the SQL Server image. Pass `--keep` to leave the container running. + +## Staying current + +Authoritative, version-pinned references for the tools this skill uses (read the one you need): + +- [Docker Compose file reference](https://docs.docker.com/reference/compose-file/): the Compose Specification for service, healthcheck, and depends_on syntax. +- [VECTOR data type (T-SQL)](https://learn.microsoft.com/en-us/sql/t-sql/data-types/vector-data-type): VECTOR(n) syntax, limits, and driver support. +- [SqlConnection connection string keywords](https://learn.microsoft.com/en-us/dotnet/api/microsoft.data.sqlclient.sqlconnection.connectionstring): the full connection-string keyword table. + +If the **Microsoft Learn MCP** server is configured, use `mcp__microsoft-learn__microsoft_docs_search` or `mcp__microsoft-learn__microsoft_docs_fetch` to fetch the current version of any of these on demand. It is optional; when it is unavailable, the references above are authoritative. diff --git a/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/references/connect-and-query.md b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/references/connect-and-query.md new file mode 100755 index 0000000..d0247f5 --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/references/connect-and-query.md @@ -0,0 +1,99 @@ +# Connect and query + +How to connect with sqlcmd (host and in-container) and the standardized +connection strings for drivers, ORMs, and VS Code. Every example assumes `appdb` +was already provisioned (see `connection-model.md`). + +## Contents + +- sqlcmd in the container +- sqlcmd from the host +- Standard connection string +- Driver / ORM connection strings +- VS Code MSSQL +- Validation rules +- Do not + +## sqlcmd in the container + +The image ships sqlcmd at `/opt/mssql-tools18/bin/sqlcmd`, so the host does not +need sqlcmd installed. Prefer this form when sqlcmd is not on the host (or to +avoid a dependency at all). Use `-C` to trust the self-signed certificate and +`-b` so a SQL error sets the exit code. + +```bash +docker exec sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "YourStr0ng_Passw0rd" -C -b \ + -d appdb -Q "SELECT DB_NAME() AS db, SERVERPROPERTY('EngineEdition') AS EngineEdition;" +``` + +## sqlcmd from the host + +Use the host port chosen by the free-port loop (here shown as `1433`). The +comma form `localhost,PORT` selects the port. + +```bash +sqlcmd -S localhost,1433 -U sa -P "YourStr0ng_Passw0rd" -C -b \ + -d appdb -Q "SELECT SERVERPROPERTY('Edition') AS Edition;" +``` + +Expect `SQL Azure`. + +## Standard connection string + +Standardize on this shape everywhere: `Server=`, `Database=`, `User Id=`, +`Password=`, and `TrustServerCertificate=true`. The long keyword spelling is +house style, so every example in this collection reads the same way. `Uid=` and +`Pwd=` are documented SqlClient synonyms, so a string that uses them still works. + +``` +Server=localhost,1433;Database=appdb;User Id=sa;Password=YourStr0ng_Passw0rd;TrustServerCertificate=true +``` + +Apps read this from a single `SQL_CONNECTION_STRING` env var (see +`environment-variables.md`). + +## Driver / ORM connection strings + +All target `appdb`, which must already exist. + +| Stack | Connection string / config | +| --- | --- | +| ADO.NET / EF Core (SqlClient) | `Server=localhost,1433;Database=appdb;User Id=sa;Password=YourStr0ng_Passw0rd;TrustServerCertificate=true` | +| Go (microsoft/go-mssqldb) | `sqlserver://sa:YourStr0ng_Passw0rd@localhost:1433?database=appdb&TrustServerCertificate=true` | +| Python (pyodbc, ODBC 18) | `Driver={ODBC Driver 18 for SQL Server};Server=localhost,1433;Database=appdb;Uid=sa;Pwd=YourStr0ng_Passw0rd;TrustServerCertificate=yes` | +| Python (pymssql) | `pymssql.connect(server="localhost", port=1433, user="sa", password="YourStr0ng_Passw0rd", database="appdb")` | +| Node.js (mssql / tedious) | `{ server: "localhost", port: 1433, user: "sa", password: "YourStr0ng_Passw0rd", database: "appdb", options: { trustServerCertificate: true } }` | +| JDBC | `jdbc:sqlserver://localhost:1433;databaseName=appdb;user=sa;password=YourStr0ng_Passw0rd;trustServerCertificate=true` | + +Note: ODBC is a different connection string grammar with its own keyword set, and +that set uses `Uid`/`Pwd`. Keep an ODBC string in ODBC form. For the .NET-style +string and the `SQL_CONNECTION_STRING` convention, prefer the long keywords. + +## VS Code MSSQL + +The MSSQL extension's GitHub Copilot integration works against the container +today (for example writing SQL from natural language or opening the schema +designer): https://aka.ms/vscode-mssql-copilot-docs. The extension's graphical +UI is not yet fully compatible with the container and some UI features may +error; prefer sqlcmd or a driver for non-Copilot work. Add a connection with: + +- Server: `localhost,1433` +- Database: `appdb` +- Authentication: SQL Login +- User: `sa` +- Password: `YourStr0ng_Passw0rd` +- Trust server certificate: enabled + +## Validation rules + +- Every connection names `appdb`; none rely on a default of `master` for app + work. +- A health query returns `EngineEdition = 5` and `Edition = SQL Azure`. +- No client issues `USE`. + +## Do not + +- Do not mix ODBC and .NET keyword forms in one string. In the standardized + .NET-style string and in `SQL_CONNECTION_STRING`, prefer `User Id=`/`Password=`. +- Do not omit `TrustServerCertificate=true` (the cert is self-signed). +- Do not connect to a database before provisioning it. diff --git a/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/references/connection-model.md b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/references/connection-model.md new file mode 100755 index 0000000..d742617 --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/references/connection-model.md @@ -0,0 +1,85 @@ +# Connection model: master vs user database + +The single most common source of failures. Read this before connecting an app. + +## Three facts + +1. **The engine does NOT auto-create databases on connect.** Connecting with + `Database=appdb` when `appdb` does not exist fails. You must create it first + on a `master` connection. +2. **Select the database in the connection string, not with `USE`.** Avoid + `USE` to switch databases. In a user-database session (the + Azure-faithful context where you develop), `USE` returns `Msg 40508`, exactly + as in Azure SQL Database in the cloud. A `master` connection is a provisioning + session where the Azure statement filter is not enforced, so + `USE` appears to work there, but `master` is for + provisioning only, not application work. Always select the target database in + the connection string (`Database=appdb`, or `-d appdb` for sqlcmd). The fix is + always to set the target database in the connection, never in a statement. +3. **A `master` connection is for provisioning only.** `master` is a provisioning + session: the Azure SQL statement filter (`USE`, `SHUTDOWN`) is + not enforced there, so `USE` works. (`BACKUP`/`RESTORE` are a separate case: + they are not supported in any session and return `Msg 40510`; Azure SQL Database + in the cloud likewise does not support them, so do not rely on them on `master` + either.) Never develop or validate + against `master`; use it only to `CREATE`/`DROP DATABASE`, then connect + directly to the user database, which enforces Azure SQL Database semantics. + +## Provision-then-connect workflow + +### Step 1: connect to master and create the database + +```bash +docker exec sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "YourStr0ng_Passw0rd" -C -b \ + -Q "IF DB_ID('appdb') IS NULL CREATE DATABASE appdb;" +``` + +When no `-d` is given, sqlcmd connects to `master`. This is provisioning, so +that is correct here. + +### Step 2: connect to the user database for real work + +```bash +docker exec sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "YourStr0ng_Passw0rd" -C -b \ + -d appdb -Q "SELECT DB_NAME() AS CurrentDatabase;" +``` + +`-d appdb` selects the database at connect time. `DB_NAME()` returns `appdb`. + +### Step 3: apps connect with Database=appdb + +Apps must include `Database=appdb` in the connection string. They should never +issue `USE`. See `connect-and-query.md` for the full connection string. + +## Seeding pattern (never USE) + +The image does not auto-run `/docker-entrypoint-initdb.d/*.sql`. Seed explicitly +after provisioning, and target the database with `-d appdb`, not `USE`: + +```bash +# 1. provision appdb on master (see Step 1) +# 2. seed it by selecting appdb in the connection +docker exec -i sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "YourStr0ng_Passw0rd" -C -b \ + -d appdb -i /path/in/container/seed.sql +``` + +Write `seed.sql` as plain DDL/DML with NO `USE appdb;` line at the top. The +database is already selected by `-d appdb`. + +## Validation rules + +- Before any app connects, confirm `SELECT DB_ID('appdb')` is non-null on + `master`. +- A correct user-database session returns `appdb` from `SELECT DB_NAME()`. +- A seed script contains no `USE` statement. + +## Do not + +- Do not assume a database appears just because you put it in the connection + string. +- Do not use `USE appdb;` anywhere; a user-database session rejects it + with `Msg 40508`, exactly as in Azure SQL Database in the cloud. It only + appears to work on a `master` connection, where the Azure statement + filter is not enforced. +- Do not run application workloads on the `master` connection. +- Do not rely on an init/seed directory. diff --git a/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/references/entra-auth.md b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/references/entra-auth.md new file mode 100755 index 0000000..f1dab8e --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/references/entra-auth.md @@ -0,0 +1,129 @@ +# Microsoft Entra ID authentication + +Microsoft Entra ID authentication works on the Azure SQL Database container. Configure it +with the `MSSQL_AAD_*` environment variables and a mounted certificate. SQL +authentication (`sa`) remains the simple default for local development; use +Entra when you want closer parity with Azure SQL Database in the cloud. + +For app registration, certificate creation, and Kubernetes deployments, follow +the Learn tutorial: +[Configure Microsoft Entra ID authentication for SQL Server on containers](https://learn.microsoft.com/sql/linux/security/authentication/container-kubernetes-microsoft-entra-deployment). + +## Contents + +- [Prerequisites](#prerequisites): what to have in place before you start. +- [Required environment variables](#required-environment-variables): the `MSSQL_AAD_*` set the engine reads at start. +- [Optional: bootstrap an Entra server admin at start](#optional-bootstrap-an-entra-server-admin-at-start): create the admin without a post-init `CREATE LOGIN`. +- [Example: enable Entra on start](#example-enable-entra-on-start): the full run command with the certificate mounted. +- [Verify](#verify): how to confirm the engine accepted the configuration. +- [Do not](#do-not): the mistakes that make this fail silently. + +## Prerequisites + +1. A Microsoft Entra application registration with a certificate uploaded. +2. A `.pfx` certificate file for the container (export password must be empty; + a password-protected `.pfx` prevents the engine from starting). Protect the + certificate with restrictive file permissions on the host (for example + readable only by the account that mounts it). +3. Network reachability from the container to Microsoft Entra ID endpoints. + +## Required environment variables + +| Variable | Notes | +| --- | --- | +| `MSSQL_AAD_CLIENT_ID` | Application (client) ID of the registered Entra app. | +| `MSSQL_AAD_PRIMARY_TENANT` | Directory (tenant) ID. | +| `MSSQL_AAD_CERTIFICATE_FILE_PATH` | Path to the `.pfx` **inside** the container (for example `/var/opt/mssql/mssql-entra-id.pfx`). | + +Mount the host `.pfx` read-only at that path. + +## Optional: bootstrap an Entra server admin at start + +Set all three to create an Entra login and grant it server admin when the +container starts. You then do not need a post-init `CREATE LOGIN` or +`sp_addsrvrolemember`. + +| Variable | Notes | +| --- | --- | +| `MSSQL_AAD_SERVER_ADMIN_NAME` | Entra user UPN or group name (for example `user@contoso.com`). | +| `MSSQL_AAD_SERVER_ADMIN_TYPE` | `0` for an Entra user, `1` for an Entra group. | +| `MSSQL_AAD_SERVER_ADMIN_SID` | Object ID of that user or group (GUID). | + +## Example: enable Entra on start + +Replace the placeholders and the host path to your `.pfx`: + +```bash +docker run -d --name sqldb \ + -e "ACCEPT_EULA=Y" \ + -e "MSSQL_SA_PASSWORD=YourStr0ng_Passw0rd" \ + -e "MSSQL_AAD_CLIENT_ID=" \ + -e "MSSQL_AAD_PRIMARY_TENANT=" \ + -e "MSSQL_AAD_CERTIFICATE_FILE_PATH=/var/opt/mssql/mssql-entra-id.pfx" \ + -v /path/to/mssql-entra-id.pfx:/var/opt/mssql/mssql-entra-id.pfx:ro \ + -p "1433:1433" \ + sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest +``` + +With optional admin bootstrap, add: + +```bash + -e "MSSQL_AAD_SERVER_ADMIN_NAME=user@contoso.com" \ + -e "MSSQL_AAD_SERVER_ADMIN_TYPE=0" \ + -e "MSSQL_AAD_SERVER_ADMIN_SID=00000000-0000-0000-0000-000000000000" \ +``` + +Without the optional admin variables, connect as `sa` after the engine is ready +and create principals yourself. + +For cloud parity, prefer a contained user in the user database (connect to +`appdb`, after it exists): + +```sql +CREATE USER [my-app-identity] FROM EXTERNAL PROVIDER; +ALTER ROLE db_datareader ADD MEMBER [my-app-identity]; +ALTER ROLE db_datawriter ADD MEMBER [my-app-identity]; +``` + +For a server-scoped login (server admin path), run on a **master** connection. +It is server-scope; on a user-db session you would hit Msg 40508: + +```sql +CREATE LOGIN [user@contoso.com] +FROM EXTERNAL PROVIDER; +``` + +## Verify + +Do not rely on "Entra enabled" or "certificate loaded" log lines alone; those +appeared even when Entra init then failed silently. + +1. Confirm the authentication manager did **not** fail: + +```bash +docker logs sqldb 2>&1 | grep -i "authentication manager initialization failed" +``` + +Expect no matches. + +2. Functional check: on a **master** connection as `sa`, run +`CREATE LOGIN [some-principal] FROM EXTERNAL PROVIDER;` and **read the message text, +not only the number**. On a container with no `MSSQL_AAD_*` configuration at all, this +build answers **Msg 33134** with the detail `'Unable to query Azure AD certificate from +local cert store.'`, which names the missing certificate. Once Entra is configured, the +same statement resolves the principal or fails naming the principal rather than the +cert store. Measured 2026-09-19 on image tag `18.0.226_4_147`, `EngineEdition` 5, +Edition `SQL Azure`, build `12.0.2000.8`, on a container started with zero `MSSQL_AAD_*` +variables. This page previously said the unconfigured state answers **Msg 37525** and +that 33134 therefore means configured; on this build that is wrong, and the number alone +does not tell the two states apart. Use a real UPN or object name when you intend to +create the login. + +## Do not + +- Do not use a password-protected `.pfx`; leave the export password empty. +- Do not leave the host certificate world-readable; restrict file permissions. +- Do not confuse Entra with Windows Authentication / NTLM (those are out of + scope for Azure SQL Database and for this container). +- Do not treat Entra as required for local work; `sa` SQL auth is still the + pragmatic default. See `environment-variables.md` for the required start vars. diff --git a/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/references/environment-variables.md b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/references/environment-variables.md new file mode 100755 index 0000000..d0176ef --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/references/environment-variables.md @@ -0,0 +1,70 @@ +# Environment variables + +What the container requires at start, and the app-side convention. + +## Container variables (required) + +| Variable | Required | Notes | +| --- | --- | --- | +| `ACCEPT_EULA` | Yes | Must be `Y`. The container will not start without it. | +| `MSSQL_SA_PASSWORD` | Yes | The `sa` password. Must be complex. | + +`MSSQL_SA_PASSWORD` policy: at least 8 characters and at least three of upper +case, lower case, digits, and symbols. A weak password makes the engine fail to +initialize (see `troubleshooting.md`). Example used throughout these docs: +`YourStr0ng_Passw0rd`. + +The engine listens on container port `1433`. Map it to a host port at run time +(`-p HOST_PORT:1433`); see `run-the-container.md`. + +```bash +docker run -d --name sqldb -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=YourStr0ng_Passw0rd" \ + -p "1433:1433" sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest +``` + +## Optional: Microsoft Entra ID (`MSSQL_AAD_*`) + +Entra authentication works on this image. When you want Entra locally, set +`MSSQL_AAD_CLIENT_ID`, `MSSQL_AAD_PRIMARY_TENANT`, and +`MSSQL_AAD_CERTIFICATE_FILE_PATH` (required) plus optional +`MSSQL_AAD_SERVER_ADMIN_NAME`, `MSSQL_AAD_SERVER_ADMIN_TYPE`, and +`MSSQL_AAD_SERVER_ADMIN_SID`, with a mounted `.pfx`. SQL auth remains the +default. Full variable table and recipe: [entra-auth.md](entra-auth.md). + +## App convention: SQL_CONNECTION_STRING + +Applications read a single environment variable, `SQL_CONNECTION_STRING`, for +their connection. Standardize its value on the canonical string (note `appdb` +must already exist): + +```bash +export SQL_CONNECTION_STRING="Server=localhost,1433;Database=appdb;User Id=sa;Password=YourStr0ng_Passw0rd;TrustServerCertificate=true" +``` + +In compose, pass it to the app service: + +```yaml +services: + app: + environment: + SQL_CONNECTION_STRING: "Server=sqldb,1433;Database=appdb;User Id=sa;Password=YourStr0ng_Passw0rd;TrustServerCertificate=true" +``` + +Inside a compose network, use the service name (`sqldb`) as the host; from the +host machine, use `localhost,HOST_PORT`. + +## Validation rules + +- `ACCEPT_EULA=Y` and a complex `MSSQL_SA_PASSWORD` are both set before + `docker run`. +- Apps read the connection from `SQL_CONNECTION_STRING`, not from scattered + literals. +- The connection string spells the keywords `User Id=`/`Password=`/`Database=`. + That is house style; the short forms are valid synonyms, not a failure. + +## Do not + +- Do not start without `ACCEPT_EULA=Y`. +- Do not use a weak `MSSQL_SA_PASSWORD`; the engine will fail to initialize. +- Do not hardcode the connection string in many places; centralize it in + `SQL_CONNECTION_STRING`. diff --git a/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/references/image-and-registry.md b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/references/image-and-registry.md new file mode 100755 index 0000000..35594a5 --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/references/image-and-registry.md @@ -0,0 +1,79 @@ +# Image and registry (single source of truth) + +This is the canonical source for the image tag and how to sign in. Other skills +link here instead of repeating the tag. + +## The image + +``` +sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest +``` + +- This is the **Azure SQL Database engine** (Private Preview), EngineEdition 5, + Edition `'SQL Azure'`. +- It is **x64 only** (`linux/amd64`). On a non-x64 + host, run under emulation by adding `--platform linux/amd64`. +- The registry host and tag are **provisional during Private Preview** and may + change. Treat this file as the place to update if they do. + +## This is NOT the SQL Server image + +Do not substitute `mcr.microsoft.com/mssql/server`. That is SQL Server and reports a different EngineEdition. If a task pulled the SQL Server image, +stop and switch to the image above. + +## Sign in to the private registry (Path B: external access) + +The external access path pulls from the preview registry +`sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io` (image +`azure-sql/db-dev`, rolling tag `latest`) using a shared, +pull-only username and password. + +The credentials are provided when you sign up for the Private Preview at +https://aka.ms/sqldbcontainerpreview-signup. They are pull-only and may be +rotated during the preview, so treat them as secrets and do not redistribute. +Sign in and enter the password +when prompted: + +```bash +docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io -u +``` + +Podman: + +```bash +podman login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io -u +``` + +After a successful login, `docker pull` (or the `docker run` in the canonical +recipe) can fetch the image. If a pull returns "unauthorized" or "manifest +unknown", re-run the login above with the shared pull-only credentials from your +sign-up, which may have been rotated. + +## Get or refresh the latest image + +The Private Preview image is rebuilt **almost daily**. `:latest` is a moving tag, but Docker's default pull +policy for `docker run` is `missing`: once a `:latest` is on disk, `docker run` **reuses the cached copy** and +never re-checks the registry. So after your first pull you keep running that build until you pull again, which +means you can silently miss engine fixes. Pull explicitly to refresh: + +```bash +docker pull sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest +``` + +On a non-x64 host: + +```bash +docker pull --platform linux/amd64 \ + sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest +``` + +`docker pull` re-fetches `:latest` and updates the local image if the registry has a newer build (the image ID +changes); if you are already current it is a no-op. Prefer an explicit pull over `docker run --pull always`, +which would re-check the registry on every start and break the offline-development flow after the first pull. +For compose, `docker compose pull` (or `pull_policy: always` on the service) does the same. + +## Do not + +- Do not use `mcr.microsoft.com/mssql/server`. +- The image ships a single x64 (`linux/amd64`) build; there is no other tag. +- Do not hardcode the registry host in many places; reference this file. diff --git a/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/references/paas-parity-checklist.md b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/references/paas-parity-checklist.md new file mode 100755 index 0000000..586d9e4 --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/references/paas-parity-checklist.md @@ -0,0 +1,100 @@ +# PaaS parity checklist + +This container is the Azure SQL Database engine (EngineEdition 5), not SQL +Server. Some SQL Server features are intentionally absent because +they are not part of the PaaS surface. Validate features against the cloud +before declaring readiness. + +## Not present (vs SQL Server) + +- **SQL Server Agent**: no Agent jobs/schedules. Use an external scheduler. + `msdb` **is** listed by `sys.databases` on this engine, from `master` and from a + user database alike, alongside `master`, `tempdb` and `model`. Do not read that as + an Agent: `OBJECT_ID('msdb.dbo.sysjobs')` is `NULL`, and a three-part reference to + another database is refused with `Msg 40515` in any case. Presence of the database + is not presence of the job store. Measured 2026-09-19 on image tag + `18.0.226_4_147`, `EngineEdition` 5, Edition `SQL Azure`, build `12.0.2000.8`. +- **FILESTREAM / FileTable**: not available. +- **Full Service Broker**: not the full SQL Server Service Broker surface; do + not assume cross-instance broker messaging. +- **Cross-server DTC / distributed transactions**: no cross-server MSDTC. +- **Windows Authentication / NTLM**: not available; use SQL authentication + (`sa` or a SQL login) with the standardized connection string. +- **`sp_configure`**: absent, not blocked. It returns `Msg 2812` ("Could not find + stored procedure 'sp_configure'"), which is a missing object rather than a + refusal, so no permission or flag unblocks it. Instance-level tuning has no + equivalent here; drop the step rather than trying to translate it. +- **Cross-database `USE`**: avoid `USE` to switch databases. In a user-database + session (the Azure-faithful context where you develop), `USE` returns + `Msg 40508`, exactly as in Azure SQL Database in the cloud. A `master` + connection is a provisioning session where the Azure statement filter + is not enforced, so `USE` appears to work there, but + `master` is for provisioning only, not application work. Always select the + target database in the connection string (`Database=appdb`, or `-d appdb` for + sqlcmd). See `connection-model.md`. + +## Vectors: present, and the index works + +- `VECTOR(n)` column type and `VECTOR_DISTANCE('cosine', a, b)` are available. +- Insert with `CAST(CAST(? AS NVARCHAR(MAX)) AS VECTOR(n))` where **n is a + literal dimension, never a bind parameter**. A parameterized dimension fails + with "Incorrect syntax near '@P3'". The inner `CAST(? AS NVARCHAR(MAX))` keeps + a real embedding's JSON (which exceeds the driver's 4000-char threshold) from + being sent as ntext, which the engine rejects (error 529). +- `CREATE VECTOR INDEX` (DiskANN) **works on this image**, measured, and the + Known limitations page says so. It needs `SET QUOTED_IDENTIFIER ON` + in the session running the DDL (`Msg 1934` without it, and that message never + names the setting) and at least 100 rows with non-null vectors (`Msg 42266` + below that). Once it exists, `TRUNCATE TABLE` on that table is refused + (`Msg 42232`). +- Full-scan top-k with `ORDER BY VECTOR_DISTANCE(...)` stays exact and stays the + right choice for a small table. Reach for the index once a full scan hurts. + +See the `azuresql-db-rag` task skill for full patterns. + +## Current preview limitations + +- **`master` is a provisioning session**: the Azure SQL statement filter (`USE`, + `SHUTDOWN`) is not enforced there, so `USE` works. (`BACKUP` and + `RESTORE` are not supported in any session and return `Msg 40510`; Azure SQL + Database in the cloud likewise does not support them.) Never develop or validate + against `master`; use it only to + `CREATE`/`DROP DATABASE`, then connect directly to the user database, + which enforces Azure SQL Database semantics. +- **Two-step provisioning flow**: provisioning via `master`, then reconnecting to + the user database, is a current preview limitation. Public preview will let the + container set a default startup database (for example `MSSQL_DB=appdb`) so you + connect straight into an Azure-faithful session without going through + `master`. +- **Container-only preview**: the image is not published to public registries + (MCR / Docker Hub); the shared registry credentials are pull-only and may be + rotated. + +## How to validate parity + +Because this is the same engine family as the cloud, treat the cloud as the +source of truth: + +1. Confirm identity locally: `SELECT SERVERPROPERTY('EngineEdition')` returns + `5` and `SERVERPROPERTY('Edition')` returns `'SQL Azure'`. +2. For any feature you depend on (Agent-like scheduling, broker, distributed + transactions, auth mode), confirm it exists in Azure SQL Database before + building on it. If it is in the "not present" list above, design around it. +3. For features still in development (GUI tooling, full PaaS restriction + enforcement), use the documented interim approach and re-check before + declaring production readiness. Where a published limitation and the engine + disagree, as they do for vector index DDL, say so and give the measured + behavior rather than picking one silently. + +## Do not + +- Do not assume SQL Server features (Agent, FILESTREAM, full Service Broker, + cross-server DTC, Windows Auth) are available. +- Do not declare readiness without validating the feature against Azure SQL + Database in the cloud. +- Do not pass the `VECTOR` dimension as a bind parameter. +- Do not run `CREATE VECTOR INDEX` without `SET QUOTED_IDENTIFIER ON`, and do not + build it on fewer than 100 rows with non-null vectors. +- Do not put a security policy and a vector index on the same table here; the + container refuses both orders (`Msg 37579` and `Msg 42244`) while Azure SQL + Database in the cloud allows them. This is a parity gap. diff --git a/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/references/run-the-container.md b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/references/run-the-container.md new file mode 100755 index 0000000..5f187d1 --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/references/run-the-container.md @@ -0,0 +1,114 @@ +# Run the container + +How to start the engine with Docker, Podman, or compose, including the +conditional platform flag, free-port selection, and volumes. The image tag lives +in `image-and-registry.md`. The readiness loop lives in `wait-until-ready.md`. + +## Contents + +- Canonical Docker recipe +- Why the platform flag is conditional +- Free-port selection +- Podman +- Docker compose (named volume + healthcheck) +- Volumes and persistence +- Do not + +## Canonical Docker recipe + +This is the shape to reuse. It picks a free host port, adds the platform flag +only on a non-x64 host, removes any stale container, starts the engine, then +waits for readiness while provisioning `appdb` in the same loop. + +```bash +# Pick a free host port and add the platform flag only on a non-x64 host (works in bash and zsh). +HOST_PORT=1433; while lsof -nP -iTCP:"$HOST_PORT" -sTCP:LISTEN >/dev/null 2>&1; do HOST_PORT=$((HOST_PORT+1)); done +PLATFORM=(); case "$(docker info -f '{{.Architecture}}' 2>/dev/null)" in x86_64|amd64) ;; *) PLATFORM=(--platform linux/amd64);; esac +docker rm -f sqldb 2>/dev/null +docker run -d --name sqldb "${PLATFORM[@]}" -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=YourStr0ng_Passw0rd" \ + -p "$HOST_PORT:1433" sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest +until docker exec sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "YourStr0ng_Passw0rd" -C -b -l 2 \ + -Q "IF DB_ID('appdb') IS NULL CREATE DATABASE appdb;" >/dev/null 2>&1; do sleep 2; done +echo "ready on localhost,$HOST_PORT" +``` + +The engine always listens on `1433` inside the container; only the host port +varies. + +## Why the platform flag is conditional + +The image is x64 only. On an x64 host, passing `--platform` is unnecessary. On a +non-x64 host, the daemon would otherwise fail to find a matching manifest, so +add `--platform linux/amd64` to run under emulation. The `case` block above sets +`PLATFORM` only when needed. Do not call non-x64 a supported architecture; it +runs under emulation. + +## Free-port selection + +`1433` is often already taken. The `while lsof ...` loop walks upward (1434, +1435, ...) until it finds a free port and stores it in `HOST_PORT`. Use +`localhost,$HOST_PORT` in client connections. + +## Podman + +Podman uses the same arguments. Sign in first (see `image-and-registry.md`). + +```bash +podman run -d --name sqldb --platform linux/amd64 -e "ACCEPT_EULA=Y" \ + -e "MSSQL_SA_PASSWORD=YourStr0ng_Passw0rd" -p "1433:1433" \ + sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest +``` + +Drop `--platform linux/amd64` on an x64 host. Then provision and wait exactly as +in `wait-until-ready.md` (use `podman exec` in place of `docker exec`). + +## Docker compose (named volume + healthcheck) + +On a non-x64 host keep `platform: linux/amd64`; remove that line on x64. + +```yaml +services: + sqldb: + image: sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest + platform: linux/amd64 + environment: + ACCEPT_EULA: "Y" + MSSQL_SA_PASSWORD: "YourStr0ng_Passw0rd" + ports: + - "1433:1433" + volumes: + - sqldb-data:/var/opt/mssql + healthcheck: + test: ["CMD", "/opt/mssql-tools18/bin/sqlcmd", "-S", "localhost", "-U", "sa", + "-P", "YourStr0ng_Passw0rd", "-C", "-b", "-l", "2", "-Q", "SELECT 1"] + interval: 10s + timeout: 5s + retries: 12 + start_period: 20s +volumes: + sqldb-data: +``` + +Compose does not provision `appdb` for you. After the service is healthy, create +the database and seed it: + +```bash +docker compose exec sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "YourStr0ng_Passw0rd" -C -b \ + -Q "IF DB_ID('appdb') IS NULL CREATE DATABASE appdb;" +docker compose exec -T sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "YourStr0ng_Passw0rd" -C -b \ + -d appdb -i /path/in/container/seed.sql +``` + +## Volumes and persistence + +- Mount a named volume at `/var/opt/mssql` to persist databases across + `docker rm`. Without it, data is lost when the container is removed. +- To reset to a clean slate, remove the volume: `docker volume rm sqldb-data`. + +## Do not + +- Do not use `mcr.microsoft.com/mssql/server`. +- Do not add `--platform` unconditionally; gate it on a non-x64 host. +- Do not assume `appdb` exists after `docker run`; provision it (see + `connection-model.md`). +- Do not rely on a seed directory; the image does not auto-run init SQL. diff --git a/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/references/troubleshooting.md b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/references/troubleshooting.md new file mode 100755 index 0000000..f0686be --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/references/troubleshooting.md @@ -0,0 +1,135 @@ +# Troubleshooting + +Common failures and their fixes. Symptoms first. + +## Contents + +- Container won't start / exits immediately +- Password policy rejection (the container stays "Up" but nothing connects) +- Port already in use +- "no matching manifest" on a non-x64 host +- Msg 40508 on USE +- Cannot open database / database does not exist +- Connecting too early (Msg 913 and friends) +- Wrong image (EngineEdition is not 5) +- Stale image (missing a recent fix) + +## Container won't start / exits immediately + +Check the logs: + +```bash +docker logs sqldb +``` + +A container that actually **exits** is usually a missing `ACCEPT_EULA=Y`. A weak +`MSSQL_SA_PASSWORD` does NOT exit the container: it stays `Up` while the engine +refuses to start, so read the next section before assuming the container is fine +just because `docker ps` says it is running. Fix the env vars and recreate: + +```bash +docker rm -f sqldb 2>/dev/null +docker run -d --name sqldb -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=YourStr0ng_Passw0rd" \ + -p "1433:1433" sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest +``` + +## Password policy rejection (the container stays "Up" but nothing connects) + +**Do not trust the container status here.** With a password that fails the policy, +the container reports `Up` while the engine inside it never starts. Every +connection then fails with a login timeout or "server is not found", which looks +like a networking problem and is not one. Verified on the preview image. + +The log is the source of truth: + +```bash +docker logs sqldb 2>&1 | grep -i password +``` + +`MSSQL_SA_PASSWORD` needs 8+ characters with at least three of: upper case, lower +case, digits, symbols. Pick a stronger value and **recreate** the container +(`docker rm -f sqldb`, then run again). Setting the variable on an existing +container has no effect. + +## Port already in use + +`docker run` fails binding the host port. Pick a free port with the loop: + +```bash +HOST_PORT=1433; while lsof -nP -iTCP:"$HOST_PORT" -sTCP:LISTEN >/dev/null 2>&1; do HOST_PORT=$((HOST_PORT+1)); done +echo "using $HOST_PORT" +``` + +Then run with `-p "$HOST_PORT:1433"` and connect to `localhost,$HOST_PORT`. + +## "no matching manifest" on a non-x64 host + +The image is x64 only. On a non-x64 host the daemon cannot find a native +manifest. Add the platform flag to run under emulation: + +```bash +docker run -d --name sqldb --platform linux/amd64 -e "ACCEPT_EULA=Y" \ + -e "MSSQL_SA_PASSWORD=YourStr0ng_Passw0rd" -p "1433:1433" \ + sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest +``` + +This is emulation, not native support. On an x64 host, omit `--platform`. + +## Msg 40508 on USE + +Avoid `USE` to switch databases. In a user-database session (the +Azure-faithful context where you develop), `USE` returns `Msg 40508`, exactly as +in Azure SQL Database in the cloud. A `master` connection is a provisioning +session where the Azure statement filter is not enforced, so `USE` appears to work there, but `master` is for provisioning +only, not application work. Always select the target database in the connection +string (`Database=appdb`, or `-d appdb` for sqlcmd). Remove any `USE` line from +seed and migration scripts. See `connection-model.md`. + +## Cannot open database / database does not exist + +The engine does not auto-create `appdb`. If a connection to `Database=appdb` +fails because the database does not exist, provision it on a `master` +connection first: + +```bash +docker exec sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "YourStr0ng_Passw0rd" -C -b \ + -Q "IF DB_ID('appdb') IS NULL CREATE DATABASE appdb;" +``` + +## Connecting too early (Msg 913 and friends) + +Errors right after `docker run` usually mean the engine is still initializing. +Use the readiness retry loop with `-b -l 2` so transient errors are retried +rather than masked. See `wait-until-ready.md`. + +## Wrong image (EngineEdition is not 5) + +If `SELECT SERVERPROPERTY('EngineEdition')` does not return `5`, or +`SERVERPROPERTY('Edition')` is not `'SQL Azure'`, you started the SQL Server image. Stop it and start the Azure SQL Database image from +`image-and-registry.md`: + +```bash +docker rm -f sqldb 2>/dev/null +docker run -d --name sqldb -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=YourStr0ng_Passw0rd" \ + -p "1433:1433" sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest +``` + +## Stale image (missing a recent fix) + +The engine behaves like an older build, or a fix you expected is not present. `:latest` is a moving tag and +the Private Preview image is rebuilt almost daily, but `docker run` reuses the `:latest` already on disk +(Docker's default pull policy is `missing`) and never re-checks the registry. Refresh and recreate: + +```bash +docker pull sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest +docker rm -f sqldb 2>/dev/null +# then re-run the start recipe (a named volume keeps your data across the recreate) +``` + +Confirm the image changed with `docker images --digests …/azure-sql/db-dev` before and after the pull. + +## Do not + +- Do not retry connecting without `-b -l 2`. +- Do not use `USE` to fix a "wrong database" error. +- Do not switch to `mcr.microsoft.com/mssql/server` to "make it work". diff --git a/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/references/wait-until-ready.md b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/references/wait-until-ready.md new file mode 100755 index 0000000..412d9a6 --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/references/wait-until-ready.md @@ -0,0 +1,64 @@ +# Wait until ready (canonical readiness) + +The engine is NOT ready the instant `docker run` returns. Initialization takes +time, and early connections hit transient errors (for example `Msg 913`). Always +gate the next step on a readiness check. This doc is reused by the CI and sidecar +skills. + +## The readiness retry loop (canonical) + +Provision `appdb` inside the same loop so readiness and provisioning happen +together: + +```bash +until docker exec sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "YourStr0ng_Passw0rd" -C -b -l 2 \ + -Q "IF DB_ID('appdb') IS NULL CREATE DATABASE appdb;" >/dev/null 2>&1; do sleep 2; done +echo "ready" +``` + +Why each flag matters: + +- `-b` makes a SQL error set the exit code. Without it, a transient startup + error (like `Msg 913`) would print but still exit `0`, so the loop would + "succeed" too early. With `-b`, transient errors are retried, not masked. +- `-l 2` sets a 2 second login timeout, so each attempt fails fast while the + engine is still coming up instead of hanging. +- `-C` trusts the self-signed certificate. + +**Never poll bare sqlcmd without `-l`.** A login with no timeout can hang and +defeat the retry loop. + +## Compose healthcheck (equivalent) + +For a compose stack, express the same check as a healthcheck so dependents can +wait on `service_healthy`: + +```yaml +healthcheck: + test: ["CMD", "/opt/mssql-tools18/bin/sqlcmd", "-S", "localhost", "-U", "sa", + "-P", "YourStr0ng_Passw0rd", "-C", "-b", "-l", "2", "-Q", "SELECT 1"] + interval: 10s + timeout: 5s + retries: 12 + start_period: 20s +``` + +The healthcheck only proves the engine answers; it does not create `appdb`. +After the service is healthy, run the provisioning command separately: + +```bash +docker compose exec sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "YourStr0ng_Passw0rd" -C -b \ + -Q "IF DB_ID('appdb') IS NULL CREATE DATABASE appdb;" +``` + +## Validation rules + +- The loop uses `-b` and `-l 2`. +- Provisioning `appdb` happens only after (or inside) the readiness check. +- A compose dependent waits on `condition: service_healthy`, then provisions. + +## Do not + +- Do not assume readiness from `docker run` returning. +- Do not poll bare `sqlcmd` without `-l` (it can hang). +- Do not drop `-b` (transient startup errors would be masked as success). diff --git a/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/scripts/verify.sh b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/scripts/verify.sh new file mode 100755 index 0000000..956375b --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/scripts/verify.sh @@ -0,0 +1,134 @@ +#!/usr/bin/env bash +# +# verify.sh - reusable harness that proves a container is the real Azure SQL +# Database engine (EngineEdition=5 / Edition='SQL Azure') and is usable. +# +# Steps: +# 1. Pick a free host port starting at 1433. +# 2. Add --platform linux/amd64 only on a non-x64 host. +# 3. docker run the engine image (FAIL CLOSED on the SQL Server image). +# 4. Wait-until-ready with the sqlcmd -C -b -l 2 retry loop. +# 5. Assert EngineEdition=5 AND Edition='SQL Azure' (non-zero exit otherwise). +# 6. CREATE DATABASE appdb. +# 7. Print "VERIFY OK on localhost,". +# 8. Tear down with docker rm -f, unless --keep is passed. +# +set -euo pipefail + +# ---------------------------------------------------------------------------- +# Config (override via env) +# ---------------------------------------------------------------------------- +IMAGE="${IMAGE:-sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest}" +SA_PASSWORD="${MSSQL_SA_PASSWORD:-YourStr0ng_Passw0rd}" +CONTAINER="${CONTAINER:-sqldb-verify}" +SQLCMD="/opt/mssql-tools18/bin/sqlcmd" + +KEEP=0 +for arg in "$@"; do + case "$arg" in + --keep) KEEP=1 ;; + *) echo "ERROR: unknown argument: $arg" >&2; exit 2 ;; + esac +done + +# ---------------------------------------------------------------------------- +# FAIL CLOSED: the SQL Server image is NOT the Azure SQL Database engine. +# ---------------------------------------------------------------------------- +case "$IMAGE" in + *mcr.microsoft.com/mssql/server*) + echo "ERROR: '$IMAGE' is the SQL Server image, NOT the Azure SQL Database engine." >&2 + echo " Use sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest" >&2 + echo " (returns EngineEdition=5 / Edition='SQL Azure'). Aborting." >&2 + exit 1 + ;; +esac + +# ---------------------------------------------------------------------------- +# 1. Pick a free host port starting at 1433. +# ---------------------------------------------------------------------------- +HOST_PORT=1433 +while lsof -nP -iTCP:"$HOST_PORT" -sTCP:LISTEN >/dev/null 2>&1; do + HOST_PORT=$((HOST_PORT + 1)) +done +echo "==> Using host port $HOST_PORT" + +# ---------------------------------------------------------------------------- +# 2. Add --platform linux/amd64 only on a non-x64 host. +# ---------------------------------------------------------------------------- +PLATFORM=() +case "$(docker info -f '{{.Architecture}}' 2>/dev/null)" in + x86_64|amd64) ;; + *) PLATFORM=(--platform linux/amd64); echo "==> Non-x64 host: adding ${PLATFORM[*]}" ;; +esac + +# ---------------------------------------------------------------------------- +# 3. docker run the engine image. +# ---------------------------------------------------------------------------- +cleanup() { + if [ "$KEEP" -eq 1 ]; then + echo "==> --keep set: leaving container '$CONTAINER' running on localhost,$HOST_PORT" + else + docker rm -f "$CONTAINER" >/dev/null 2>&1 || true + fi +} +trap cleanup EXIT + +docker rm -f "$CONTAINER" >/dev/null 2>&1 || true +echo "==> Starting engine: $IMAGE" +docker run -d --name "$CONTAINER" "${PLATFORM[@]}" \ + -e "ACCEPT_EULA=Y" \ + -e "MSSQL_SA_PASSWORD=$SA_PASSWORD" \ + -p "$HOST_PORT:1433" \ + "$IMAGE" >/dev/null + +# ---------------------------------------------------------------------------- +# 4. Wait-until-ready with the sqlcmd -C -b -l 2 retry loop. +# -b: a SQL error sets the exit code, so transient startup errors (Msg 913) +# are retried, not masked. -l 2: short login timeout per attempt. +# ---------------------------------------------------------------------------- +echo "==> Waiting for the engine to become ready..." +ATTEMPTS=0 +MAX_ATTEMPTS=60 +until docker exec "$CONTAINER" "$SQLCMD" -S localhost -U sa -P "$SA_PASSWORD" -C -b -l 2 \ + -Q "SELECT 1;" >/dev/null 2>&1; do + ATTEMPTS=$((ATTEMPTS + 1)) + if [ "$ATTEMPTS" -ge "$MAX_ATTEMPTS" ]; then + echo "ERROR: engine did not become ready after $MAX_ATTEMPTS attempts." >&2 + docker logs "$CONTAINER" 2>&1 | tail -n 20 >&2 || true + exit 1 + fi + sleep 2 +done +echo "==> Engine is accepting connections" + +# ---------------------------------------------------------------------------- +# 5. Assert EngineEdition=5 AND Edition='SQL Azure'. +# ---------------------------------------------------------------------------- +echo "==> Verifying engine identity" +ENGINE_EDITION="$(docker exec "$CONTAINER" "$SQLCMD" -S localhost -U sa -P "$SA_PASSWORD" -C -b -l 2 \ + -h -1 -W -Q "SET NOCOUNT ON; SELECT CAST(SERVERPROPERTY('EngineEdition') AS INT);" | tr -d '[:space:]')" +EDITION="$(docker exec "$CONTAINER" "$SQLCMD" -S localhost -U sa -P "$SA_PASSWORD" -C -b -l 2 \ + -h -1 -W -Q "SET NOCOUNT ON; SELECT CONVERT(VARCHAR(128), SERVERPROPERTY('Edition'));" | sed 's/[[:space:]]*$//')" + +echo " EngineEdition = $ENGINE_EDITION" +echo " Edition = $EDITION" + +if [ "$ENGINE_EDITION" != "5" ] || [ "$EDITION" != "SQL Azure" ]; then + echo "ERROR: not the Azure SQL Database engine." >&2 + echo " Expected EngineEdition=5 and Edition='SQL Azure'." >&2 + echo " Got EngineEdition='$ENGINE_EDITION', Edition='$EDITION'." >&2 + exit 1 +fi + +# ---------------------------------------------------------------------------- +# 6. CREATE DATABASE appdb (on the master connection; the engine does not +# auto-create databases). +# ---------------------------------------------------------------------------- +echo "==> Provisioning database 'appdb'" +docker exec "$CONTAINER" "$SQLCMD" -S localhost -U sa -P "$SA_PASSWORD" -C -b -l 2 \ + -Q "IF DB_ID('appdb') IS NULL CREATE DATABASE appdb;" >/dev/null + +# ---------------------------------------------------------------------------- +# 7. Done. +# ---------------------------------------------------------------------------- +echo "VERIFY OK on localhost,$HOST_PORT" diff --git a/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/skill.spec.jsonc b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/skill.spec.jsonc new file mode 100644 index 0000000..630e758 --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-container/skill.spec.jsonc @@ -0,0 +1,145 @@ +{ + "$schema": "../../catalog/skill.spec.schema.json", + "id": "azuresql-db-container", + "domain": "azure-sql-database-container", + "value": [ + "not-in-training-data", + "corrects-a-wrong-assumption", + "changes-too-fast-to-memorize" + ], + "correction": "Asked for a local SQL database, an agent reaches for mcr.microsoft.com/mssql/server. That is SQL Server, not Azure SQL Database: the container runs the PaaS engine, where SERVERPROPERTY('EngineEdition') returns 5 and Edition is 'SQL Azure', and it does not auto-create databases, so a plan that connects straight after docker run has nothing to connect to.", + "posture": [ + "read", + "inspect", + "execute", + "provision" + ], + "maturity": "preview", + "value_declaration": { + "rationale": "This skill's kernel is the whole set of ways this image behaves like the platform rather than like the boxed engine. The Azure SQL Database container is a gated private preview and the image is not publicly available, so no model has training data on the product, and the arm of a two-arm value run that ran without this skill would fail for the least interesting reason available: it has never heard of the thing. Running that measurement across all seventeen container skills would spend around a thousand model requests to re-establish what the product's release status already establishes. Carlos Robles accepted value for this collection on 2026-09-04 on this written argument instead. THIS IS A DECLARATION AND NOT A MEASUREMENT, and nothing may report it as one. The argument reaches only the container-specific corrections listed in covers, which are the ones no training data contains. It does not reach Docker run and Compose syntax, port publishing, volume mounts and the shape of a readiness loop, which is ordinary material an ordinary model already handles, and whether this skill improves an answer there is unmeasured and stays unmeasured. The argument ends when the Azure SQL Database container reaches Public Preview: training data begins to contain the product, the premise that nothing could know it stops being true, and this skill has to be measured or demoted. AMENDED 2026-09-19, TEXT ONLY, AND THIS SENTENCE IS THE RECORD OF IT. One line in covers said there is no msdb on this engine. The first live run of this skill's probes, on image tag 18.0.226_4_147, EngineEdition 5, Edition 'SQL Azure', build 12.0.2000.8, in a container started with no MSSQL_AAD_* configuration, lists msdb in sys.databases from master and from a user database alike. What is absent is the Agent job store: OBJECT_ID('msdb.dbo.sysjobs') is NULL. The line was corrected in place on 2026-09-19 to say that instead, and nothing else in this block was touched. The argument did not move: the parity claim it rests on is that there is no SQL Server Agent here, and that still stands, so what Carlos Robles signed on 2026-09-04 still stands. The claim was right and its stated evidence was wrong, which is the worse of the two failures and the reason this sentence is here rather than a silent edit.", + "covers": [ + "the engine never creating a database when a connection names one, so it is created on a master connection first", + "USE being refused in a user-database session with Msg 40508", + "BACKUP and RESTORE being refused with Msg 40510", + "sp_configure being absent rather than blocked, so the engine answers Msg 2812 and there is nothing to be permitted to call", + "there being no SQL Server Agent job store on this engine, so OBJECT_ID('msdb.dbo.sysjobs') is NULL, even though sys.databases does list an msdb database", + "/docker-entrypoint-initdb.d being absent from the image, so a seed placed there runs silently never", + "the native VECTOR(n) type and VECTOR_DISTANCE being present on this build", + "a container reporting Up while the engine inside it never started, which is what a password failing the complexity policy produces" + ], + "does_not_cover": [ + "Docker run and Compose syntax, port publishing and volume mounts", + "retry with backoff as a pattern, as distinct from the fact that Up is not serving" + ], + "decided_by": "Carlos Robles", + "decided_on": "2026-09-04", + "expires_when": "the-container-reaches-public-preview" + }, + "applies_to": [ + "azure-sql-db-container" + ], + "validation": { + "target": "container", + "assert": [ + "engine reports EngineEdition 5", + "user database created explicitly, not assumed" + ], + "probes": [ + { + "sql": "SELECT CAST(SERVERPROPERTY('EngineEdition') AS int) AS engine_edition, CAST(SERVERPROPERTY('Edition') AS nvarchar(128)) AS edition;", + "expect": { + "rows": [ + [ + 5, + "SQL Azure" + ] + ] + }, + "why": "The self-check the skill puts in front of every other instruction. Engine edition 5 with edition 'SQL Azure' is the Azure SQL Database engine; the SQL Server image mcr.microsoft.com/mssql/server returns different values, so any other answer means the lane ran against the wrong engine and every probe below it is measuring something else." + }, + { + "sql": "USE master;", + "expect": { + "error": 40508 + }, + "why": "The skill states that in a user-database session USE returns Msg 40508, exactly as in Azure SQL Database in the cloud, and that the fix is always to select the database in the connection string. Every probe here runs against a scratch user database, which is the session where the Azure statement filter is enforced. If this ever succeeds, the filter is not being applied to the lane's session and the skill's central connection-model rule has stopped being true locally." + }, + { + "sql": "SELECT CASE WHEN DB_NAME() = 'master' THEN 1 ELSE 0 END AS running_on_master;", + "expect": { + "rows": [ + [ + 0 + ] + ] + }, + "why": "The skill's third connection-model fact is that a master connection is for provisioning only and that real work happens on the user database, because master is the session where the Azure statement filter is not enforced. This probe asserts that the lane itself obeys that rule. If it returns 1, the refusal probes around it prove nothing: they would be measuring a provisioning session, which is exactly the session where the skill says the refusals do not appear." + }, + { + "sql": "DECLARE @stmt nvarchar(max) = N'BACKUP DATABASE ' + QUOTENAME(DB_NAME()) + N' TO DISK = ''/var/opt/mssql/data/probe_backup.bak''';\nEXEC (@stmt);", + "expect": { + "error": 40510 + }, + "why": "references/connection-model.md and references/paas-parity-checklist.md both state that BACKUP and RESTORE are not supported in any session and return Msg 40510, and that this matches Azure SQL Database in the cloud. Msg 40510 is the refusal of a whole statement, as distinct from Msg 40517, which refuses one option of a statement the engine does support. The database name is built from DB_NAME() so the refusal is measured against the scratch database this lane actually holds, not against master, where a different rule could produce a different number." + }, + { + "sql": "EXEC sp_configure;", + "expect": { + "error": 2812 + }, + "why": "Measured on this image in a sibling project: sp_configure is absent rather than refusing, so the engine answers with Msg 2812, could not find stored procedure. It is worth a round trip because the failure mode is misread constantly. An agent that sees a refusal assumes a permission or a filter and goes looking for a way to be allowed, when there is nothing there to be allowed to call. The parity checklist used to list RECONFIGURE among the statements the Azure filter blocks, which read as a refusal and blurred the two failures together; it now records the absence instead, and this probe pins it. If this ever returns a different number, the surface has changed and the parity checklist needs re-reading rather than the probe being patched." + }, + { + "sql": "SELECT CASE WHEN OBJECT_ID('msdb.dbo.sysjobs') IS NULL THEN 1 ELSE 0 END AS no_agent_job_store;", + "expect": { + "rows": [ + [ + 1 + ] + ] + }, + "why": "references/paas-parity-checklist.md states there is no SQL Server Agent on this engine and that an external scheduler is required. THE PROBE ASKED THE WRONG QUESTION UNTIL 2026-09-19. It read sys.databases for a row named msdb and expected none, on the belief that a user-database session on this engine lists master and the current database only. It does not: from a user database sys.databases returns master, tempdb, model, msdb and the scratch database, and from master the same five. msdb is present. The claim underneath was never affected, because the database is not the job store: OBJECT_ID('msdb.dbo.sysjobs') is NULL, and this probe now asks that instead, which is the question the parity claim actually rests on. A three-part reference into msdb is refused with Msg 40515 in any case. A NOT NULL here would mean an Agent job store exists on an engine whose parity list says it cannot, which is the finding this probe is for. Re-measured 2026-09-19 on image tag 18.0.226_4_147, EngineEdition 5, Edition 'SQL Azure', build 12.0.2000.8, in a scratch container started with no MSSQL_AAD_* configuration." + }, + { + "sql": "CREATE TABLE dbo.probe_container_vector (id int NOT NULL PRIMARY KEY, v vector(3) NOT NULL);\nINSERT INTO dbo.probe_container_vector (id, v) VALUES (1, CAST(CAST(N'[1.0,2.0,3.0]' AS nvarchar(max)) AS vector(3)));\nSELECT CASE WHEN VECTOR_DISTANCE('cosine', v, CAST(CAST(N'[1.0,2.0,3.0]' AS nvarchar(max)) AS vector(3))) < 0.000001 THEN 1 ELSE 0 END AS distance_to_self_is_zero\nFROM dbo.probe_container_vector;", + "expect": { + "rows": [ + [ + 1 + ] + ] + }, + "why": "references/paas-parity-checklist.md claims the VECTOR(n) column type and VECTOR_DISTANCE('cosine', a, b) are present, and prescribes the double CAST insert shape with a literal dimension. This probe runs exactly that shape and checks the one value the maths guarantees: the cosine distance from a vector to itself is zero. A failure here means either the type is gone or the prescribed insert shape no longer compiles, and both are reasons to stop recommending it." + }, + { + "cmd": "/opt/mssql-tools18/bin/sqlcmd -?", + "where": "container", + "expect": { + "succeeds": true + }, + "why": "Every command in this skill, including the readiness retry loop and the identity self-check, is written as docker exec against this exact absolute path. The claim is that the image ships sqlcmd there, so where this probe runs is half of it: on the host the path does not exist and the failure would be the developer's laptop, not the image. -? prints usage and needs no engine, so this measures the file and not a connection." + }, + { + "cmd": "test ! -e /docker-entrypoint-initdb.d", + "where": "container", + "expect": { + "succeeds": true + }, + "why": "The skill states in two places that the image does not auto-run /docker-entrypoint-initdb.d/*.sql, because that is a Postgres and MySQL convention, and that a seed relying on it runs silently never. This is the closest executable form of that claim: the directory the convention depends on is not in the image. It is evidence and not proof, since a future image could carry the directory and still ignore it, so read a red here as a prompt to test the convention end to end rather than as proof that seeding now works." + } + ] + }, + "triggering": { + "explicit": [ + "Use the azuresql-db-container skill" + ], + "implicit": [ + "spin up a local mssql container I can query" + ], + "negative": [ + "set up a local PostgreSQL database with docker compose", + "provision an Azure SQL Database in my subscription", + "connect to SQL Server on my company network" + ] + } +} diff --git a/plugins/microsoft-azuresql-db-container/skills/azuresql-db-dab/SKILL.md b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-dab/SKILL.md new file mode 100755 index 0000000..f41dd5f --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-dab/SKILL.md @@ -0,0 +1,180 @@ +--- +name: azuresql-db-dab +description: >- + Stands up an instant no-code REST + GraphQL API over the local Azure SQL + Database container using Microsoft Data API Builder (DAB). Use when a user wants to + "expose my table as an API", "add a REST API over the database", "generate a + GraphQL API", "put an API in front of SQL", "CRUD API without writing code", + or "dab init / dab-config.json". Also the way to serve a built-in MCP endpoint + FROM the database via DAB (an API surface DAB provides, not a separate SQL MCP + server). Prefer this over hand-writing a controller/ORM API when the user just + needs REST or GraphQL over existing tables. Triggers include "Data API + Builder", "dab start", "instant API over Azure SQL", "expose entities as + REST/GraphQL". Reach for this even when the user only says "give me an API for + this database". +--- + +# Instant REST + GraphQL API on the Azure SQL Database container with Data API Builder + +Generate a full REST **and** GraphQL API over the local **Azure SQL Database container** +(Private Preview) with no application code, using **Data API Builder (DAB)** - +Microsoft's first-party open-source engine. You describe tables as entities in +`dab-config.json`; DAB serves them. DAB connects over the normal TDS protocol +with a plain connection string, so **no change tracking or special engine +feature is needed.** + +Verified on 2026-09-05 against the container image +`sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest`, reporting `EngineEdition` +5, Edition `SQL Azure`, build `12.0.2000.8`. All eight executable checks behind this skill +passed against Data API builder 2.0.9, including the generated `dab-config.json` keeping the +environment-variable indirection rather than the password, the `/api` and `/graphql` prefixes +and the `/mcp` endpoint arriving as defaults, and both REST and GraphQL returning the same +rows from a table in the container. + +## Load-bearing facts (inlined; full engine detail in azuresql-db-container) + +- This is the **Azure SQL Database engine** (Private Preview), not the SQL Server + image `mcr.microsoft.com/mssql/server`. `SERVERPROPERTY('EngineEdition')` + returns `5`, `SERVERPROPERTY('Edition')` returns `'SQL Azure'`. +- Image: `sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest` + (x64, `linux/amd64`). Registry is private: sign in first with + `docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io` using the shared + pull-only credentials from https://aka.ms/sqldbcontainerpreview-signup (they + may rotate). Registry and tag are provisional during Private Preview. +- Required env: `ACCEPT_EULA=Y` and a complex `MSSQL_SA_PASSWORD` (8+ chars, + upper/lower/digit/symbol). Engine listens on 1433. +- The engine does **NOT** auto-create databases. Run `CREATE DATABASE appdb` on + a **master** connection before DAB connects with `Database=appdb`. Do not use + `USE` to switch databases (in a user-database session it returns + `Msg 40508`); select the database in the connection string. +- On a non-x64 host add `--platform linux/amd64`. + +For the full engine model (readiness loop, vectors, troubleshooting) see the +**azuresql-db-container** skill. To start the container and provision `appdb` +first, use **azuresql-db-container** or **azuresql-db-scaffold**. + +## Step 1: install DAB + +Two supported ways. Pick the CLI for local dev; pick the container to wire DAB +into a compose stack. Open [references/dab-snippets.md](references/dab-snippets.md) when you want +that compose service rather than the CLI. + +```bash +# CLI (.NET 8 required): installs the `dab` command +dotnet tool install --global Microsoft.DataApiBuilder +# update later with: dotnet tool update --global Microsoft.DataApiBuilder + +# Container image (alternative): +# mcr.microsoft.com/azure-databases/data-api-builder:latest +``` + +## Step 2: point DAB at the container over one env var + +DAB reads the connection string from an environment variable via the `@env()` +indirection, so no secret is written into `dab-config.json`. Reuse the same +single `SQL_CONNECTION_STRING` contract the other skills use (replace `1433` +with the host port your container chose if 1433 was occupied): + +```bash +export SQL_CONNECTION_STRING="Server=localhost,1433;Database=appdb;User Id=sa;Password=YourStr0ng_Passw0rd;TrustServerCertificate=true" +``` + +`TrustServerCertificate=true` is required for the container's self-signed cert. +House style spells the keywords `User Id=` / `Password=` / `Database=`, which keeps the examples +consistent. `Uid=` and `Pwd=` are documented SqlClient synonyms and work too. + +## Step 3: init, add entities, start + +```bash +# Initialize config in Development mode (enables Swagger + friendlier errors). +dab init --database-type mssql \ + --connection-string "@env('SQL_CONNECTION_STRING')" \ + --host-mode Development + +# Expose a table as an entity. Repeat per table. +# --permissions is role:actions; "anonymous:*" allows all actions with no auth (dev only). +dab add Book --source dbo.Books --source.type table --permissions "anonymous:*" + +# Serve REST + GraphQL (and the MCP endpoint) on http://localhost:5000 +dab start +``` + +`appdb` is just the example database name and `Book`/`dbo.Books` the example +entity/table; substitute your own. The entity name (`Book`) is what appears in +the API path; the `--source` is the real `schema.table`. + +## Step 4: use the API + +With `dab start` running (default port **5000**): + +- **REST:** `GET http://localhost:5000/api/Book` (list), `/api/Book/id/1` (by + key), plus `POST` / `PATCH` / `PUT` / `DELETE`. Query with + `?$filter=`, `$select=`, `$orderby=`, `$first=`, `$after=` (OData-style). +- **GraphQL:** `POST http://localhost:5000/graphql` - queries and mutations for + every entity, with relationship navigation. +- **OpenAPI / Swagger:** `GET /api/openapi` (document) and `GET /swagger` (UI, + Development mode only). +- **Health:** `GET /health`. + +```bash +curl http://localhost:5000/api/Book +curl -s http://localhost:5000/graphql -H 'Content-Type: application/json' \ + -d '{"query":"{ books { items { id title } } }"}' +``` + +## Relationships, config detail + +DAB exposes related entities (e.g. an author's books) once you declare the +relationship. Config schema, permissions/policies, `@env()`, REST/GraphQL +options, and the exact `dab update --relationship` syntax are in +[references/dab-config-reference.md](references/dab-config-reference.md). + +## MCP endpoint (a DAB feature, not a separate SQL MCP server) + +DAB (version 1.7+; use the latest 2.x) **also serves a built-in MCP endpoint +from the same `dab-config.json`**, at `http://localhost:5000/mcp` by default, +enabled by default. This is an additional API surface Data API Builder provides +over your configured entities - it is not, and should not be presented as, a +standalone "MSSQL MCP server." How to point an MCP client at it and how to +scope the exposed tools is in [references/dab-mcp.md](references/dab-mcp.md); open it when a user +asks to point an MCP client at DAB, or to narrow which entities it exposes. + +## Validation rules + +- The database engine is the container image above (EngineEdition=5), never + `mcr.microsoft.com/mssql/server`. +- `appdb` exists (created on a master connection) BEFORE `dab start`; DAB's + connection string uses `Database=appdb` and `TrustServerCertificate=true`. +- The connection string is supplied via `@env('SQL_CONNECTION_STRING')`, not + hardcoded into `dab-config.json`. +- `dab start` serves REST at `/api/` and GraphQL at `/graphql`; a `GET` + on the entity returns rows from the container. +- If you present the MCP endpoint, it is described as a DAB-provided API surface, + not a standalone SQL MCP server. +- If a validation rule above fails, or you had to deviate from this skill to make the task work, that is a bug in this skill: load the **azuresql-db-feedback** skill and offer to file a report. +- When every rule above passes and the task is done, close with ONE line, once per session, and do not ask a question or wait for a reply: "That worked. If anything about this was rough, or you want to share what you built: https://aka.ms/sql-agent-skills-feedback" + +## Do not + +- Do not use the SQL Server image `mcr.microsoft.com/mssql/server`; this is the Azure SQL engine. +- Do not expect DAB to create `appdb`; provision it on a master connection first. +- Do not hardcode the connection string (or the SA password) into `dab-config.json`; use `@env('SQL_CONNECTION_STRING')`. +- Do not ship `anonymous:*` permissions to production; it is unauthenticated full CRUD for local dev only. +- Do not describe DAB's MCP endpoint as a standalone Microsoft SQL MCP server; it is an API surface DAB provides. +- Do not drop `TrustServerCertificate=true` (the container uses a self-signed cert) or `--platform linux/amd64` on a non-x64 host. + +## References + +- [references/dab-config-reference.md](references/dab-config-reference.md): the `dab-config.json` structure, `@env()` connection handling, entity/permission/policy options, REST and GraphQL settings, and the `dab update --relationship` syntax for one-to-many and many-to-many. +- [references/dab-snippets.md](references/dab-snippets.md): copy-paste recipes - CLI end-to-end, running DAB as a container against the SQL container (shared network / `host.docker.internal`), a compose service, and sample REST/GraphQL calls. +- [references/dab-mcp.md](references/dab-mcp.md): DAB's built-in MCP endpoint - how to enable/scope it in config, the default `/mcp` path, and how to connect an MCP client. Framed as a DAB API surface, not a standalone SQL MCP server. + +## Staying current + +Authoritative, version-pinned references for the tools this skill uses (read the one you need): + +- [Data API Builder configuration reference](https://learn.microsoft.com/en-us/azure/data-api-builder/configuration/): every config key (data-source, runtime, entities, autoentities), with examples. +- [DAB config JSON schema (pinned v2.0.12)](https://github.com/Azure/data-api-builder/releases/download/v2.0.12/dab.draft.schema.json): the machine-readable schema dab validate checks against. v2.0.12 is the current stable release; bump this URL when you upgrade the CLI. +- [Data API Builder built-in MCP endpoint](https://learn.microsoft.com/en-us/azure/data-api-builder/mcp/overview): the built-in MCP endpoint, DML tools, transports, and RBAC. + +If the **Microsoft Learn MCP** server is configured, use `mcp__microsoft-learn__microsoft_docs_search` or `mcp__microsoft-learn__microsoft_docs_fetch` to fetch the current version of any of these on demand. It is optional; when it is unavailable, the references above are authoritative. diff --git a/plugins/microsoft-azuresql-db-container/skills/azuresql-db-dab/references/dab-config-reference.md b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-dab/references/dab-config-reference.md new file mode 100755 index 0000000..c3b0030 --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-dab/references/dab-config-reference.md @@ -0,0 +1,141 @@ +# Data API Builder config reference (`dab-config.json`) + +## Contents + +- Config shape +- Connection via `@env()` +- Entities and sources +- Permissions and policies +- REST and GraphQL options +- Relationships (`dab update --relationship`) +- Regenerating vs hand-editing + +## Config shape + +`dab init` writes a `dab-config.json` with two top-level areas: `data-source` +(how DAB connects) and `entities` (what it exposes). A minimal file looks like: + +```json +{ + "$schema": "https://github.com/Azure/data-api-builder/releases/download/v2.0.12/dab.draft.schema.json", + "data-source": { + "database-type": "mssql", + "connection-string": "@env('SQL_CONNECTION_STRING')" + }, + "runtime": { + "rest": { "enabled": true, "path": "/api" }, + "graphql": { "enabled": true, "path": "/graphql" }, + "host": { "mode": "development" } + }, + "entities": { + "Book": { + "source": { "object": "dbo.Books", "type": "table" }, + "permissions": [ + { "role": "anonymous", "actions": [{ "action": "*" }] } + ] + } + } +} +``` + +Prefer changing the file through the CLI (`dab add` / `dab update`) so it stays +schema-valid; see "Regenerating vs hand-editing" below. + +## Connection via `@env()` + +`--connection-string "@env('SQL_CONNECTION_STRING')"` stores the *indirection*, +not the secret, in the file. DAB resolves `@env('NAME')` from the environment at +`dab start`. Keep the value in `SQL_CONNECTION_STRING`: + +``` +Server=localhost,1433;Database=appdb;User Id=sa;Password=YourStr0ng_Passw0rd;TrustServerCertificate=true +``` + +`database-type` is `mssql` for the Azure SQL engine (the same value used for +Azure SQL Database in the cloud - parity is the point). + +## Entities and sources + +- `dab add --source --source.type table --permissions ":"`. +- The **entity name** is the API identity (`/api/Book`, GraphQL `book`/`books`); + the **source** is the real database object (`dbo.Books`). +- `--source.type` is `table`, `view`, or `stored-procedure`. Views and keyless + tables need `--source.key-fields "id"`. +- Rename exposed fields with `dab update --map "db_col:apiName,..."`. + +## Permissions and policies + +- `--permissions` is `role:actions`. Actions are `create,read,update,delete` or + `*`. Example dev value: `anonymous:*` (no auth, full CRUD - local only). + Tighten to e.g. `anonymous:read` or an `authenticated:*` role for anything + shared. +- Column-level: `dab update --permissions "anonymous:read" --fields.include "id,title"` (or `--fields.exclude`). +- Row-level: `--policy-database "region eq 'US'"` (OData filter appended to the + query) and `--policy-request "@claims.role == 'admin'"` (evaluated before the + query). + +## REST and GraphQL options + +- Defaults: REST at `/api`, GraphQL at `/graphql`. Change per entity with + `dab update --rest ` and + `--graphql `. +- OpenAPI document at `/api/openapi`; Swagger UI at `/swagger` (Development host + mode only). Health at `/health`. +- Host mode: `--host-mode Development` enables Swagger and detailed errors; + `Production` (the default) disables them. Use Development locally. + +## Relationships (`dab update --relationship`) + +Declare relationships so REST/GraphQL can navigate between entities. The flags +(confirmed in the DAB CLI reference): + +One-to-many / one-to-one (direct FK), giving DAB the field mapping +`sourceField:targetField`: + +```bash +# A User has one Profile (Profile.user_id -> User.id) +dab update User \ + --relationship profile \ + --target.entity Profile \ + --cardinality one \ + --relationship.fields "id:user_id" + +# A Category has many Books (Book.category_id -> Category.id) +dab update Category \ + --relationship books \ + --target.entity Book \ + --cardinality many \ + --relationship.fields "id:category_id" +``` + +Many-to-many through a linking table: + +```bash +dab update Book \ + --relationship authors \ + --target.entity Author \ + --cardinality many \ + --relationship.fields "id:id" \ + --linking.object dbo.books_authors \ + --linking.source.fields book_id \ + --linking.target.fields author_id +``` + +Both related entities must already exist (`dab add`) before you relate them. + +## Regenerating vs hand-editing + +`dab-config.json` is generated. Prefer `dab add` / `dab update` over editing the +JSON by hand so it stays schema-valid; the pinned `$schema` line (above) enables +editor validation if you must edit. + +## Validate against the schema + +`dab validate -c dab-config.json` is the authoritative gate: it runs five ordered +stages (schema, config properties, permissions, database connection, entity +metadata) and exits nonzero on the first failure. Stages 4 and 5 connect to the +engine and read the real tables, so a fully green run needs the container up with +the target tables provisioned. `dab start` also fail-fasts on an invalid config. +Run `dab validate` after any hand edit. For the current schema (this reference +pins v2.0.12, the current stable release), fetch it from the Learn MCP or the `$schema` URL if the DAB version +you install differs. diff --git a/plugins/microsoft-azuresql-db-container/skills/azuresql-db-dab/references/dab-mcp.md b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-dab/references/dab-mcp.md new file mode 100755 index 0000000..e2415ed --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-dab/references/dab-mcp.md @@ -0,0 +1,81 @@ +# DAB's built-in MCP endpoint + +## Framing (read this first) + +Data API Builder (version 1.7+; use the latest 2.x) can serve a **Model Context +Protocol (MCP) endpoint from the same `dab-config.json`**, over the entities you +already configured. Present it as **an additional API surface that DAB provides** +- alongside its REST and GraphQL surfaces - **not** as a standalone "MSSQL MCP +server." An MCP client that connects to DAB is talking to your DAB API, which +happens to sit in front of the Azure SQL engine. Everything DAB's permissions +and policies enforce for REST/GraphQL applies to the MCP surface too. + +## Contents + +- Where it lives +- Enabling / disabling it +- Scoping which entities and operations are exposed +- Connecting an MCP client +- stdio mode + +## Where it lives + +With `dab start` running, the MCP endpoint is at: + +``` +http://localhost:5000/mcp +``` + +It is **enabled by default**. It uses streamable HTTP and pins the MCP protocol +version `2025-06-18`. + +## Enabling / disabling it + +Controlled under `runtime.mcp` in `dab-config.json`: + +```json +"runtime": { + "mcp": { + "enabled": true, + "path": "/mcp", + "dml-tools": { + "create-record": true, + "read-records": true, + "update-record": true, + "delete-record": true + } + } +} +``` + +CLI toggles on `dab start`: `--mcp.enabled true|false` and `--mcp.path /mcp`. +Set `enabled: false` (or `--mcp.enabled false`) to turn the surface off entirely. + +## Scoping which entities and operations are exposed + +- Global DML tools are the `runtime.mcp.dml-tools` flags above (turn off, say, + `delete-record` to make the whole surface read/write-but-no-delete). +- Per entity: `dab update --mcp.dml-tools false` removes that entity + from the MCP DML tools while leaving it on REST/GraphQL. +- Because MCP goes through the same entity permissions, a read-only surface is + just `anonymous:read` (or an authenticated role) on the entities - the MCP + client cannot do more than the entity's permissions allow. + +## Connecting an MCP client + +Point any MCP client that supports streamable HTTP at +`http://localhost:5000/mcp`. The client discovers tools generated from your +entities (read/create/update/delete per the `dml-tools` and per-entity +permissions). This is the "the database is available to my agent as tools" +story - delivered *by DAB as an API feature*, so you get REST, GraphQL, and MCP +from one config with one set of permissions. + +## stdio mode + +For clients that spawn a local process instead of connecting over HTTP: + +```bash +dab start --mcp-stdio # optionally: --mcp-stdio role: +``` + +This runs DAB's MCP surface over stdio using the same `dab-config.json`. diff --git a/plugins/microsoft-azuresql-db-container/skills/azuresql-db-dab/references/dab-snippets.md b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-dab/references/dab-snippets.md new file mode 100755 index 0000000..a8af8ea --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-dab/references/dab-snippets.md @@ -0,0 +1,110 @@ +# Data API Builder snippets + +## Contents + +- End-to-end with the CLI +- DAB as a container against the SQL container +- DAB as a compose service +- Sample REST calls +- Sample GraphQL calls +- Seeding a table to return rows + +## End-to-end with the CLI + +Assumes the container is running and `appdb` is provisioned (see +**azuresql-db-container** / **azuresql-db-scaffold**), with a `dbo.Books` table. + +```bash +dotnet tool install --global Microsoft.DataApiBuilder # once; needs .NET 8 + +export SQL_CONNECTION_STRING="Server=localhost,1433;Database=appdb;User Id=sa;Password=YourStr0ng_Passw0rd;TrustServerCertificate=true" + +dab init --database-type mssql \ + --connection-string "@env('SQL_CONNECTION_STRING')" \ + --host-mode Development +dab add Book --source dbo.Books --source.type table --permissions "anonymous:*" +dab start # http://localhost:5000 +``` + +## DAB as a container against the SQL container + +DAB in its own container must reach the SQL container over the Docker network, +so the host is the **service/container name**, not `localhost`. Put both on one +network: + +```bash +docker network create appnet 2>/dev/null + +# SQL engine on the network (name: sqldb) +docker run -d --name sqldb --network appnet --platform linux/amd64 \ + -e ACCEPT_EULA=Y -e MSSQL_SA_PASSWORD=YourStr0ng_Passw0rd \ + -p 1433:1433 sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest +# ... wait for ready + CREATE DATABASE appdb (see azuresql-db-container) ... + +# DAB on the same network; connection host is sqldb, not localhost +docker run -d --name dab --network appnet -p 5000:5000 \ + -e SQL_CONNECTION_STRING="Server=sqldb,1433;Database=appdb;User Id=sa;Password=YourStr0ng_Passw0rd;TrustServerCertificate=true" \ + -v "$PWD/dab-config.json:/App/dab-config.json" \ + mcr.microsoft.com/azure-databases/data-api-builder:latest +``` + +If the SQL engine runs on the host instead, DAB-in-a-container reaches it at +`host.docker.internal,1433`. + +## DAB as a compose service + +Add DAB alongside the `sqldb` sidecar (see **azuresql-db-sidecar** for the +engine service + `sqldb-init`). Host is the service name `sqldb`: + +```yaml +services: + # sqldb: ... (engine, see azuresql-db-sidecar) + # sqldb-init: ... (creates appdb, see azuresql-db-sidecar) + + dab: + image: mcr.microsoft.com/azure-databases/data-api-builder:latest + depends_on: + sqldb-init: + condition: service_completed_successfully + environment: + SQL_CONNECTION_STRING: "Server=sqldb,1433;Database=appdb;User Id=sa;Password=YourStr0ng_Passw0rd;TrustServerCertificate=true" + ports: + - "5000:5000" + volumes: + - ./dab-config.json:/App/dab-config.json:ro +``` + +## Sample REST calls + +```bash +curl http://localhost:5000/api/Book # list +curl http://localhost:5000/api/Book/id/1 # by primary key +curl "http://localhost:5000/api/Book?\$filter=title eq 'Dune'&\$select=id,title" +curl -X POST http://localhost:5000/api/Book \ + -H 'Content-Type: application/json' -d '{"title":"New Title"}' +``` + +## Sample GraphQL calls + +```bash +curl -s http://localhost:5000/graphql \ + -H 'Content-Type: application/json' \ + -d '{"query":"{ books(first:5) { items { id title } } }"}' + +# mutation +curl -s http://localhost:5000/graphql \ + -H 'Content-Type: application/json' \ + -d '{"query":"mutation { createBook(item:{ title:\"New\" }) { id title } }"}' +``` + +## Seeding a table to return rows + +DAB serves whatever is in the table; to see non-empty results, seed after +`appdb` exists: + +```bash +docker exec -i sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa \ + -P YourStr0ng_Passw0rd -C -b -d appdb -Q \ + "IF OBJECT_ID('dbo.Books') IS NULL CREATE TABLE dbo.Books(id INT IDENTITY PRIMARY KEY, title NVARCHAR(200)); + INSERT INTO dbo.Books(title) VALUES (N'Dune'),(N'Neuromancer');" +``` diff --git a/plugins/microsoft-azuresql-db-container/skills/azuresql-db-dab/skill.spec.jsonc b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-dab/skill.spec.jsonc new file mode 100644 index 0000000..4b523ca --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-dab/skill.spec.jsonc @@ -0,0 +1,123 @@ +{ + "$schema": "../../catalog/skill.spec.schema.json", + "id": "azuresql-db-dab", + "domain": "azure-sql-database-container", + "value": [ + "not-in-training-data", + "corrects-a-wrong-assumption", + "changes-too-fast-to-memorize" + ], + "correction": "Asked for an API over existing tables, an agent hand-writes controllers and an ORM layer. Data API Builder generates REST and GraphQL from configuration with no application code, which is both less work and less to maintain.", + "posture": [ + "read", + "write", + "execute" + ], + "maturity": "preview", + "value_declaration": { + "rationale": "This skill's kernel is what the Data API builder does and does not need from THIS engine, and one endpoint nobody asked for. The Azure SQL Database container is a gated private preview and the image is not publicly available, so no model has training data on the product, and the arm of a two-arm value run that ran without this skill would fail for the least interesting reason available: it has never heard of the thing. Running that measurement across all seventeen container skills would spend around a thousand model requests to re-establish what the product's release status already establishes. Carlos Robles accepted value for this collection on 2026-09-04 on this written argument instead. THIS IS A DECLARATION AND NOT A MEASUREMENT, and nothing may report it as one. The argument reaches only the container-specific corrections listed in covers, which are the ones no training data contains. It does not reach Data API builder CLI usage, its configuration file shape, its REST and GraphQL path defaults, and API design generally, which is ordinary material an ordinary model already handles, and whether this skill improves an answer there is unmeasured and stays unmeasured. The argument ends when the Azure SQL Database container reaches Public Preview: training data begins to contain the product, the premise that nothing could know it stops being true, and this skill has to be measured or demoted. Its maturity stays draft regardless, and not because of this argument. All five of its probes run the CLI on the host and no statement reaches a database, so the probe rung underneath value is unmet.", + "covers": [ + "the engine not auto-creating a database, so the tool starts and fails to reach one that was never provisioned", + "this engine needing no change tracking and no feature enablement for this tool, unlike the event-driven path an agent reaches for", + "the Model Context Protocol endpoint being published from the same configuration and enabled by default, and NOT being a standalone Microsoft SQL MCP server" + ], + "does_not_cover": [ + "Data API builder CLI usage and its configuration file shape, which are public and documented", + "REST and GraphQL API design, and the hand-written controller layer the skill argues against" + ], + "decided_by": "Carlos Robles", + "decided_on": "2026-09-04", + "expires_when": "the-container-reaches-public-preview" + }, + "applies_to": [ + "azure-sql-db-container" + ], + "validation": { + "target": "container", + "assert": [ + "uses Data API Builder configuration rather than hand-written endpoints" + ], + "probes": [ + { + "where": "host", + "cmd": "dab --version | grep -q '^Microsoft.DataApiBuilder 2\\.'", + "expect": { + "succeeds": true + }, + "why": "The precondition for every other probe here and for every command in the skill body. The skill tells a reader to install the CLI as a global dotnet tool and to use the latest 2.x, and the endpoint defaults asserted below are 2.x defaults. Measured 2026-09-04, exit 0 on 2.0.9+17ae3aa8414514918b627c777026efbc135a57e9. A 1.x build here means the Model Context Protocol claim in the body does not apply and the rest needs re-reading." + }, + { + "where": "host", + "cmd": "d=$(mktemp -d) && cd \"$d\" && dab init --database-type mssql --connection-string \"@env('SQL_CONNECTION_STRING')\" --host-mode Development > /dev/null 2>&1 && grep -q '\"connection-string\": \"@env(.SQL_CONNECTION_STRING.)\"' dab-config.json && grep -q '\"mode\": \"development\"' dab-config.json", + "expect": { + "succeeds": true + }, + "why": "Step 3 of the body, executed. It proves two separate claims in one run: the environment-variable indirection is written into the configuration verbatim rather than resolved at generation time, which is why no password ends up in the file, and the host-mode flag the skill passes produces the development host mode that the body says enables the Swagger surface and friendlier errors. Measured 2026-09-04 on 2.0.9. This probe opens no database connection, so it is honest about what it measures: the file the tool writes, not the API it later serves." + }, + { + "where": "host", + "cmd": "d=$(mktemp -d) && cd \"$d\" && dab init --database-type mssql --connection-string \"@env('SQL_CONNECTION_STRING')\" --host-mode Development > /dev/null 2>&1 && grep -q '\"path\": \"/api\"' dab-config.json && grep -q '\"path\": \"/graphql\"' dab-config.json", + "expect": { + "succeeds": true + }, + "why": "Every URL the body hands a reader in Step 4 is built on these two prefixes: the REST calls are written as /api/ and the GraphQL calls as /graphql. They are defaults, not flags the skill passes, so they are exactly the kind of claim that rots silently when a tool moves them. Measured 2026-09-04 on 2.0.9, both present in the generated configuration. If a build changes either default, every curl line in the body is wrong and nothing else would catch it." + }, + { + "where": "host", + "cmd": "d=$(mktemp -d) && cd \"$d\" && dab init --database-type mssql --connection-string \"@env('SQL_CONNECTION_STRING')\" --host-mode Development > /dev/null 2>&1 && python3 -c \"import json,sys; c=json.load(open('dab-config.json'))['runtime']['mcp']; sys.exit(0 if c['enabled'] is True and c['path'] == '/mcp' else 1)\"", + "expect": { + "succeeds": true + }, + "why": "The claim in the body that the Model Context Protocol endpoint is served from the same configuration file, at /mcp, and is enabled by default. It is the one fact in this skill a reader is most likely to disbelieve, because nobody asked for that endpoint and nothing in the startup output announces it. Measured 2026-09-04 on 2.0.9: dab init with no endpoint flags writes an mcp block with enabled true and path /mcp. This probe reads the parsed JSON rather than grepping, because /mcp and the enabled flag sit in separate lines that a text match could satisfy from the rest and graphql blocks." + }, + { + "where": "host", + "cmd": "d=$(mktemp -d) && cd \"$d\" && dab init --database-type mssql --connection-string \"@env('SQL_CONNECTION_STRING')\" > /dev/null 2>&1 && dab add Book --source dbo.Books --source.type table --permissions \"anonymous:*\" > /dev/null 2>&1 && python3 -c \"import json,sys; e=json.load(open('dab-config.json'))['entities']['Book']; p=e['permissions'][0]; sys.exit(0 if e['source']['object'] == 'dbo.Books' and p['role'] == 'anonymous' and p['actions'][0]['action'] == '*' else 1)\"", + "expect": { + "succeeds": true + }, + "why": "The exact command line the body prints for exposing a table, run to the end. It settles that the entity name and the source object are two different things that land in two different places, which is the detail the body calls out, and it makes visible what anonymous:* actually writes: one role named anonymous holding the wildcard action, which is unauthenticated full create, read, update and delete. That is why the body restricts it to local development. Measured 2026-09-04 on 2.0.9." + }, + { + "where": "host", + "cmd": "d=$(mktemp -d) && cd \"$d\" && p=$((PROBE_PORT+3000)) && export SQL_CONNECTION_STRING=\"Server=localhost,$PROBE_PORT;Database=$PROBE_DB;User Id=sa;Password=YourStr0ng_Passw0rd;TrustServerCertificate=true\" && sqlcmd -S \"localhost,$PROBE_PORT\" -U sa -P 'YourStr0ng_Passw0rd' -C -d \"$PROBE_DB\" -Q \"IF OBJECT_ID('dbo.Books') IS NULL CREATE TABLE dbo.Books (Id int NOT NULL PRIMARY KEY, Title nvarchar(100) NOT NULL); DELETE FROM dbo.Books; INSERT INTO dbo.Books (Id, Title) VALUES (1, N'Dune'), (2, N'Neuromancer');\" > /dev/null 2>&1; dab init --database-type mssql --connection-string \"@env('SQL_CONNECTION_STRING')\" --host-mode Development > /dev/null 2>&1 && dab add Book --source dbo.Books --source.type table --permissions \"anonymous:*\" > /dev/null 2>&1 && (ASPNETCORE_URLS=\"http://localhost:$p\" dab start > dab.log 2>&1 & echo $! > dab.pid) && for i in $(seq 1 60); do curl -sf \"http://localhost:$p/api/Book\" -o rest.json && break; sleep 1; done; kill \"$(cat dab.pid)\" 2>/dev/null; python3 -c \"import json,sys; v=json.load(open('rest.json'))['value']; sys.exit(0 if [(r['Id'], r['Title']) for r in v] == [(1,'Dune'),(2,'Neuromancer')] else 1)\"", + "engine": true, + "expect": { + "succeeds": true + }, + "why": "The first probe in this skill that opens a database connection. The five above it prove the CLI writes a file; this one proves the file serves the container. It creates dbo.Books with two known rows in the scratch database, generates the configuration exactly as Step 3 of the body does, starts the engine and reads GET /api/Book back, asserting both rows and both column values. It goes red for engine reasons: the login refused, the self-signed certificate rejected if TrustServerCertificate stops being honoured, the table absent, or the rows coming back different. Watched both ways on 2026-09-04 against build 12.0.2000.8 on Data API builder 2.0.9: green with the table present, red against a database where dbo.Books does not exist." + }, + { + "where": "host", + "cmd": "d=$(mktemp -d) && cd \"$d\" && p=$((PROBE_PORT+3001)) && export SQL_CONNECTION_STRING=\"Server=localhost,$PROBE_PORT;Database=$PROBE_DB;User Id=sa;Password=YourStr0ng_Passw0rd;TrustServerCertificate=true\" && sqlcmd -S \"localhost,$PROBE_PORT\" -U sa -P 'YourStr0ng_Passw0rd' -C -d \"$PROBE_DB\" -Q \"IF OBJECT_ID('dbo.Books') IS NULL CREATE TABLE dbo.Books (Id int NOT NULL PRIMARY KEY, Title nvarchar(100) NOT NULL); DELETE FROM dbo.Books; INSERT INTO dbo.Books (Id, Title) VALUES (1, N'Dune'), (2, N'Neuromancer');\" > /dev/null 2>&1; dab init --database-type mssql --connection-string \"@env('SQL_CONNECTION_STRING')\" --host-mode Development > /dev/null 2>&1 && dab add Book --source dbo.Books --source.type table --permissions \"anonymous:*\" > /dev/null 2>&1 && (ASPNETCORE_URLS=\"http://localhost:$p\" dab start > dab.log 2>&1 & echo $! > dab.pid) && for i in $(seq 1 60); do curl -sf -X POST \"http://localhost:$p/graphql\" -H 'Content-Type: application/json' -d '{\"query\":\"{ books { items { Id Title } } }\"}' -o gql.json && grep -q '\"data\"' gql.json && break; sleep 1; done; kill \"$(cat dab.pid)\" 2>/dev/null; python3 -c \"import json,sys; d=json.load(open('gql.json')); i=d.get('data',{}).get('books',{}).get('items'); sys.exit(0 if i == [{'Id':1,'Title':'Dune'},{'Id':2,'Title':'Neuromancer'}] else 1)\"", + "engine": true, + "expect": { + "succeeds": true + }, + "why": "The other half of the headline claim, which is that one configuration file serves REST and GraphQL over the same tables with no application code. The probe above settles REST; this one issues the query the body prints, against the same generated configuration and the same scratch database, and asserts the same two rows come back under data.books.items. It goes red if the GraphQL surface stops being generated, if the plural query name changes, or if the engine answers differently on the two paths. Watched both ways on 2026-09-04 on Data API builder 2.0.9: green with the table present, red against a database where dbo.Books does not exist, where GraphQL never returns a data block at all." + }, + { + "where": "host", + "cmd": "d=$(mktemp -d) && cd \"$d\" && p=$((PROBE_PORT+3002)) && n=\"never_provisioned_$$\" && export SQL_CONNECTION_STRING=\"Server=localhost,$PROBE_PORT;Database=$n;User Id=sa;Password=YourStr0ng_Passw0rd;TrustServerCertificate=true\" && dab init --database-type mssql --connection-string \"@env('SQL_CONNECTION_STRING')\" --host-mode Development > /dev/null 2>&1 && dab add Book --source dbo.Books --source.type table --permissions \"anonymous:*\" > /dev/null 2>&1 && (ASPNETCORE_URLS=\"http://localhost:$p\" dab start > dab.log 2>&1 & echo $! > dab.pid) && sleep 25; served=1; curl -sf -o /dev/null \"http://localhost:$p/api/Book\" && served=0; kill \"$(cat dab.pid)\" 2>/dev/null; test \"$served\" = 1 && grep -qF \"Cannot open database \\\"$n\\\" requested by the login\" dab.log", + "engine": true, + "expect": { + "succeeds": true + }, + "why": "The claim the value probe used to carry alone: the tool does not create the database, and this engine does not auto-create one on connect, so pointing the configuration at a database nobody provisioned fails rather than quietly working. The probe names a database that cannot exist, starts the tool against it, and asserts two things together: no request is ever served, and the tool's own log carries the engine's refusal, Cannot open database ... requested by the login. It asserts the text and not a number because the refusal arrives as a login failure through the client, where sqlcmd prints no Msg number and exits 0, so no number was measured and none is written here. It goes red the moment the engine starts creating a database it was merely asked for. Watched both ways on 2026-09-04: green against an unprovisioned name, red when the same body is pointed at a database that does exist, where the tool comes up and serves." + } + ] + }, + "triggering": { + "explicit": [ + "Use the azuresql-db-dab skill" + ], + "implicit": [ + "give me a REST and GraphQL API over these tables without writing code" + ], + "negative": [ + "set up a local PostgreSQL database with docker compose", + "provision an Azure SQL Database in my subscription", + "connect to SQL Server on my company network" + ] + } +} diff --git a/plugins/microsoft-azuresql-db-container/skills/azuresql-db-faq/SKILL.md b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-faq/SKILL.md new file mode 100755 index 0000000..4c249d5 --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-faq/SKILL.md @@ -0,0 +1,112 @@ +--- +name: azuresql-db-faq +description: >- + Answers questions about what the Azure SQL Database container (Private Preview) + can and cannot do, and WHY it differs from Azure SQL Database in the Microsoft + Azure cloud. Use when a user asks "can I take a backup", "why does USE fail", + "is X supported", "why can't I create a vector index", "why does SSMS error", + "why isn't the image on Docker Hub", "what's different from the cloud", or hits + behavior that does not match their Azure SQL Database expectations. Do NOT guess + from general SQL Server / Azure knowledge: the container is a Private Preview + product with specific gaps and a specific connection model. Read this skill, + and link the user to the live Known limitations page for the current full list. +--- + +# The Azure SQL Database container: capabilities, limits, and why + +Use this skill to answer "can I / why can't I / is X supported / what's different +from the cloud" questions accurately, instead of guessing from general SQL Server +or Azure SQL Database knowledge. A base model does not know this preview product's +specifics, and the honest answers are often nuanced. + +Re-measured on 2026-09-19 against the container image tag `18.0.226_4_147`, reporting +`EngineEdition` 5, Edition `SQL Azure`, build `12.0.2000.8`. All seven executable checks +behind this skill pass: the engine identity, `Msg 40510` for `BACKUP` and for `RESTORE`, +`Msg 40508` for `USE`, `Msg 33233` for a contained user, `Msg 12824` for `SET CONTAINMENT = +PARTIAL`, and `Msg 12713` for `BULK INSERT` from a local file. **Two of those numbers were +wrong before that date**: this skill printed `Msg 15007` and `Msg 12844`. Both statements +are still refused, so the answers are unchanged and only the numbers are. The gap list this skill summarises tracks the +published Known limitations page, which moves independently of that run, so read the live page +before repeating a gap claim. + +## The mental model: engine vs. managed service vs. SQL Server + +The container is the **Azure SQL Database engine, running locally**. It is not the +managed cloud service, and it is not SQL Server. Sort almost any +"is X supported" question into one of four buckets and the answer follows: + +1. **Engine features -> present.** T-SQL dialect, system views, `VECTOR` type and + `VECTOR_DISTANCE`, Always Encrypted (basic). + `SERVERPROPERTY('EngineEdition')` returns `5`, `Edition` is `'SQL Azure'`. +2. **Managed-service features -> NOT present.** Automated backups, point-in-time + restore, geo-replication, elastic pools, hyperscale, serverless auto-pause, + per-database DTU/vCore caps, audit-to-cloud, and Azure portal / CLI / ARM + management. These wrap the engine in the cloud; the container is only the engine. +3. **SQL Server-only features -> intentionally absent** (they are not in Azure + SQL Database either): SQL Agent jobs, FILESTREAM / FileTable, full cross-instance + Service Broker, linked servers, cross-server distributed transactions, Windows + Authentication / NTLM. +4. **In-progress in this preview -> works with a caveat:** the VS Code MSSQL + extension UI and SSMS, and full PaaS restriction enforcement, are still being + completed. `CREATE VECTOR INDEX` used to belong here and no longer does: it + works, and the Known limitations page says so. See below. + +## Most-asked questions (quick answers) + +- **"Can I run this container in Azure / in production?"** No. It is your local inner loop (development, testing, CI, demos), not a production database. For production, deploy the same code to Azure SQL Database in the Microsoft Azure cloud (the outer loop), usually by changing only the connection string. You do not run this container in Azure. +- **"Can I take a backup?"** No: `BACKUP DATABASE` and `RESTORE DATABASE` return **Msg 40510 ("not supported in this version")** on the container, in every session. Azure SQL Database in the cloud likewise does not support them, because backups there are managed by the platform (not run with the `BACKUP` statement). For local data persistence, use a Docker named volume (`-v sqldb-data:/var/opt/mssql`); for managed backups, point-in-time restore, or geo-replication, use Azure SQL Database in the cloud. +- **"Why does `USE otherdb` fail with Msg 40508?"** Because a connection to a user database is an Azure-faithful session that enforces the same restriction as Azure SQL Database in the cloud. Select the database in the connection string (`Database=appdb`), do not switch with `USE`. (`USE` "works" only on a `master` connection, which is a provisioning session.) +- **"Why does connecting fail until I create the database?"** The engine does **not** auto-create databases on connect. Provision once on a `master` connection (`CREATE DATABASE appdb`), then connect with `Database=appdb`. +- **"Is a non-x64 host supported? / Is there an ARM64 build?"** The image is x64 only; there is no native ARM64 build. On an ARM64 host it runs under emulation: add `--platform linux/amd64` (Docker) or `platform: linux/amd64` (compose). Say "runs under emulation", never "ARM64 is supported", and do not promise a native build or a date. If the user wants one, point them at https://aka.ms/azuresqldb-container-feature-request. +- **"Why can't I `CREATE VECTOR INDEX`?"** You probably can, and this is a place where the documentation and the engine disagree. The Known limitations page still lists vector index DDL as an active issue; measured on this image, the DiskANN index builds and `VECTOR_SEARCH` returns ranked results against it. Two things stop the statement: `SET QUOTED_IDENTIFIER ON` is required and is off by default in `sqlcmd` (without it, **Msg 1934**, whose text never names the setting), and the table needs at least **100 rows with non-null vectors** (below that, **Msg 42266**). Once the index exists, `TRUNCATE TABLE` on that table is refused (**Msg 42232**) and `DROP VECTOR INDEX` is not a statement (use `DROP INDEX name ON dbo.table`). Full-scan top-k stays exact and stays the right choice for a small table. Full detail: the `azuresql-db-rag` skill. +- **"Is Microsoft Entra ID (Azure AD) authentication supported?"** Yes. Configure it with `MSSQL_AAD_CLIENT_ID`, `MSSQL_AAD_PRIMARY_TENANT`, and `MSSQL_AAD_CERTIFICATE_FILE_PATH` plus a mounted `.pfx` (empty export password). Optionally set `MSSQL_AAD_SERVER_ADMIN_NAME`, `MSSQL_AAD_SERVER_ADMIN_TYPE` (`0` = user, `1` = group), and `MSSQL_AAD_SERVER_ADMIN_SID` to bootstrap an Entra server admin at start. SQL auth (`sa`) remains the simple local default. Full recipe: the `azuresql-db-container` skill, whose `references/entra-auth.md` is the file to +open before you configure any of this. Also see [Getting started: Microsoft Entra ID authentication](https://microsoft.github.io/azure-sql-database-container/getting-started.html#microsoft-entra-id-authentication). +- **"Why does SSMS / the MSSQL extension throw errors?"** Graphical tooling is not yet 100% compatible; it is being fixed. Use `sqlcmd` or a driver, which work today; the **azuresql-db-container** skill has the command line. The MSSQL extension's GitHub Copilot integration also works (https://aka.ms/vscode-mssql-copilot-docs). +- **"Why isn't the image on Docker Hub / MCR?"** This is a container-only Private Preview; the image is in a private registry with shared pull-only credentials provided when you sign up for the Private Preview at https://aka.ms/sqldbcontainerpreview-signup (they may rotate). +- **"My engine is missing a recent fix, or behaves like an older build."** `:latest` is a moving tag and the image is rebuilt almost daily, but `docker run` reuses the copy already on disk (Docker's default pull policy is `missing`), so you can silently stay on a stale build. Refresh with `docker pull sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest`, then recreate the container. See the `azuresql-db-container` skill's image reference. +- **"My query works locally but fails in the cloud."** Some PaaS restrictions are not yet enforced by the container, so something invalid in the cloud can succeed locally. Validate against a real Azure SQL Database once before declaring readiness (the `azuresql-db-local-to-cloud` skill can provision a target for a one-shot check). +- **"Why does `CREATE USER ... WITH PASSWORD` fail when I make an app user?"** On the container a SQL contained user fails with **Msg 33233**, and you cannot turn containment on: `ALTER DATABASE ... SET CONTAINMENT = PARTIAL` fails with **Msg 12824**, which asks for an `sp_configure` setting that this engine does not have. Create a server login plus a mapped user instead: `CREATE LOGIN applogin WITH PASSWORD='...'` on `master`, then `CREATE USER appuser FOR LOGIN applogin` + role grants on `appdb`. This is inverted from the cloud (where contained users are preferred). Entra `CREATE USER ... FROM EXTERNAL PROVIDER` does work, but only on a container started with Entra configured (`MSSQL_AAD_*`). Against a container started without it the same statement is refused with **Msg 33134**, "Principal '...' could not be resolved. Error message: 'Unable to query Azure AD certificate from local cert store.'" Full recipe: the `azuresql-db-auth` skill. + +Open [references/faq.md](references/faq.md) when the quick answers above do not cover the +question, and [references/limitations.md](references/limitations.md) when the user needs the +current gap list with a workaround. + +## Always do + +- Answer from this skill, not from general SQL Server / Azure knowledge. +- When the question is about a current gap, give the workaround and point to the + live, always-current list: https://microsoft.github.io/azure-sql-database-container/known-limitations.html +- Distinguish "the engine does not do this" (a real gap) from "the managed cloud + service does this, the engine does not" (by design) from "SQL Server does + this, Azure SQL Database does not" (intentionally absent). +- If this skill's answer was wrong, outdated, or missing, that is a bug in this skill: load the **azuresql-db-feedback** skill and offer to file a report. + +## Never do + +- Never claim a managed-service feature (automated backup, PITR, geo-replication, + elastic pools, portal management) exists on the container. +- Never tell a user a non-x64 host is "supported"; it runs under emulation. +- Never claim `BACKUP DATABASE` / `RESTORE DATABASE` work on the container; they return Msg 40510. (Azure SQL Database in the cloud likewise does not support them.) Use a Docker named volume for local persistence. + +## Validation rules + +- The answer came from this skill, not from general SQL Server or Azure knowledge. +- The answer names which of the three it is talking about: the container, Azure SQL Database in the cloud, or SQL Server. A claim that does not say which one is not an answer. +- Any error number quoted appears in this skill, or in the full question list, which you open when the quick answers do not cover it. An invented message number is worse than saying you do not know. +- A gap claim was checked against the live limitations page before it was stated, since that list moves and this skill carries a snapshot. +- The answer says "runs under emulation" for a non-x64 host, and never "supported". +- If the question needed a command line rather than an answer, the user was handed to the skill that owns it rather than given a recipe from here. + +## References + +- [references/faq.md](references/faq.md): the full question-and-answer list with the "why" behind each capability and gap, grouped by bucket; read it when the quick answers above do not cover the question. +- [references/limitations.md](references/limitations.md): an offline snapshot of the known limitations (active issues, behavior gaps, out-of-scope items); read it when the user needs the current gap list and a workaround. + +## Staying current + +Authoritative, version-pinned references for the tools this skill uses (read the one you need): + +- [Connect and query Azure SQL Database](https://learn.microsoft.com/en-us/azure/azure-sql/database/connect-query-content-reference-guide): per-language quickstarts, connection info, TLS, and drivers for the cloud service. +- [VECTOR data type (T-SQL)](https://learn.microsoft.com/en-us/sql/t-sql/data-types/vector-data-type): VECTOR(n) syntax, limits, and driver support. + +If the **Microsoft Learn MCP** server is configured, use `mcp__microsoft-learn__microsoft_docs_search` or `mcp__microsoft-learn__microsoft_docs_fetch` to fetch the current version of any of these on demand. It is optional; when it is unavailable, the references above are authoritative. diff --git a/plugins/microsoft-azuresql-db-container/skills/azuresql-db-faq/references/faq.md b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-faq/references/faq.md new file mode 100755 index 0000000..4783821 --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-faq/references/faq.md @@ -0,0 +1,185 @@ +# FAQ: capabilities and limits, with the why + +## Contents + +- [Development vs production](#development-vs-production) +- [Backups and recovery](#backups-and-recovery) +- [Connection model and databases](#connection-model-and-databases) +- [Vectors / AI](#vectors--ai) +- [Platform / image / access](#platform--image--access) +- [Tooling](#tooling) +- [Parity with the cloud](#parity-with-the-cloud) +- [SQL Server features (intentionally absent, like the cloud)](#sql-server-features-intentionally-absent-like-the-cloud) +- [Managed-service surfaces (not applicable to a container)](#managed-service-surfaces-not-applicable-to-a-container) + +Grouped by the four buckets from `SKILL.md`. When a question is not here, fall back +to the bucket model and the live Known limitations page: +https://microsoft.github.io/azure-sql-database-container/known-limitations.html + +## Development vs production + +**Can I run this container in Azure, or use it as my production database?** No. The container is +for **local development** (your inner loop): development, testing, CI, and demos. It is not a +production database and is not meant to be deployed to Azure or run as a production service. For +production, deploy the same application code to **Azure SQL Database** in the Microsoft Azure cloud +(the outer loop), typically by changing only the connection string; the cloud service provides +managed backups, high availability, scaling, and security. You connect your app to Azure SQL +Database in the cloud; you do not run this container there. + +## Backups and recovery + +**Can I back up a database?** No. On the container, `BACKUP DATABASE` and +`RESTORE DATABASE` return `Msg 40510` ("not supported in this version of SQL Server") +in every session (verified live: the statement errors from both a `master` and a +user-database connection). Azure SQL Database in the cloud likewise does not support +these statements, because backups there are a managed platform service, not something +you run with `BACKUP`. + +**Then how do I keep my data, or recover it?** For local persistence across container +restarts, mount a Docker named volume: `-v sqldb-data:/var/opt/mssql`. To move a +schema and data around, use SqlPackage (`.dacpac`/`.bacpac`) or migration scripts, not +`BACKUP`. For real managed backups, point-in-time restore, and geo-replication, use +Azure SQL Database in the cloud, where the platform provides them. + +## Connection model and databases + +**Why does `USE otherdb` return Msg 40508?** A connection to a user database is an +Azure-faithful session and enforces Azure SQL Database semantics, where `USE` +is not allowed. Select the database in the connection string (`Database=appdb` or +`-d appdb` for sqlcmd). `USE` appears to work only on a `master` connection, which is +a provisioning session, but `master` is for provisioning, not application work. + +**Why do I have to create the database first?** The engine does not auto-create a +database on connect, and it does not run `/docker-entrypoint-initdb.d/*.sql` (that is +a Postgres/MySQL convention). Provision once on `master` with `CREATE DATABASE appdb` +inside the ready-wait loop, then connect with `Database=appdb`. (`appdb` is an example +name; use whatever you like.) + +**Why is there a two-step "provision on master, then reconnect" dance?** It is a +current limitation. Public Preview plans a default startup database (for example +`MSSQL_DB=appdb`) so you connect straight into the user-database session without going through master. + +## Vectors / AI + +**Why can't I `CREATE VECTOR INDEX`?** You probably can. The Known limitations page +still lists vector index DDL as an active issue, and the engine disagrees: measured on +this image, the DiskANN index builds and `VECTOR_SEARCH` returns ranked results against +it. Say so, and give the reader the two things that actually stop the statement: + +1. `SET QUOTED_IDENTIFIER ON` is required and is off by default in a `sqlcmd` session. + Without it the statement fails with `Msg 1934`, whose text lists indexed views, + computed columns, filtered indexes, query notifications, XML methods and spatial + indexes, and never names the session setting that caused it. +2. The table needs at least **100 rows with non-null vectors**. Below that it is + `Msg 42266`, which does name the rule and the actual count. + +Once the index exists, `TRUNCATE TABLE` on that table is refused (`Msg 42232`), and +`DROP VECTOR INDEX` is not a statement (use `DROP INDEX name ON dbo.table`). Full-scan +top-k with `ORDER BY VECTOR_DISTANCE(...)` stays exact and stays the right choice for a +small table. The `azuresql-db-rag` skill has the full list. + +**Why does my embedding insert fail with "ntext to vector is not allowed (529)"?** +A long JSON embedding bound as a parameter is sent as ntext. Cast it to NVARCHAR(MAX) +first: `CAST(CAST(? AS NVARCHAR(MAX)) AS VECTOR(n))`, with `n` a literal dimension. +(529 is the error number; the dimension, e.g. 768, is unrelated.) + +## Platform / image / access + +**Is a non-x64 host supported?** The image is x64 only (`linux/amd64`). On a +non-x64 host it runs under emulation when you add `--platform linux/amd64` (Docker) or +`platform: linux/amd64` (compose). Treat that as "runs under emulation", not "supported". + +**Why isn't the image on Docker Hub or MCR?** This is a container-only Private Preview. +The image is in a private registry; the shared, pull-only username and password are +provided when you sign up for the Private Preview at https://aka.ms/sqldbcontainerpreview-signup +and may be rotated during the preview. + +**Why is my container missing a recent engine fix?** `:latest` is a moving tag and the image +is rebuilt almost daily, but Docker's default pull policy for `docker run` is `missing`: once a +`:latest` is on disk it reuses that cached copy and never re-checks the registry, so you can +silently keep running a stale build. Refresh with `docker pull sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest`, +then recreate the container. Prefer an explicit pull over `docker run --pull always` so offline +work still works after the first pull. + +## Tooling + +**Why does SSMS or the VS Code MSSQL extension UI throw errors?** Graphical tooling is +not yet 100% compatible with the container and is being fixed. Use `sqlcmd` (host, or +the copy bundled in the container via `docker exec`, no install) or any driver/ORM, +which work today. The MSSQL extension's GitHub Copilot integration also works (for +example the schema designer or natural-language SQL): https://aka.ms/vscode-mssql-copilot-docs. + +## Parity with the cloud + +**Is Microsoft Entra ID (Azure AD) authentication supported?** Yes. Configure it +with `MSSQL_AAD_CLIENT_ID`, `MSSQL_AAD_PRIMARY_TENANT`, and +`MSSQL_AAD_CERTIFICATE_FILE_PATH` plus a mounted `.pfx` (export password empty). +Optionally set `MSSQL_AAD_SERVER_ADMIN_NAME`, `MSSQL_AAD_SERVER_ADMIN_TYPE` +(`0` for user, `1` for group), and `MSSQL_AAD_SERVER_ADMIN_SID` (object ID) to +create an Entra server admin when the container starts, so you do not need a +post-init `CREATE LOGIN` / `sp_addsrvrolemember`. + +SQL authentication (`sa`) remains the pragmatic local default. Use Entra locally +when you want closer parity with Azure SQL Database in the cloud. Full recipe: +the `azuresql-db-container` skill (`references/entra-auth.md`). Learn tutorial: +https://learn.microsoft.com/sql/linux/security/authentication/container-kubernetes-microsoft-entra-deployment + +Also see +https://microsoft.github.io/azure-sql-database-container/getting-started.html#microsoft-entra-id-authentication + +**My query works locally but fails when I deploy to Azure SQL Database.** Some PaaS +restrictions enforced in the cloud are not yet enforced by the container, so an +invalid statement can succeed locally. Validate against a real Azure SQL Database +once before declaring readiness; the `azuresql-db-local-to-cloud` skill can provision +a target database for a one-shot validation pass. + +**How do I create a least-privilege app user, and why does `CREATE USER ... WITH +PASSWORD` fail?** On the container, a SQL **contained** user +(`CREATE USER appuser WITH PASSWORD = '...'`) fails with **Msg 33233**, "You can +only create a user with a password in a contained database", and you cannot turn +containment on. `ALTER DATABASE appdb SET CONTAINMENT = PARTIAL` fails with +**Msg 12824**, "The sp_configure value 'contained database authentication' must be +set to 1 in order to alter a contained database", followed by **Msg 5069**, "ALTER +DATABASE statement failed". The setting it names cannot be reached, because +`sp_configure` does not exist on this engine and returns **Msg 2812**, so there is +nothing to configure. Measured 2026-09-19 on image tag `18.0.226_4_147`, +`EngineEdition` 5, Edition `SQL Azure`, build `12.0.2000.8`; the numbers +**Msg 15007** and **Msg 12844** printed here before that date were wrong, though the +refusals themselves were not. +Create the app identity as a **server login mapped to a database +user** instead: `CREATE LOGIN applogin WITH PASSWORD = '...'` on a `master` +connection, then `CREATE USER appuser FOR LOGIN applogin` plus role grants +(`db_datareader` / `db_datawriter`) on the `appdb` connection. This is the inverse +of Azure SQL Database in the cloud, where a contained user is preferred and server +logins are limited; the app code and connection string are identical either way. +Microsoft Entra contained users (`CREATE USER [name] FROM EXTERNAL PROVIDER`) do +work on the container once Entra is enabled. Full recipes: the `azuresql-db-auth` skill. + +**Why does `BULK INSERT` (or `OPENROWSET(BULK ...)`) fail with Msg 12713 on a local file?** +Because the engine reads bulk data only from **Azure Blob Storage**, not the local filesystem, +exactly as Azure SQL Database in the cloud. Pointing `BULK INSERT` at a path inside the container +returns `Msg 12713` ("OPENROWSET is not allowed to read local files"). To load a **local** CSV, +use the `bcp` utility (it streams rows over the connection instead of reading a server-side file) +or a driver/ORM; use `BULK INSERT` only against Blob Storage via a `DATABASE SCOPED CREDENTIAL` + +`EXTERNAL DATA SOURCE`. Recipes: the `azuresql-db-seed` skill. + +**Are session/database defaults identical to the cloud?** Mostly. Some defaults +(collation, transaction isolation, ANSI settings) do not match the cloud exactly and +can cause subtle edge-case differences. Set the ones you depend on explicitly. + +## SQL Server features (intentionally absent, like the cloud) + +**Why are SQL Agent jobs / FILESTREAM / linked servers / Windows Authentication / +cross-server distributed transactions missing?** These exist in SQL Server but not in Azure SQL Database, so they are intentionally absent here too. +Removing a dependency on them is part of being cloud-ready. Use the `sa` login locally +and Microsoft Entra in the cloud instead of Windows Authentication. + +## Managed-service surfaces (not applicable to a container) + +**Why can't I manage it from the Azure portal / az CLI / ARM / Bicep / Terraform?** +Those target the cloud service, not a local container. **Why no elastic pools, +hyperscale, serverless auto-pause, or DTU/vCore limits?** Those are properties of the +cloud service tiers, not the engine, so the container does not have them (and does not +throttle on them). **Auditing:** audit-to-file works; audit to Log Analytics or Storage +is a cloud target and is not applicable locally. **Always Encrypted:** basic +functionality works; secure enclaves require host TEE support and are not validated here. diff --git a/plugins/microsoft-azuresql-db-container/skills/azuresql-db-faq/references/limitations.md b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-faq/references/limitations.md new file mode 100755 index 0000000..1031084 --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-faq/references/limitations.md @@ -0,0 +1,31 @@ +# Known limitations (snapshot) + +This is a snapshot for offline use. The **live, always-current list is the source of +truth**: https://microsoft.github.io/azure-sql-database-container/known-limitations.html +(repo: `docs/known-limitations.md`). If they disagree, trust the live page and report +the drift. When a user hits something not listed, point them to +https://aka.ms/azuresqldb-container-bug to file an issue. + +## Active issues being fixed + +1. **Restriction enforcement gaps.** Some PaaS restrictions enforced in the cloud are not yet enforced locally, so an invalid statement can succeed locally and fail at deployment. Workaround: validate against a real Azure SQL Database once before declaring readiness. +2. **Default value alignment.** Some session/database defaults (collation, transaction isolation, ANSI defaults) do not match the cloud exactly. Workaround: set the ones you depend on explicitly. +3. **Two-step provisioning.** Provision a database on a `master` connection, then reconnect to it. Public Preview plans a default startup database (e.g. `MSSQL_DB=appdb`). +4. **GUI tooling compatibility.** The VS Code MSSQL extension UI and SSMS are not yet 100% compatible (UI errors), being fixed. Use `sqlcmd` or a driver; the MSSQL extension's GitHub Copilot integration works (https://aka.ms/vscode-mssql-copilot-docs). + +## Known behavior gaps (differences from the cloud) + +- **x64 image only; no native ARM64 build.** The image is `linux/amd64`. On an ARM64 host it runs under emulation: add `--platform linux/amd64` (Docker) or `platform: linux/amd64` (compose). Never say ARM64 is "supported", and do not promise a native build or a date. Feature requests: https://aka.ms/azuresqldb-container-feature-request +- **Backup and restore.** `BACKUP DATABASE` / `RESTORE DATABASE` are not supported on the container (return `Msg 40510` in any session). Azure SQL Database in the cloud likewise does not support them. Use a Docker named volume for local persistence; use Azure SQL Database in the cloud for managed backups, point-in-time restore, and geo-replication. +- **Always Encrypted with secure enclaves.** Basic Always Encrypted works; secure enclaves need host TEE support and are not validated. +- **Auditing to Log Analytics or Storage.** Audit-to-file works; audit-to-cloud-targets is not applicable on the container. +- **Resource governance.** No per-database DTU or vCore caps (those are cloud SKU properties). +- **Connection model: two session types.** A user-database connection is an Azure-faithful session that enforces Azure semantics (`USE` -> Msg 40508). A `master` connection is a provisioning session where `USE` works (the filter is not enforced). `BACKUP`/`RESTORE` are not supported in either session (Msg 40510). Use `master` only to `CREATE`/`DROP DATABASE`; do app work on the user database. +- **Container-only preview.** The image is not on public registries (MCR / Docker Hub); shared pull-only credentials may rotate. +- **Vector index restrictions.** `CREATE VECTOR INDEX` (DiskANN) works on the container, measured on build `12.0.2000.8`, and the live page says so. Four rules apply before the statement succeeds: the session needs `SET QUOTED_IDENTIFIER ON`; the table needs at least 100 rows with non-null vectors (`Msg 42266` below that); `TRUNCATE TABLE` is refused while the index exists (`Msg 42232`); and a security policy and a vector index cannot share a table in either order (`Msg 37579` policy after index, `Msg 42244` index after policy), which is a parity gap because the two coexist in the cloud. A `vector` column tops out at 1998 dimensions (`Msg 2717` above that), and that ceiling applies in the cloud too. Only `SELECT TOP (N) WITH APPROXIMATE ... FROM VECTOR_SEARCH(...)` reads the index; a `VECTOR_DISTANCE` query is always exact, never uses the index, and raises no warning. Full-scan top-k stays exact and stays the right choice for a small table. The `azuresql-db-rag` skill carries the detail. + +## Out of scope by design + +- **Cloud-only management surfaces** (Azure portal, CLI, ARM, Bicep, Terraform) target the cloud service, not the container. +- **PaaS multi-tenancy controls** (elastic pools, hyperscale, serverless auto-pause) are cloud service-tier features, not engine features. +- **SQL Server behavior** not in Azure SQL Database (SQL Agent, FILESTREAM, full Service Broker, Windows Authentication / NTLM, cross-server distributed transactions) is intentionally absent. diff --git a/plugins/microsoft-azuresql-db-container/skills/azuresql-db-faq/skill.spec.jsonc b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-faq/skill.spec.jsonc new file mode 100644 index 0000000..34e7ece --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-faq/skill.spec.jsonc @@ -0,0 +1,111 @@ +{ + "$schema": "../../catalog/skill.spec.schema.json", + "id": "azuresql-db-faq", + "domain": "azure-sql-database-container", + "value": [ + "not-in-training-data", + "corrects-a-wrong-assumption", + "changes-too-fast-to-memorize" + ], + "correction": "Asked what the container supports, an agent answers from general SQL Server knowledge and is confidently wrong. BACKUP and RESTORE are rejected with Msg 40510, USE against a user database fails with Msg 40508, and the current limitation list is a live document rather than something to recall.", + "posture": [ + "read", + "inspect" + ], + "maturity": "preview", + "value_declaration": { + "rationale": "This skill's kernel is a way to sort a capability question, and every bucket boundary is an engine refusal that only this engine produces. The Azure SQL Database container is a gated private preview and the image is not publicly available, so no model has training data on the product, and the arm of a two-arm value run that ran without this skill would fail for the least interesting reason available: it has never heard of the thing. Running that measurement across all seventeen container skills would spend around a thousand model requests to re-establish what the product's release status already establishes. Carlos Robles accepted value for this collection on 2026-09-04 on this written argument instead. THIS IS A DECLARATION AND NOT A MEASUREMENT, and nothing may report it as one. The argument reaches only the container-specific corrections listed in covers, which are the ones no training data contains. It does not reach general Azure SQL Database and SQL Server feature knowledge, which is exactly what the buckets sort, which is ordinary material an ordinary model already handles, and whether this skill improves an answer there is unmeasured and stays unmeasured. The argument ends when the Azure SQL Database container reaches Public Preview: training data begins to contain the product, the premise that nothing could know it stops being true, and this skill has to be measured or demoted. AMENDED 2026-09-19, TEXT ONLY, AND THIS SENTENCE IS THE RECORD OF IT. One line in covers quoted two error numbers that had never been read off the engine. The first live run of this skill's probes, on image tag 18.0.226_4_147, EngineEdition 5, Edition 'SQL Azure', build 12.0.2000.8, in a container started with no MSSQL_AAD_* configuration, answered Msg 33233 where it said Msg 15007 and Msg 12824 where it said Msg 12844. Both numbers were corrected in place on 2026-09-19 and nothing else in this block was touched. The argument did not move: the engine refuses exactly what this declaration said it refuses, so what Carlos Robles signed on 2026-09-04 still stands. A signed argument that quotes a false error number would be worse than one that carries a correction on its face, which is why the numbers were fixed and this sentence was added rather than the numbers being left to rot or fixed silently.", + "covers": [ + "BACKUP and RESTORE being refused with Msg 40510, which is the boundary of the managed-service bucket", + "USE being refused with Msg 40508", + "the contained user refused with Msg 33233 and CONTAINMENT PARTIAL refused with Msg 12824", + "BULK INSERT from a local path refused with Msg 12713, because this engine reads bulk data from Azure Blob Storage only" + ], + "does_not_cover": [ + "general Azure SQL Database and SQL Server feature knowledge, which is what the buckets sort rather than what they add", + "how to phrase a hedged answer when a question does not resolve" + ], + "decided_by": "Carlos Robles", + "decided_on": "2026-09-04", + "expires_when": "the-container-reaches-public-preview" + }, + "applies_to": [ + "azure-sql-db-container" + ], + "validation": { + "target": "container", + "assert": [ + "answers from the documented limitation list", + "links the live known-limitations page rather than reciting from memory" + ], + "probes": [ + { + "sql": "SELECT CAST(SERVERPROPERTY('EngineEdition') AS int) AS engine_edition, CAST(SERVERPROPERTY('Edition') AS nvarchar(128)) AS edition;", + "expect": { + "rows": [ + [ + 5, + "SQL Azure" + ] + ] + }, + "why": "The first bucket in the skill's mental model, made executable: this is the Azure SQL Database engine and not the SQL Server image, which is the premise every other answer in the skill rests on. If this returns anything else, the four bucket sort is being applied to the wrong product." + }, + { + "sql": "BACKUP DATABASE master TO DISK = N'/var/opt/mssql/data/probe_faq_backup.bak';", + "expect": { + "error": 40510 + }, + "why": "The most asked question in the skill, and one it answers with a specific number in three places: SKILL.md, references/faq.md and references/limitations.md all say Msg 40510. The database named is master rather than the scratch database because the statement filter refuses the statement before it resolves the name, and the skill's own claim is that this fails in every session." + }, + { + "sql": "RESTORE DATABASE master FROM DISK = N'/var/opt/mssql/data/probe_faq_backup.bak';", + "expect": { + "error": 40510 + }, + "why": "The skill claims the same number for RESTORE as for BACKUP, and the two are worth separating because the answer people act on is the restore half: it is what somebody reaches for after losing a container. If RESTORE were merely failing because the file does not exist, this probe would report a file error instead, which is itself the signal that the statement is not being filtered." + }, + { + "sql": "USE master;", + "expect": { + "error": 40508 + }, + "why": "The second most asked question, and the one whose answer is easiest to get half right. The refusal is a property of the session, not of the engine: this probe runs in the scratch user database and must fail, whereas the same statement on a master connection succeeds because master is a provisioning session. A pass here also confirms the runner is not accidentally connected to master, which would quietly invalidate the two probes above." + }, + { + "sql": "CREATE USER probe_faq_contained_user WITH PASSWORD = 'Pr0be_Passw0rd!x';", + "expect": { + "error": 33233 + }, + "why": "The answer here is inverted from Azure SQL Database, which is what makes it worth a probe: in the cloud a contained user is the recommended shape, and on the container it fails, so the correct guidance is a server login plus a mapped user. THE NUMBER WAS WRONG UNTIL 2026-09-19: this skill's SKILL.md and references/faq.md both said Msg 15007, and the engine says Msg 33233, \"You can only create a user with a password in a contained database.\" Body and probe were corrected together. The password in this probe is a throwaway for a user that never exists. Re-measured 2026-09-19 on image tag 18.0.226_4_147, EngineEdition 5, Edition 'SQL Azure', build 12.0.2000.8, in a scratch container started with no MSSQL_AAD_* configuration." + }, + { + "sql": "ALTER DATABASE CURRENT SET CONTAINMENT = PARTIAL;", + "expect": { + "error": 12824 + }, + "why": "The obvious workaround for the refusal above, and it is also refused, which is why the skill's answer sends people to a login and a mapped user rather than to a database setting. The engine says Msg 12824, \"The sp_configure value 'contained database authentication' must be set to 1 in order to alter a contained database.\", then Msg 5069, \"ALTER DATABASE statement failed.\" THE NUMBER WAS WRONG UNTIL 2026-09-19: this skill said Msg 12844 with the text \"this functionality is not available in the current edition of SQL Server\", which no run of this probe has ever produced. Without this probe the previous one invites the reader to try the containment setting and conclude the skill was simply missing a step. Re-measured 2026-09-19 on image tag 18.0.226_4_147, EngineEdition 5, Edition 'SQL Azure', build 12.0.2000.8, in a scratch container started with no MSSQL_AAD_* configuration." + }, + { + "sql": "CREATE TABLE dbo.probe_faq_bulk (col1 nvarchar(100) NULL);\nBULK INSERT dbo.probe_faq_bulk FROM '/var/opt/mssql/data/probe_faq_nonexistent.csv' WITH (FIELDTERMINATOR = ',', ROWTERMINATOR = '\\n');", + "expect": { + "error": 12713 + }, + "why": "A local file is not a valid source: the engine reads from Azure Blob Storage, so the loading answer for a laptop CSV is a client side tool and not BULK INSERT. Msg 12713 is stated in this skill's references/faq.md. The file deliberately does not exist, which is the point: the statement is refused for being local before anything tries to open it, so a file-not-found error here would mean the restriction has been lifted and the skill's answer needs rewriting." + } + ] + }, + "triggering": { + "explicit": [ + "Use the azuresql-db-faq skill" + ], + "implicit": [ + "can I take a backup of this container?" + ], + "negative": [ + "set up a local PostgreSQL database with docker compose", + "provision an Azure SQL Database in my subscription", + "connect to SQL Server on my company network" + ] + } +} diff --git a/plugins/microsoft-azuresql-db-container/skills/azuresql-db-feedback/SKILL.md b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-feedback/SKILL.md new file mode 100755 index 0000000..c750264 --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-feedback/SKILL.md @@ -0,0 +1,149 @@ +--- +name: azuresql-db-feedback +description: >- + Reports a bug or files feedback about the azuresql-db-* agent skills themselves, or about the + Azure SQL Database container (Private Preview). Use when the user says a skill or the container + "did not work", hit an error, behaved unexpectedly, or is missing something; and when they say + "report a bug", "file an issue", "open a GitHub issue", "request a feature", "give feedback", or + "tell the team". Also use when you, the agent, had to deviate from an azuresql-db-* skill or work + around a defect in one to finish a task: that is a bug worth reporting even if the task succeeded. + Decides whether the problem belongs to the SKILL or to the CONTAINER, since they use different + issue templates, then builds a complete prefilled GitHub issue from context you already have. + Never submits anything without explicit confirmation from the user. +--- + +# Report a problem with the skills, or with the container + +The user should never have to assemble a bug report by hand. You are already holding what a good one needs: +which skill you were following, what it told you to do, what you actually had to do, the image tag, the host, +the runtime, the failing command, and the error. Your job is to turn that into a complete report and hand it +to the user to submit. + +**Repository:** `microsoft/azure-sql-database-container` (both the container and the skills live here). + +The claims in this skill are about issue forms in `microsoft/azure-sql-database-container`, +not about the engine, so no engine measurement applies to them. Verified on 2026-09-05: +`aka.ms/sql-agent-skills-feedback` still answers `301` to +`https://github.com/microsoft/azure-sql-database-container/issues/new?template=skill_feedback.yml` +with the query string dropped, which is exactly why a prefilled report has to use the full +`github.com` URL. The field ids, labels and dropdown values are read from the issue form +definitions in this repository and mirrored in +[references/issue-fields.md](references/issue-fields.md), which you open before you build any URL. + +## The two rules that matter most + +1. **Never create an issue without explicit confirmation.** Show the user the full title and body first and + wait for a clear yes. You may offer; you may never submit unasked. This applies to every path below, + including the `gh` CLI. +2. **Redact before you send.** Everything submitted is public. See [Redaction](#step-3-redaction-do-this-before-you-build-anything). + +## Step 1: skill problem, or container problem? + +**Get this right first: they use different issue templates.** + +Ask yourself what actually failed. + +| The problem | It belongs to | Template | +| --- | --- | --- | +| A skill told the agent to do the **wrong** thing, or failed to say something it needed to say | the **skill** | `skill_feedback.yml` | +| The **wrong skill** loaded, or no skill loaded when one should have | the **skill** | `skill_feedback.yml` | +| A skill would not install, or the agent never picked it up | the **skill** | `skill_feedback.yml` | +| You had to **deviate from the skill** or work around it to make the task succeed | the **skill** | `skill_feedback.yml` | +| The skill said the right thing, the agent did the right thing, and **the container still failed** (will not start, query errors, engine behaves unexpectedly) | the **container** | `bug_report.yml` | +| The **container** is missing a capability the user wants | the **container** | `feature_request.yml` | + +The test that settles it: **if the instructions were correct and the engine still broke, it is a container +bug. If the instructions were wrong, incomplete, or ignored, it is a skill bug.** When genuinely torn, ask the +user. Do not guess, and do not file both. + +If the user is only reporting that something worked well, do not open an issue. Point them at +[Discussions](https://github.com/microsoft/azure-sql-database-container/discussions) and stop. + +## Step 2: gather the facts + +Only run a command if you do not already know the answer. + +**For a skill problem** (the important ones, and the ones we are otherwise blind to): + +- Which skill, by name (`azuresql-db-rag`, etc). If none loaded, say so: that is itself the bug. +- Which agent you are (Claude Code, GitHub Copilot, Codex, Cursor). Skills behave differently across + harnesses and we cannot see which one the user ran. +- **The instruction that was wrong or missing, quoted from the skill, and what actually worked instead.** + This is the single most valuable field in the whole report. Without it we cannot fix the skill. +- The prompt the user gave you. + +**For a container problem:** the image tag, the host OS (mapped to the exact dropdown value), the container +runtime and version, what happened, and the commands that reproduce it. `docker logs sqldb` if the container +is what broke. + +## Step 3: redaction (do this before you build anything) + +Strip all of the following from every field, including logs and repro steps: + +- The SA password (`MSSQL_SA_PASSWORD`, `-P `, the `Password=` field of a connection string). Replace with `***`. +- Registry credentials (the `docker login` username and password). +- Full connection strings. Keep the shape, drop the secret: `Server=localhost,1433;Database=appdb;User Id=sa;Password=***;TrustServerCertificate=true`. +- Any customer or application data, table contents, embeddings, or paths that identify the user or their employer. +- Access tokens of any kind. + +The repository is public and issues are world readable. A report that leaks the user's password is worse than +no report at all. + +## Step 4: draft and show + +Write the report, then show it to the user in full and ask whether to file it. Say which fields you filled and +which you left blank. If you could not determine a value confidently, **leave it blank rather than guess**: a +wrong skill name or host OS sends triage down the wrong path. + +## Step 5: submit + +Try these in order, stop at the first that works, and **confirm with the user first** either way. + +**Tier 1: the `gh` CLI**, if `gh auth status` succeeds. The issue is authored by the user, so they get replies. + +```bash +gh issue create --repo microsoft/azure-sql-database-container \ + --title "[Skill]: " \ + --label skills --label needs-triage --label User-filled --label via-skill \ + --body-file +``` + +Write the body to a file rather than passing it inline, so quoting and newlines survive. + +**Tier 2: a prefilled URL.** No credentials, no setup, and the user sees exactly what will be submitted before +anything happens. Use this whenever `gh` is not available; it always works. + +Build the URL from the issue form's field ids and print it for the user to open. The field ids, the **verbatim** +dropdown values, and worked examples for all three templates are in +[references/issue-fields.md](references/issue-fields.md). **Read that file before constructing a URL.** + +## Validation rules + +- The user saw the exact title, body and labels before anything was submitted, and said yes. +- The report went to the right template: a skill problem on the skills form, a container problem on the container form. +- No SA password, registry credential or access token appears in any field. Re-read the body once more before submitting. +- Every dropdown value is verbatim from the field reference, which you open before building any URL, or the field was left out. +- A prefilled report uses a full `github.com` URL, never an `aka.ms` link, because those drop the query string. +- Tier 1 succeeded when `gh issue create` printed the new issue URL; tier 2 succeeded when the user opened the URL and the form came up with the fields already filled in. If neither happened, the report was not filed: say so rather than implying it was. + +## Do not + +- Do not create, comment on, or close an issue without explicit user confirmation. +- Do not include the SA password, registry credentials, or access tokens in any field. Ever. +- Do not file a skill problem on the container template, or the reverse. They are triaged by different people. +- Do not guess a dropdown value. Leave the field out if you are unsure; an omitted dropdown renders unselected, but a wrong one misroutes triage. +- Do not use an `aka.ms` short link to carry a prefilled report. Those links drop query strings, so every field you filled in is silently lost. Use the full `github.com` URL. (The `aka.ms` links are for humans opening an empty form: [skills feedback](https://aka.ms/sql-agent-skills-feedback), [container bug](https://aka.ms/azuresqldb-container-bug), [container feature](https://aka.ms/azuresqldb-container-feature-request).) +- Do not open an issue for something already on the [Known limitations](https://microsoft.github.io/azure-sql-database-container/known-limitations.html) page, or already in [open issues](https://github.com/microsoft/azure-sql-database-container/issues). Point the user there instead. +- Do not nag. Offer once, take no for an answer, and move on. + +## References + +- [references/issue-fields.md](references/issue-fields.md): the exact field ids for all three templates, the verbatim dropdown values, URL construction and its length limit, and worked examples. Read this before building a prefilled URL. + +## Staying current + +Authoritative, version-pinned references for the tools this skill uses (read the one you need): + +- [GitHub issue-form schema syntax](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema): the form-schema fields (input, textarea, dropdown) the prefill maps to. + +If the **Microsoft Learn MCP** server is configured, use `mcp__microsoft-learn__microsoft_docs_search` or `mcp__microsoft-learn__microsoft_docs_fetch` to fetch the current version of any of these on demand. It is optional; when it is unavailable, the references above are authoritative. diff --git a/plugins/microsoft-azuresql-db-container/skills/azuresql-db-feedback/references/issue-fields.md b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-feedback/references/issue-fields.md new file mode 100755 index 0000000..1eb49f1 --- /dev/null +++ b/plugins/microsoft-azuresql-db-container/skills/azuresql-db-feedback/references/issue-fields.md @@ -0,0 +1,197 @@ +# Issue form fields and prefilled URLs + +## Contents + +- [How prefilling works](#how-prefilling-works) +- [Which template](#which-template) +- [Skill feedback fields](#skill-feedback-fields-skill_feedbackyml) +- [Container bug fields](#container-bug-fields-bug_reportyml) +- [Container feature fields](#container-feature-fields-feature_requestyml) +- [Labels: pass all of them](#labels-pass-all-of-them) +- [URL length](#url-length) +- [Worked example: a skill bug](#worked-example-a-skill-bug) +- [Checkboxes cannot be prefilled](#checkboxes-cannot-be-prefilled) + +## How prefilling works + +GitHub issue forms prefill from URL query parameters. The parameter name is the field's `id` in the template +YAML; the value is URL-encoded. Base URL: + +``` +https://github.com/microsoft/azure-sql-database-container/issues/new?template=