Introduction

Connecting from a Docker container to SQL Server is usually a networking problem, not a database-driver problem. The main question is where SQL Server is running: on the host machine, in another container, or on a remote server. Once that is clear, the connection string and network setup become straightforward.

First Decide Where SQL Server Lives

There are three common setups:

• SQL Server runs on the host machine
• SQL Server runs in another container
• SQL Server runs on a different server entirely

The hostname you use in the connection string depends on that choice.

If SQL Server Runs on the Host Machine

The most common beginner mistake is using localhost inside the container. From the container's perspective, localhost means the container itself, not your laptop or server host.

On Docker Desktop, a common host alias is:

host.docker.internal

Example SQL Server connection string:

Server=host.docker.internal,1433;Database=AppDb;User Id=sa;Password=YourStrong!Passw0rd;TrustServerCertificate=True;

That works only if SQL Server is configured to accept TCP connections and the host firewall allows access.

Example with Python and pyodbc

A minimal container-side Python example:

1import pyodbc
2
3conn = pyodbc.connect(
4    "DRIVER={ODBC Driver 18 for SQL Server};"
5    "SERVER=host.docker.internal,1433;"
6    "DATABASE=AppDb;"
7    "UID=sa;"
8    "PWD=YourStrong!Passw0rd;"
9    "Encrypt=no;"
10)
11
12cursor = conn.cursor()
13cursor.execute("SELECT @@VERSION")
14print(cursor.fetchone()[0])

This example assumes the SQL Server instance is reachable from the container and that the driver is installed inside the image.

If SQL Server Runs in Another Container

When both containers are on the same Docker network, use the other container's service name or container name as the server host.

Example Compose file:

1version: "3.9"
2services:
3  app:
4    build: .
5    depends_on:
6      - db
7  db:
8    image: mcr.microsoft.com/mssql/server:2022-latest
9    environment:
10      ACCEPT_EULA: "Y"
11      SA_PASSWORD: "YourStrong!Passw0rd"

Inside the app container, the server name becomes db:

Server=db,1433;Database=master;User Id=sa;Password=YourStrong!Passw0rd;TrustServerCertificate=True;

This is often simpler than crossing from container networking back to the host.

If SQL Server Is Remote

If the database is on another server, use its DNS name or IP just like any other remote service.

Example:

Server=sql-prod.example.com,1433;Database=AppDb;User Id=appuser;Password=secret;

At that point Docker is mostly irrelevant except that the container must be allowed to reach the destination network.

Make Sure SQL Server Is Listening on TCP/IP

Even with the right hostname, connection attempts fail if SQL Server is not configured for TCP/IP or if it listens on a different port.

Typical checks:

• SQL Server TCP/IP enabled
• port 1433 open if using the default instance configuration
• firewall rules allow inbound access
• authentication mode matches your credentials

Without those basics, the connection string can be perfectly written and still fail.

Test Connectivity Before Blaming the App

It is often faster to test raw network reachability first.

Inside the container:

nc -zv host.docker.internal 1433

If that fails, your application code is not the first thing to debug.

Use Environment Variables for Secrets

Do not hardcode database credentials in the image or source code.

Example:

1import os
2import pyodbc
3
4conn = pyodbc.connect(
5    f"DRIVER={{ODBC Driver 18 for SQL Server}};"
6    f"SERVER={os.environ['DB_HOST']},{os.environ.get('DB_PORT', '1433')};"
7    f"DATABASE={os.environ['DB_NAME']};"
8    f"UID={os.environ['DB_USER']};"
9    f"PWD={os.environ['DB_PASSWORD']};"
10    "Encrypt=no;"
11)

Then pass those variables with Docker Compose, Docker run, or your orchestration platform.

Common Pitfalls

• Using localhost from inside the container and accidentally targeting the container itself.
• Forgetting that SQL Server on the host still needs firewall and TCP/IP configuration.
• Mixing up the hostname strategy for host-based, container-based, and remote SQL Server setups.
• Debugging application code before verifying basic network connectivity to port 1433.
• Hardcoding credentials in the image instead of using environment-based configuration.

Summary

• The correct SQL Server hostname depends on where the database actually runs.
• 'localhost inside a container is not the Docker host.'
• Use host.docker.internal for host-based SQL Server on Docker Desktop, or service names for container-to-container networking.
• Verify TCP/IP, firewall, and port configuration before debugging code.
• Keep connection details configurable and keep secrets out of source code.