Azure SQL Developer Hub

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

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, user sa, 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 (or podman info, or wslc 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.