Setting up a local SQL Server database

Apple Silicon and other ARM machines

The images exist only for x86-64 (linux/amd64). Microsoft's Docker quickstart states that running them under emulation or translation, such as Rosetta 2 or QEMU, isn't tested or supported.

In practice, the image does run under Rosetta 2: the Docker steps in this guide were tested with SQL Server 2025 CU9 on an Apple Silicon Mac with OrbStack, which uses Rosetta for x86-64 containers. Docker Desktop can use Rosetta too, but only with the Apple Virtualization framework as its virtual machine manager. With Docker VMM, which doesn't support Rosetta, x86-64 emulation is slow. So in Docker Desktop, first choose Apple Virtualization framework under Settings > General > Virtual Machine Manager, then turn on Use Rosetta for x86_64/amd64 emulation on Apple Silicon in the settings. This guide wasn't tested with Docker Desktop.

Either way, treat emulation as a development convenience that Microsoft doesn't support. If you hit behavior you can't explain, reproduce it on an x86-64 machine before you debug your own code.

You may find older tutorials that recommend Azure SQL Edge as an ARM-native alternative. Microsoft retired Azure SQL Edge on September 30, 2025, so it's no longer an option.

Starting the container

Choose a password for the sa administrator account. It must follow SQL Server's password policy: at least eight characters, with characters from three of these four groups: uppercase letters, lowercase letters, digits and symbols. If the password doesn't meet the policy, SQL Server can't finish its setup and the container stops.

If you typed the password into the docker run command itself, it would end up in your shell's history. Instead, read it into an environment variable without echoing it, and let Docker pass that variable on. In Bash:

read -rs -p 'sa password: ' MSSQL_SA_PASSWORD && echo
export MSSQL_SA_PASSWORD
docker run --detach \
  --name mssql \
  --hostname mssql \
  --platform linux/amd64 \
  --env ACCEPT_EULA=Y \
  --env MSSQL_SA_PASSWORD \
  --publish 127.0.0.1:1433:1433 \
  --volume mssql-data:/var/opt/mssql \
  mcr.microsoft.com/mssql/server:2025-latest

In PowerShell, lines continue with a backtick instead of a backslash:

$env:MSSQL_SA_PASSWORD = [Net.NetworkCredential]::new('', (Read-Host -AsSecureString 'sa password')).Password
docker run --detach `
  --name mssql `
  --hostname mssql `
  --platform linux/amd64 `
  --env ACCEPT_EULA=Y `
  --env MSSQL_SA_PASSWORD `
  --publish 127.0.0.1:1433:1433 `
  --volume mssql-data:/var/opt/mssql `
  mcr.microsoft.com/mssql/server:2025-latest

Alternatively, write MSSQL_SA_PASSWORD=<sa-password> into a file that only you can read, and replace --env MSSQL_SA_PASSWORD with --env-file <file>.

Here's what the options do:

• --platform linux/amd64 asks for the x86-64 image explicitly. On an Intel or AMD machine, it changes nothing. On an ARM machine, it states that you want the image to run under emulation, so Docker doesn't warn that the image's platform doesn't match your machine's.
• ACCEPT_EULA=Y accepts the SQL Server license terms, which the image requires.
• --env MSSQL_SA_PASSWORD, without a value, copies the variable from your shell into the container, where SQL Server uses it as the sa password. Older guides use SA_PASSWORD, which is deprecated.
• --publish 127.0.0.1:1433:1433 makes SQL Server reachable on port 1433 of your machine, but only from the machine itself. With --publish 1433:1433, Docker would listen on every network interface, and anyone on the same network, say, a café's Wi-Fi, could try passwords against sa.
• --volume mssql-data:/var/opt/mssql stores the databases in a named Docker volume. The data survives when you remove and re-create the container, for example to update to a newer image.
• --name gives the container the name that you use in other docker commands. --hostname sets the host name inside the container, which SQL Server reports as its server name, for example in @@SERVERNAME.

The image contains the Enterprise Developer edition unless you choose another one. For the Standard Developer edition, add --env 'MSSQL_PID=StandardDeveloper'; Microsoft's environment variables reference lists all values.

The 2025-latest tag always points to the newest cumulative update. If everyone on your team should run the same build (see syncing development databases between team members), use a tag that names the update, such as 2025-CU9-ubuntu-24.04, from the list of tags. For SQL Server 2022, use 2022-latest or one of its update tags.

SQL Server needs a few seconds to start. It's ready when its log contains this line:

docker logs mssql | grep "ready for client connections"

In PowerShell, use Select-String instead of grep:

docker logs mssql | Select-String "ready for client connections"

2026-09-30 03:37:41.88 spid57s     SQL Server is now ready for client connections. This is an informational message; no user action is required.

Even after this line appears, a login can fail for a few more seconds while SQL Server finishes starting up. If that happens, try again. If the container isn't running at all, docker logs mssql shows why, for example that the password doesn't meet the policy.

The other docker commands in this guide work the same way in Bash and PowerShell.

Connecting with sqlcmd inside the container

The image includes the sqlcmd client that's based on the ODBC driver, so you don't have to install anything to connect. Open a SQL shell as sa:

docker exec -it mssql /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -C

sqlcmd asks for the password and then shows its 1> prompt. Current images install the tools in /opt/mssql-tools18/bin. The /opt/mssql-tools/bin path from older tutorials doesn't exist in the SQL Server 2025 image.

You'll create a database and a login in the next section. First, it's worth understanding the -C option.

Why sqlcmd needs -C: encryption and certificates

Version 18 of Microsoft's ODBC driver, and the sqlcmd built on it, encrypts connections by default and checks that the server's TLS certificate is trusted, just as a browser does for a website. A fresh SQL Server generates a self-signed certificate at startup, which no client trusts. Without -C, the connection fails:

Sqlcmd: Error: Microsoft ODBC Driver 18 for SQL Server : SSL Provider: [error:0A000086:SSL routines::certificate verify failed:self-signed certificate].
Sqlcmd: Error: Microsoft ODBC Driver 18 for SQL Server : Client unable to establish connection. For solutions related to encryption errors, see https://go.microsoft.com/fwlink/?linkid=2226722.

You have three ways to deal with this:

• -C (trust the server certificate) keeps the connection encrypted but skips the check of who's on the other end. An attacker who can intercept the traffic could pose as the server. On a connection to localhost, that would require access to your machine, so for a local development server this is a reasonable trade-off.
• -No makes encryption optional. SQL Server always encrypts the login packet, which contains the password, but your queries and their results then travel unencrypted. Microsoft's quickstarts suggest -No, but when -C works, you gain nothing by dropping encryption.
• A certificate that your clients trust is the right fix as soon as the connection crosses a network. See Microsoft's guides for Linux and Windows.

To check whether your current connection is encrypted, run this query as sa or another administrator. Logins without the VIEW SERVER PERFORMANCE STATE permission, like the application login you'll create later, can't read this view:

SELECT encrypt_option FROM sys.dm_exec_connections WHERE session_id = @@SPID;
GO

encrypt_option
----------------------------------------
TRUE

(1 rows affected)

With -No, the same query returns FALSE.

Your application's database driver faces the same choice, usually through a trustServerCertificate or TrustServerCertificate connection string option. Keep that option in your local configuration only.

Connecting from your machine with the Go-based sqlcmd

To connect from outside the container, for example from your editor's terminal, you can install the newer, Go-based sqlcmd (go-sqlcmd). It's a single program for Windows, macOS and Linux: install it with winget install sqlcmd on Windows, brew install sqlcmd on macOS, or download a release from GitHub. Microsoft's installation guide describes these options and the ODBC-based alternative.

Its encryption defaults differ from the ODBC-based sqlcmd: in version 1.10.0, a connection without options only encrypts the login, not the queries and results, and -C alone doesn't change that. To get a fully encrypted connection to the local server, request encryption with -N true and trust the self-signed certificate with -C:

sqlcmd -S localhost -U sa -N true -C

go-sqlcmd can also create a SQL Server container for you with sqlcmd create mssql --accept-eula. It generates a login named after your operating system user, disables sa, and stores the credentials in ~/.sqlcmd/sqlconfig. This guide uses docker run instead, for two reasons: in version 1.10.0, sqlcmd create mssql publishes the port on all network interfaces with no option to restrict it to localhost, and it can't select an edition.

Ubuntu 24.04 and 22.04

Add Microsoft's signing key and the SQL Server 2025 repository, then install the mssql-server package. On Ubuntu 24.04:

curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | sudo gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg
curl -fsSL https://packages.microsoft.com/config/ubuntu/24.04/mssql-server-2025.list | sudo tee /etc/apt/sources.list.d/mssql-server-2025.list
sudo apt-get update
sudo apt-get install -y mssql-server

The repository file for Ubuntu 22.04 doesn't name a key file, so apt-get update would fail with NO_PUBKEY if you only stored the key in /usr/share/keyrings. Add the key to APT's trusted keys instead:

curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | sudo tee /etc/apt/trusted.gpg.d/microsoft.asc > /dev/null
curl -fsSL https://packages.microsoft.com/config/ubuntu/22.04/mssql-server-2025.list | sudo tee /etc/apt/sources.list.d/mssql-server-2025.list
sudo apt-get update
sudo apt-get install -y mssql-server

Red Hat Enterprise Linux 9 and 10

Download the repository file for your RHEL release, here RHEL 9 (use rhel/10 in the URL for RHEL 10), and install the package:

sudo curl -o /etc/yum.repos.d/mssql-server.repo https://packages.microsoft.com/config/rhel/9/mssql-server-2025.repo
sudo yum install -y mssql-server

Configuring the server

The package installs SQL Server but doesn't configure it. Run mssql-conf setup, which asks you to choose an edition, to accept the license terms and to set the sa password:

sudo /opt/mssql/bin/mssql-conf setup

It starts with the choice of edition:

Choose an edition of SQL Server:
  1) Evaluation (free, no production use rights, 180-day limit)
  2) Enterprise Developer (free, no production use rights)
  3) Standard Developer (free, no production use rights)
  4) Express (free)
  5) Standard (PAID)
  6) Enterprise (PAID) - CPU core utilization restricted to 20 physical/40 hyperthreaded
  7) Enterprise Core (PAID) - CPU core utilization up to Operating System Maximum
  8) I bought a license through a retail sales channel and have a product key to enter.
  9) Standard (Billed through Azure) - Use pay-as-you-go billing through Azure.
  10) Enterprise Core (Billed through Azure) - Use pay-as-you-go billing through Azure.

Choose one of the free editions: a Developer edition for development, or Express. When the setup has finished, check that the service is running:

systemctl status mssql-server --no-pager

Microsoft's quickstarts also open port 1433 in the firewall to allow remote connections. For a server that only you use on this machine, skip that step.

Installing the command-line tools

The server package doesn't include sqlcmd. You can install the Go-based sqlcmd from its GitHub releases, or the ODBC-based tools from Microsoft's repository. On Ubuntu 24.04:

curl -sSL -O https://packages.microsoft.com/config/ubuntu/24.04/packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
sudo apt-get update
sudo apt-get install mssql-tools18 unixodbc-dev

On Ubuntu 22.04, which already trusts the key from the previous step:

curl -fsSL https://packages.microsoft.com/config/ubuntu/22.04/prod.list | sudo tee /etc/apt/sources.list.d/mssql-release.list
sudo apt-get update
sudo apt-get install mssql-tools18 unixodbc-dev

On RHEL 9 and 10:

curl https://packages.microsoft.com/config/rhel/9/prod.repo | sudo tee /etc/yum.repos.d/mssql-release.repo
sudo yum install -y mssql-tools18 unixODBC-devel

The packages ask you to accept the license terms of the ODBC driver and the tools. The tools are installed in /opt/mssql-tools18/bin, which isn't on your PATH. To add it for Bash:

echo 'export PATH="$PATH:/opt/mssql-tools18/bin"' >> ~/.bashrc
source ~/.bashrc

Then connect as sa. The -C option has the same meaning as in the container:

sqlcmd -S localhost -U sa -C

Replacing sa with your own administrator login

Everyone knows the name sa, so it's the first login that attackers try. Microsoft recommends that you create your own administrator login and then disable sa. Connect as sa again, create the login and add it to the sysadmin role, replacing <admin-password> with a password that meets the policy:

CREATE LOGIN dev_admin WITH PASSWORD = '<admin-password>';
ALTER SERVER ROLE sysadmin ADD MEMBER dev_admin;
GO

Type EXIT, connect as dev_admin to make sure that the new login works, and disable sa:

docker exec -it mssql /opt/mssql-tools18/bin/sqlcmd -S localhost -U dev_admin -C

ALTER LOGIN sa DISABLE;
GO

From now on, logging in as sa fails:

Sqlcmd: Error: Microsoft ODBC Driver 18 for SQL Server : Login failed for user 'sa'. Reason: The account is disabled..

On Windows, if you chose Windows Authentication during setup, sa is already disabled.

Two more things to know about the sa password in a container:

• The MSSQL_SA_PASSWORD value stays in the container's configuration, where anyone who can run docker inspect on your machine can read it. Disabling sa makes that value useless. If you keep sa, change its password with ALTER LOGIN sa WITH PASSWORD = '<new-password>';.
• SQL Server uses MSSQL_SA_PASSWORD only when it sets up an empty data volume. If you re-create the container on an existing volume with a different value, the old password stays in effect.