Get started
Run the Azure SQL Database container on your machine for development, testing, and CI. Three commands take you from pull to your first query, with Docker, Podman, or WSL containers. The image is public on Microsoft Container Registry, so there is nothing to sign up for.
The container is a development target, not a production database. For what it includes and leaves out, see the FAQ.
- Prerequisites
- Set up the container
- Set up with your coding agent
- Microsoft Entra authentication
- Troubleshooting
- Report an issue
Prerequisites
Host platforms
The image provides linux/amd64 and linux/arm64 variants. Container runtimes select the matching architecture automatically.
| Host OS | Architecture | Status |
|---|---|---|
| macOS 14 or later | x86_64, ARM64 | Supported |
| Linux (Ubuntu, Debian, Fedora) | x86_64, ARM64 | Supported |
| Windows 11 | x86_64, ARM64 | Supported (WSL2) |
On ARM64, full-text search, PolyBase, and extensibility runtimes are not available yet. See feature availability.
Container runtimes
The container is OCI-compliant and runs on any modern runtime. Tested runtimes:
- Docker 24 or later
- Podman 5.0 or later
- Rancher Desktop 1.13 or later
- containerd, through nerdctl or Kubernetes
- WSL containers (
wslc, included with WSL on Windows)
Pick the runtime that already works on your machine. The container image and the connection behavior are the same across runtimes.
System resources
Minimum allocation for the container runtime:
- CPU: 2 cores
- Memory: 4 GB available to the runtime VM
- Disk: 10 GB free for the image and a small database, more for larger datasets
If your container runtime’s VM is set lower than this, the container may fail to start or may run with reduced performance.
Network
- You need an internet connection the first time you pull the image. After the pull, the container runs offline.
- The container listens on port 1433. Make sure the port is free, or map a different host port.
Tools
You do not need sqlcmd or any database tool installed: the container bundles sqlcmd. To connect from your app, use a driver or ORM for your stack, such as mssql for Node.js, mssql-python, pyodbc, EF Core, Prisma, SQLAlchemy, or JDBC.
The container does not need an Azure subscription. To deploy to Azure SQL Database afterwards, you need one, and the free tier works.
Set up the container
The commands use docker. With Podman, replace docker with podman. On Windows with WSL containers, replace docker with wslc. The password step needs a bash or zsh shell.
1. Pull the image
docker pull mcr.microsoft.com/mssql/azure-sql-db-server:latest
2. Start the container
Generate a strong SA password, then start the engine on port 1433, bound to localhost:
MSSQL_SA_PASSWORD="Aa1$(openssl rand -hex 16)"
docker run --name sqldb -e "ACCEPT_EULA=Y" \
-e "MSSQL_SA_PASSWORD=$MSSQL_SA_PASSWORD" \
-p 127.0.0.1:1433:1433 -d \
mcr.microsoft.com/mssql/azure-sql-db-server:latest
Confirm it is up with docker ps --filter "name=sqldb". You should see sqldb with an Up status. If it exited, run docker logs sqldb; the most common cause is a password that does not meet the complexity policy. Keep MSSQL_SA_PASSWORD in your environment, not in source control.
Prefer docker compose? Export the password with export MSSQL_SA_PASSWORD, save this as docker-compose.yml, and run docker compose up -d:
services:
sqldb:
image: mcr.microsoft.com/mssql/azure-sql-db-server:latest
container_name: sqldb
ports:
- "127.0.0.1:1433:1433"
environment:
ACCEPT_EULA: "Y"
MSSQL_SA_PASSWORD: "${MSSQL_SA_PASSWORD:?Set MSSQL_SA_PASSWORD}"
volumes:
- sqldb-data:/var/opt/mssql
volumes:
sqldb-data:
3. Connect and run your first query
The container bundles sqlcmd, so nothing needs installing on your machine. The -C flag trusts the container’s self-signed certificate. The engine takes a few seconds to start after docker run, so this waits up to a minute for it to accept connections, then runs the query. If it shows an error instead, docker logs sqldb says why.
for i in {1..30}; do
docker exec sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost \
-U sa -P "$MSSQL_SA_PASSWORD" -C -Q "SELECT 1" >/dev/null 2>&1 && break
sleep 2
done
docker exec sqldb /opt/mssql-tools18/bin/sqlcmd \
-S localhost -U sa -P "$MSSQL_SA_PASSWORD" -C \
-Q "SELECT @@VERSION;"
A result that names Microsoft SQL Azure confirms the Azure SQL Database engine.
4. Create your database
The engine does not create application databases on its own. Create one on a master connection, named appdb here or whatever you choose:
docker exec sqldb /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;"
Then connect to it by name. Select the database in the connection string, Database=appdb or -d appdb for sqlcmd, rather than switching with USE.
Other ways to connect
- sqlcmd on your machine.
sqlcmd -S localhost,1433 -U sa -P "$MSSQL_SA_PASSWORD" -C -d appdb - VS Code with the MSSQL extension. Server
localhost,1433, SQL Login, usersa, your password, and Trust server certificate. Tooling experiences in SQL Server Management Studio and Visual Studio Code may evolve during the preview. - Your app.
Server=localhost,1433;Database=appdb;User Id=sa;TrustServerCertificate=true, with the password read from your environment. When you move to Azure SQL Database, the connection string changes to your Azure server and Microsoft Entra sign-in.
Stop and clean up
docker rm -f sqldb
# or, with docker compose (add -v to also remove the data volume):
docker compose down
Set up with your coding agent
The container skills are part of the microsoft-sql plugin. They cover pulling the image, waiting for the engine to be ready, and creating the database, with you reviewing each step. Install them once for Claude Code, GitHub Copilot, Codex, and Cursor; per-tool commands are in Skills.
npx skills add microsoft/microsoft-sql
Then paste this into your agent:
Add a local Azure SQL Database to this project, then scaffold the schema, migrations and data-access layer for my stack.
Microsoft Entra authentication
Microsoft Entra authentication is included. During the public preview, you set it up from the command line with environment variables and a mounted certificate. SQL authentication with sa, as above, stays the simple default; use Microsoft Entra when you want closer parity with Azure SQL Database.
For the app registration and the certificate, follow Configure Microsoft Entra ID authentication for SQL Server on containers. Mount a .pfx with an empty export password, then pass MSSQL_AAD_CLIENT_ID, MSSQL_AAD_PRIMARY_TENANT, and MSSQL_AAD_CERTIFICATE_FILE_PATH:
docker run -d --name sqldb \
-e "ACCEPT_EULA=Y" \
-e "MSSQL_SA_PASSWORD=${MSSQL_SA_PASSWORD:?Set MSSQL_SA_PASSWORD}" \
-e "MSSQL_AAD_CLIENT_ID=<client-id>" \
-e "MSSQL_AAD_PRIMARY_TENANT=<tenant-id>" \
-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 127.0.0.1:1433:1433 \
mcr.microsoft.com/mssql/azure-sql-db-server:latest
To create a Microsoft Entra server admin at startup, add MSSQL_AAD_SERVER_ADMIN_NAME, MSSQL_AAD_SERVER_ADMIN_TYPE (0 for a user, 1 for a group), and MSSQL_AAD_SERVER_ADMIN_SID (the user or group object ID).
Troubleshooting
The commands below use docker. With another runtime, use its own CLI (podman, nerdctl, or wslc); the behavior is the same.
Let your coding agent diagnose it
Paste this into your agent. It can check your machine and read the container logs itself:
My local Azure SQL Database container is not working. Diagnose it. Check my container runtime is installed, running, and set to Linux containers; check it has enough memory (the engine needs at least 2 GB); check port 1433 is free; check the image architecture matches this host (linux/amd64 or linux/arm64); then read the container logs and tell me the actual cause and the fix.
Check your container runtime first
Most first-run failures come from the runtime, not the database. Check all four:
- It is installed and up to date. Setup guides: Docker, Podman, Rancher Desktop, containerd, WSL containers.
- It is running.
docker info(orpodman info, orwslc version) returns without an error. A fresh install does not always start the engine for you. - It runs Linux containers. On Windows, a runtime set to Windows containers cannot run this image. Switch it to Linux containers. This is the most common failure on Windows.
- It has enough memory. The engine needs at least 2 GB to start. Give the runtime 4 GB and 2 CPUs: in Docker Desktop and Rancher Desktop under Settings, Resources; for Podman with
podman machine set --memory. Too little memory shows up as a container that starts and then stops with no obvious error.
The container will not start, or will not accept connections
Read the logs first. They name the cause in almost every case:
docker logs sqldb
- The container exits. Check for a missing
ACCEPT_EULA=Y. The container does not start without it. - The container is Up, but connections fail with a login timeout or “server is not found”. Right after
docker run, the engine is still starting: wait a few seconds and try again. If it keeps failing, the engine inside the container did not start. The usual causes are an SA password that does not meet the policy (8 or more characters, with at least three of upper case, lower case, digits, and symbols) or too little memory.
Fix the cause, remove the container with docker rm -f sqldb, and run it again. Changing an environment variable does not affect a container that already exists.
“no matching manifest” or “exec format error”
The image provides linux/amd64 and linux/arm64 variants, and current runtimes select the matching one. Update your runtime, then pull the image again. Do not force --platform linux/amd64 on an ARM64 host unless you need the x64 image under emulation.
Port 1433 is already in use
Something else is bound to the port, often an existing SQL Server. Map a different host port and connect to localhost,1434 instead:
docker run --name sqldb -e "ACCEPT_EULA=Y" \
-e "MSSQL_SA_PASSWORD=$MSSQL_SA_PASSWORD" \
-p 127.0.0.1:1434:1433 -d \
mcr.microsoft.com/mssql/azure-sql-db-server:latest
Connection fails right after the container starts
The engine is not ready the instant docker run returns. It takes a few seconds. Retry the connection rather than treating the first failure as final. In a script, run sqlcmd -C -b -l 2 in a retry loop.
“Cannot open database”
The engine does not create databases on its own, as in Azure SQL Database. Create yours on a master connection first.
USE appdb fails with Msg 40508
This is expected, and it matches Azure SQL Database. Select the database in the connection string (Database=appdb, or -d appdb for sqlcmd) instead of switching with USE.
It is not the Azure SQL Database engine
If SELECT SERVERPROPERTY('EngineEdition'); does not return 5, you are running the SQL Server image (mcr.microsoft.com/mssql/server) rather than this one. Recreate the container with the image from step 1.
Report an issue
Report a bug. When reporting an issue, include the container image version, host operating system and architecture, startup command, client tool and version, relevant logs, and a minimal reproduction. Do not include passwords, connection secrets, or customer data.
Related
- Container FAQ: what the container is for, and which features it includes and leaves out.
- Azure SQL Database free tier: validate in Azure before you deploy.