# Azure SQL

> Use when Azure SQL Database comes up without a specific task: what it can do today, GA or preview, which tier, tool or skill fits, current limits and defaults. Routes to the owning skill. Not Managed Instance or SQL Server.

- Skill: `microsoft/azure-sql` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add microsoft/azure-sql`
- Raw SKILL.md: https://api.skillmd.com/api/skills/microsoft/azure-sql/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: Microsoft (https://skillmd.com/u/microsoft)
- Updated: 2026-11-18
- Page: https://skillmd.com/skills/microsoft/azure-sql

---


# Working with Azure SQL Database

The front door. It answers two questions and hands everything else on: **what is true right now**,
and **which skill owns the task**. It holds little content of its own, because the content that
would live here is the content that goes stale.

The capability facts below move with releases. Refetch them from Microsoft Learn before repeating
anything below.

## The first rule: ask, do not recall

A model's picture of this service is a snapshot and the snapshot is old. Availability, defaults,
limits and command flags all move, and none of them fail loudly when recalled wrongly. They fail at
deployment, in review, or in a bill.

- **Never state general availability from memory.** Preview against generally available is the most
  consequential distinction in this service and the one that changes most often.
- **Never quote a service limit from memory.** Read it from the resource limits article, or ask the
  running system. Help text is not authoritative either: it can name a flag value the command
  rejects, or state a limit as one where the real number is ten.

Ask the database in front of you rather than yourself. `EngineEdition` separates the products of
this family, and everything in this catalog is written for `5`. It does not separate the local Azure
SQL Database container from the service: both report `5`, `Edition` `SQL Azure` and `@@VERSION`
`12.0.2000.8`. The server name settles that one: a `*.database.windows.net` host is the service.

```sql
SELECT SERVERPROPERTY('EngineEdition') AS engine_edition,   -- 5 is Azure SQL Database
       DB_NAME()                       AS current_database,
       compatibility_level
FROM sys.databases
WHERE name = DB_NAME();
```

Ask the tool in front of you too. Every neighbour skill's flags are build-specific, so read the
build before handing over, and route around whatever is missing:

```bash
sqlcmd --version
sqlpackage /version:True
dotnet --version
dab --version
azd version
az version --query '"azure-cli"' --output tsv
prisma --version || npx --no-install prisma --version
```

`prisma` is normally a project-local dependency rather than a command on `PATH`, which is why the
last line falls through to `npx`.

## Scope: which product this actually is

The Azure SQL family shares an engine and does not share behaviour, limits or feature sets. This
catalog is about **Azure SQL Database**, the multi-tenant platform service, plus the Azure SQL
Database container for local development. It is not Azure SQL Managed Instance, which reports
`EngineEdition` 8, not SQL database in Microsoft Fabric, which reports 12, and not SQL Server on
virtual machines, which reports 2 or 3.

This matters more than tidiness: capabilities are announced across the family in one blog post and
then arrive at different times, or never. Reading "announced for SQL" and writing it into an Azure
SQL Database design invents a feature. Name the other members of the family only to
exclude them, and say which product an announcement was actually about.

Two traps that follow from the product being database-scoped rather than instance-scoped:

- Instance-level features have no home here. There is no SQL Agent, and no cross-database query by
  three-part name to another user database. `USE <another database>` does not switch context: it
  returns `Msg 40508`, and a new connection is the only way to change database.
- Announcements about analytics-oriented SQL surfaces are not this product. If a capability is
  documented only under a different product's namespace, it does not exist here until a page that
  applies to Azure SQL Database says so.

## Capability currency

**The only time-sensitive content in this file, written to be lifted out whole.** If release
announcements start churning it, it becomes its own skill and this file keeps the routing.

| Fact | State | Refetch from |
|---|---|---|
| Engine version and default compatibility level | Engine version 17. New databases default to **170**; 170 down to 100 are supported | The `ALTER DATABASE` compatibility level reference |
| A database that arrived from somewhere else | Keeps the compatibility level it had. Neither a migration nor a tier conversion raises it | The same page, plus `sys.databases` |
| Default tier advice | Learn names Hyperscale **"the recommended and default service tier for all new and modernizing OLTP and HTAP workloads"**, reversing older advice to start on General Purpose | The Hyperscale service tier article |
| Native vectors | The `vector` type and `VECTOR_DISTANCE` are **generally available**. `VECTOR_DISTANCE` is always exact and never uses an index, whatever indexes exist | The vectors article |
| Approximate vector search | The DiskANN vector index and `VECTOR_SEARCH` are **generally available** in Azure SQL Database and SQL database in Fabric. They remain **preview** in SQL Server 2025, and so on the local container | The `CREATE VECTOR INDEX` reference, *Feature availability* |
| The free offer | Up to **10** free databases per subscription, each with 100,000 vCore seconds, 32 GB data and 32 GB backup storage a month, on General Purpose serverless | The free offer FAQ |
| Versioning | Evergreen. There is no version to pin and no release to wait for | The what is new article |

Three shapes to watch for, rather than facts to memorize:

- **Preview features carry conditions.** Region, hardware family, sometimes an update policy. "It is
  in preview" is not the same as "you can use it".
- **Defaults change under existing resources without changing them.** A default that applies to new
  databases says nothing about the one in front of you. Query it.
- **A feature can exist and still be the wrong answer.** Availability is the first question, not the
  last.

## Which skill owns this task

Every name below is a directory in this catalog. Nothing routes at a name that does not answer.

### Getting a database, and connecting to it

| Task | Route to |
|---|---|
| Create a server and database, open the firewall, use the free offer, get a working connection string | `provision-azure-sql-db` |
| Choose a tier for a real workload, size or convert to Hyperscale, decide about replicas | `provision-hyperscale` |
| Run or troubleshoot the Azure SQL Database engine locally in a container | `azuresql-db-container` |
| Start from a ready-made local development environment with a database in it | `dev-container-templates` |
| Driver choice, connection string, encryption, retry, pool sizing | `connect-to-azure-sql` |
| The same for one language | `connect-from-dotnet`, `connect-from-python`, `connect-from-typescript-and-node` |
| A connection already failed and there is an error number to read | `connectivity-troubleshoot` |
| Passwordless connection, managed identity, a database user for an application identity | `entra-id-auth` |

### Writing SQL and modelling data

| Task | Route to |
|---|---|
| T-SQL that is correct here rather than PostgreSQL syntax in a T-SQL costume | `t-sql-correctness` |
| JSON stored or queried in the database, `OPENJSON` | `t-sql-json-and-openjson` |
| Insert or update, and the `MERGE` shapes that lose rows | `t-sql-upserts-merge` |
| Tables, keys, string lengths, collation, the index key byte limit | `design-azure-sql-schema` |
| An object-relational mapper | `ef-core-azure-sql`, `prisma-azure-sql`, `sqlalchemy-azure-sql` |
| Parameterizing, dynamic SQL, identifiers a parameter cannot reach | `prevent-sql-injection` |
| Tenant isolation, row level security, a policy a test can prove | `rls-multi-tenant` |

### Vectors, retrieval and AI

| Task | Route to |
|---|---|
| The `vector` type, `VECTOR_DISTANCE`, the dimension ceiling, the vector index | `vector-search-azure-sql` |
| Embeddings generated inside the database, external models, chunking in T-SQL | `embeddings-and-external-models` |
| A retrieval pipeline end to end, grounded answers over your own data | `rag-on-azure-sql` |
| Whether a prototype proved on the local container still holds in the cloud | `rag-local-with-container` |
| LangChain or LlamaIndex over this database | `langchain-and-llamaindex-on-azure-sql` |

### Building, shipping and moving data

| Task | Route to |
|---|---|
| Sequencing the whole job of standing up a new application on this service | `build-app-on-azure-sql` |
| A REST or GraphQL API over the schema without writing one | `dab-rest-and-graphql` |
| Hosting that generated API, or its SQL MCP Server endpoint, in Azure Container Apps | `deploy-dab-to-azure` |
| Connecting an AI agent or MCP client to a hosted Data API builder `/mcp` endpoint | `dab-mcp-endpoint` |
| Serverless function bindings, and reacting to row changes | `azure-functions-sql-bindings` |
| Deploying the application and its database to Azure | `deploy-app-to-azure` |
| A source-controlled database project, its target platform, pre and post deployment scripts | `sql-database-projects` |
| Shipping a schema change from a continuous integration workflow | `github-actions-for-sql` |
| Whether a migration is safe to run against a live database | `schema-migrations-safely` |
| Moving a whole database as a portable file, dacpac against bacpac | `sqlpackage-import-export` |
| Loading a large amount of data into a table that already exists | `bulk-load-and-bulk-copy` |

### When it is slow, stuck or lost

| Task | Route to |
|---|---|
| One query is slow, and nobody has triaged why yet | `slow-query-investigation` |
| Reading the execution plan itself | `read-execution-plan` |
| Who is blocking whom right now | `check-live-blocking` |
| A deadlock that already happened | `deadlock-analysis-azuresql` |
| CPU, data or log IO, memory, worker and session limits | `resource-usage-sqlserver` |
| Capturing events over a window rather than sampling now | `create-xe-session` |
| Point-in-time restore, geo-restore, long-term retention | `restore-and-recover` |
| A skill in this catalog was wrong, or the job has no skill | `skill-feedback` |

One job has no skill here yet. **Migrating an existing SQL Server estate onto this service**:
assess compatibility before promising a target tier.

## Security, by reference

There is a first-party checklist, it is maintained, and copying it here would make a stale copy of a
living document. Read the security best practices article, and treat these four as non-negotiable:

1. **No secret in source, in a repository, or in a transcript.** An identity beats a password
   everywhere one is available.
2. **Encryption on, certificate validation on.** A certificate error is a name problem, not a trust
   problem.
3. **Least privilege.** The administrator login is not an application identity.
4. **Every statement parameterized.** Concatenating user input into T-SQL is the vulnerability you
   are most likely to write.

## Check it worked

This skill has done its job when three things are true, and each one is checkable.

**You are pointed at the right product.** Run the first query above. `engine_edition` must be `5`:
not 8, which is Azure SQL Managed Instance, not 12, which is SQL database in Microsoft Fabric, and
not 2 or 3, which is SQL Server. On any other value this catalog's advice is not safe to apply. Then
confirm the instance-level assumption directly, expecting the error rather than a switch:

```sql
USE master;
```

Expect `Msg 40508, USE statement is not supported to switch between databases`. If it succeeds, you
are not on Azure SQL Database and nothing above holds.

**Nothing was answered from memory.** Every capability, default or limit in your answer traces to a
page you fetched or to a query you ran, and every preview feature is labelled preview each time it
appears, not once.

**The task left this skill.** Name the skill you handed to and say why. If your answer resolved the
whole task inside this file, either it really was an orientation question, or you answered something
a neighbour owns and should not have.

## Do not

- Do not answer "is X generally available" from memory. It is the question this file exists to stop
  being answered that way.
- Do not carry a capability across the family. An announcement is about one product until a page
  says otherwise.
- Do not quote a limit, a quota or a flag value without checking it, including from help text.
- Do not answer a task another skill owns just because this file loaded first. Hand it over.
- Do not restate a stable documentation page here. Link it, and say when to read it.
- Do not treat the local container as proof about cloud behaviour, or cloud behaviour as a promise
  about the container.

## References

- Open [references/learn-pages-by-subject.md](references/learn-pages-by-subject.md) before
  answering a currency question, or whenever the honest answer is "I would be guessing". It holds
  the pinned first-party pages by subject and the four questions that decide whether a capability
  exists in this product at all.

## Operational handoffs to microsoft-sql-admin

Install `microsoft-sql-admin` alongside `microsoft-sql` for operational diagnostics. These tasks now have one owner with Azure-specific references: `slow-query-investigation`, `check-live-blocking`, `resource-usage-sqlserver`, `create-xe-session`, and `connectivity-troubleshoot`. Use `deadlock-analysis-azuresql` for a completed Azure deadlock and `authentication-diagnostics` for login/token/principal failures. A combined blocking/deadlock incident may require both skills; live blocking alone does not retrieve an old deadlock graph. If the owning skill is not installed, identify the missing dependency rather than claim it was loaded. VS Code's curated plugin includes these operational owners and uses the host's SQL tools; it does not require the SQL Tools MCP server.

The two plugins run side by side. `microsoft-sql-admin` ships the SQL Tools MCP server (NuGet package `Microsoft.SqlServer.SQLtools.MCPserver`, started from the plugin's MCP configuration); when that server is connected, the T-SQL in these skills can run through its `mssql_execute_query` tool, which is read-only by default, instead of `sqlcmd`, and its `sql-tools-mcp-setup` skill enables the server with the user's permission. Nothing else in `microsoft-sql` changes, and these skills never require that server.

