Introduction

Connecting ASP.NET Core to SQL Server on Docker Desktop for Mac is mostly a networking and connection-string problem. The exact hostname depends on where the ASP.NET Core app is running: if the app runs on the Mac host, connect to localhost; if the app runs in another container on the same Docker network, connect to the SQL Server container by service name.

Run SQL Server in Docker

Start with a SQL Server container that publishes port 1433.

1docker run -e ACCEPT_EULA=Y \
2  -e MSSQL_SA_PASSWORD='YourStrong!Passw0rd' \
3  -p 1433:1433 \
4  --name sqlserver \
5  -d mcr.microsoft.com/mssql/server:2022-latest

Then confirm the container is actually running:

docker ps
docker logs sqlserver

Do not move on to application debugging until the container is healthy. Many "connection" problems are really startup failures caused by a weak password, bad image pull, or insufficient resources.

Use the Right Connection String

If the ASP.NET Core app runs directly on your Mac, the SQL Server container is reachable through the published port on localhost.

1{
2  "ConnectionStrings": {
3    "DefaultConnection": "Server=localhost,1433;Database=AppDb;User Id=sa;Password=YourStrong!Passw0rd;TrustServerCertificate=True;Encrypt=False"
4  }
5}

In the application:

1using Microsoft.EntityFrameworkCore;
2
3var builder = WebApplication.CreateBuilder(args);
4
5builder.Services.AddDbContext<AppDbContext>(options =>
6    options.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection")));
7
8var app = builder.Build();
9app.MapGet("/", () => "API is running");
10app.Run();

On developer machines, TrustServerCertificate=True and Encrypt=False are common shortcuts for local container use. In production, use proper TLS settings instead of copying this string blindly.

Use the Container Name When Both Services Are in Docker

If the ASP.NET Core app also runs in Docker, localhost points to the app container itself, not to the SQL Server container. In that case, use Docker networking and the SQL service name.

A minimal docker-compose.yml pattern looks like this:

1services:
2  api:
3    build: .
4    depends_on:
5      - sqlserver
6    environment:
7      ConnectionStrings__DefaultConnection: "Server=sqlserver,1433;Database=AppDb;User Id=sa;Password=YourStrong!Passw0rd;TrustServerCertificate=True;Encrypt=False"
8
9  sqlserver:
10    image: mcr.microsoft.com/mssql/server:2022-latest
11    environment:
12      ACCEPT_EULA: "Y"
13      MSSQL_SA_PASSWORD: "YourStrong!Passw0rd"
14    ports:
15      - "1433:1433"

Here the hostname is sqlserver because Docker Compose creates a shared network and resolves service names automatically.

Verify the Database Layer Separately

Before assuming the .NET app is misconfigured, test SQL Server itself. If you can connect with another tool, the problem is probably in the app configuration rather than the container.

Check these basics:

• container is running
• port 1433 is published
• the password matches
• the target database exists
• the app uses the right hostname for its runtime context

If you are using Entity Framework migrations, run them only after connectivity is confirmed.

Handle Readiness and Startup Order

A working connection string is still not enough if the ASP.NET Core app reaches SQL Server before the database engine is ready to accept logins. This happens often in containerized local setups because the app process can start faster than SQL Server finishes initialization.

Practical mitigations include:

• lightweight retry logic around first connection attempts
• running migrations after a health check instead of immediately at process start
• remembering that depends_on in Compose controls startup order but not database readiness

This is especially important when both services run in Docker, because many "cannot open server" failures are really timing problems rather than permanent network misconfiguration.

Common Pitfalls

• Using localhost from inside the app container instead of the SQL Server service name.
• Assuming the SQL container is healthy without checking docker logs.
• Copying a connection string that uses the wrong password or the wrong port mapping.
• Forgetting that Docker Desktop on Mac still needs the published host port when the app runs outside Docker.
• Treating local development TLS shortcuts as production-safe database settings.

Summary

• On Mac, ASP.NET Core connects to a SQL Server Docker container through localhost only when the app runs on the host.
• If both services run in Docker, use the SQL container or compose service name instead.
• Validate the SQL container health before debugging the app.
• Keep the connection string consistent with the actual network topology.
• Separate local-development connection settings from production-grade security settings.