azuresql-db-faq

Azure SQL Developer: 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.

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 the 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: CREATE VECTOR INDEX DDL, the VS Code MSSQL extension UI and SSMS, and full PaaS restriction enforcement are still being completed.

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 (SDS) 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 non-SDS 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/azuresql-developer-feature-request.
• "Why can't I CREATE VECTOR INDEX?" That DDL is still in development. The VECTOR type and VECTOR_DISTANCE work today; use a full-scan top-k query for now (fine for prototype-sized corpora).
• "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 (references/entra-auth.md). Also see Getting started: 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 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 (Msg 15007), and ALTER DATABASE ... SET CONTAINMENT = PARTIAL fails too (Msg 12824). 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. Full recipe: the azuresql-db-auth skill.

More entries with the full "why" are in references/faq.md, and the limitations list (kept in step with the docs) is in references/limitations.md.

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 "the 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.

References

• 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: 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: per-language quickstarts, connection info, TLS, and drivers for the cloud service.
• VECTOR data type (T-SQL): 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.