SQL Server Docker

Terminal

Se você está no Mac ou no Linux, provavelmente já tem um terminal bacana. No entanto, caso use o Windows, a recomendação é utilizar o Windows Terminal para executar os comandos deste artigo.

Para instalar e configurar, siga o artigo sobre o Windows Terminal, que mostra a instalação e as configurações que uso no dia a dia.

Docker instalado e em execução

Você também precisa do Docker instalado e rodando na sua máquina. Caso ainda não tenha feito essa instalação, o artigo Docker: instalação, configuração e primeiros passos mostra o processo completo.

Segundo a documentação da Microsoft, a imagem do SQL Server exige pelo menos 2 GB de memória disponível para o container. Por isso, confira as configurações de recursos do Docker Desktop se a sua máquina tiver pouca RAM.

WSL 2 no Windows

Caso esteja no Windows, instale e utilize o WSL, que é um subsistema Linux dentro do Windows. Assim, o Docker roda containers Linux com muito mais desempenho.

Esse processo precisa acontecer antes da instalação do Docker. Para isso, siga o passo a passo do artigo sobre o WSL.

Escolhendo uma versão específica

Caso queira baixar alguma versão específica, verifique as tags disponíveis no Docker Hub. Para usar uma tag, basta adicionar dois-pontos e o nome dela ao final da imagem.

Por exemplo, mcr.microsoft.com/mssql/server:2022-latest traz a versão 2022 mais recente. Dessa forma, você garante que todo o time usa a mesma versão do SQL Server no Docker, em vez de depender do que a tag latest aponta naquele dia.

Mac com chip M1

Na época em que este conteúdo foi escrito, o SQL Server não suportava os chips M1 da Apple. Desta forma, a alternativa era rodar o Azure SQL Edge, que oferecia uma imagem compatível com ARM:

docker pull mcr.microsoft.com/azure-sql-edge

Vale um aviso importante: a Microsoft aposentou o Azure SQL Edge em 30 de setembro de 2025. Por isso, a própria Microsoft orienta usar a imagem padrão do SQL Server com a emulação Rosetta ativada no Docker Desktop, que permite executar containers x64 em Macs com Apple Silicon.

Atenção com a senha do administrador

Mas atenção! A senha precisa de um nível mínimo de complexidade. Se você definir uma senha muito fácil, como 1q2w3e4r, o container vai finalizar sozinho.

Nesse caso, você verá o status Exited (1) e a seguinte mensagem no log do container:

ERROR: Unable to set system administrator password: Password validation failed. The password does not meet SQL Server password policy requirements because it is not complex enough. The password must be at least 8 characters long and contain characters from three of the following four sets: Uppercase letters, Lowercase letters, Base 10 digits, and Symbols..

Em resumo, a senha precisa ter pelo menos 8 caracteres e combinar três destes quatro grupos: letras maiúsculas, letras minúsculas, números e símbolos. Veja todos os detalhes na política de complexidade de senhas do SQL Server.

Para descobrir por que o container parou, use docker ps -a para ver o status e docker logs sqlserver para ler a mensagem completa. Assim, você identifica o problema em poucos segundos.

Windows com WSL 2

Caso esteja no Windows com WSL 2, informe o volume onde o container vai trabalhar, utilizando a flag -v ~/docker como mostrado abaixo:

docker run -v ~/docker --name sqlserver -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=1q2w3e4r@#$" -p 1433:1433 -d mcr.microsoft.com/mssql/server

Para parar a execução, você pode pressionar CTRL + C no terminal. Deste momento em diante, o container aparece na Dashboard do Docker de forma visual, onde você pode pará-lo ou iniciá-lo a qualquer momento.

Os mesmos requisitos de senha valem aqui. Portanto, se o container encerrar logo após subir, revise primeiro a complexidade da senha.

Mac M1 com Azure SQL Edge

Continuando a saga do M1, a execução com o Azure SQL Edge muda para o comando abaixo:

docker run -e "ACCEPT_EULA=1" -e "MSSQL_SA_PASSWORD=1q2w3e4r@#$" -e "MSSQL_PID=Developer" -e "MSSQL_USER=SA" -p 1433:1433 -d --name=sqlserver mcr.microsoft.com/azure-sql-edge

Aqui, o MSSQL_PID=Developer escolhe a edição de desenvolvimento, gratuita para uso fora de produção. Mais uma vez, a senha segue a mesma política de complexidade.

Como o Azure SQL Edge foi aposentado, considere migrar esse ambiente para a imagem mcr.microsoft.com/mssql/server com o Rosetta ativo. Desse modo, você mantém o mesmo comando usado no Windows e no Linux.

Executando consultas com sqlcmd

Você também pode rodar comandos T-SQL direto no container com o utilitário sqlcmd. Nas imagens mais recentes, ele fica na pasta mssql-tools18:

docker exec -it sqlserver /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "1q2w3e4r@#$" -No -Q "SELECT name FROM sys.databases"

A documentação explica que as versões 18 ou superiores do sqlcmd criptografam a conexão por padrão. Por isso, a opção -No informa que a criptografia é opcional nesse acesso local.

Esse comando lista os bancos existentes e serve como um teste rápido. Afinal, se ele responder, o SQL Server no Docker está pronto para receber conexões da sua aplicação.

Usando a connection string em uma aplicação .NET

Em um projeto ASP.NET Core, o caminho mais comum é guardar a conexão na seção ConnectionStrings do appsettings.json. Depois, o método GetConnectionString recupera o valor pelo nome:

var builder = WebApplication.CreateBuilder(args);

// Lê a conexão com o SQL Server que roda no container
var connectionString = builder.Configuration.GetConnectionString("DefaultConnection");

Como a senha do sa não deve ir para o repositório, prefira o Secret Manager do .NET durante o desenvolvimento. Assim, cada desenvolvedor mantém a própria senha do container fora do código.

Erro de pre-login handshake com SSL

Nas versões mais novas da imagem, no Windows, surge um problema de SSL com a mensagem a seguir:

A connection was successfully established with the server, but then an error occurred during the pre-login handshake. (provider: SSL Provider

Para resolver, primeiro execute os comandos abaixo, que limpam e confiam novamente nos certificados de desenvolvimento do .NET:

dotnet dev-certs https --clean
dotnet dev-certs https --trust

Feito isso, os certificados HTTPS do .NET estarão atualizados e funcionais. Em seguida, adicione os parâmetros Trusted_Connection e TrustServerCertificate na sua connection string, como mostrado abaixo:

Server=localhost,1433;Database=balta;User ID=sa;Password=1q2w3e4r@#$;Trusted_Connection=False; TrustServerCertificate=True;

O motivo é que o driver Microsoft.Data.SqlClient passou a criptografar a conexão por padrão a partir da versão 4.0. Como o SQL Server no Docker usa um certificado autoassinado, o cliente recusa a conexão até que você diga para confiar no certificado do servidor.

Porta 1433 já em uso

Outro erro comum é a mensagem bind: address already in use ao subir o container. Isso acontece quando já existe um SQL Server instalado localmente ou outro container usando a porta 1433.

Nesse caso, mapeie outra porta da sua máquina para a porta 1433 do container, como em -p 1400:1433. Depois, use localhost,1400 na connection string.

A mesma técnica permite rodar vários containers lado a lado, cada um em uma porta diferente da sua máquina. Por exemplo, você pode manter uma versão 2019 na porta 1401 e uma versão 2022 na porta 1402 para testar compatibilidade.