Desarrollo de contenedores y local con mssql-python

Esta guía cubre la configuración del entorno para desarrolladores de Python que trabajan con el mssql-python controlador en Windows, Linux, macOS, contenedores Docker, devcontainers y pipelines CI.

Prerequisites

• Python 3.10 o posterior.
• Docker Desktop (para desarrollo basado en contenedores).
• Un host compatible con x64 (máquina virtual Intel, AMD o x64) para contenedores Linux de SQL Server. Los contenedores de SQL Server Linux no soportan hosts ARM64.

SQL Server local con sqlcmd (recomendado)

La utilidad go-sqlcmd puede crear un contenedor SQL Server en un solo comando. Controla automáticamente la extracción de imágenes de Docker, la generación de contraseñas, la asignación de puertos y el contexto de conexión:

sqlcmd create mssql --accept-eula

Para crear un contenedor con una base de datos de ejemplo ya adjunta:

sqlcmd create mssql --accept-eula --using https://aka.ms/AdventureWorksLT.bak

Después de la creación, sqlcmd almacena el contexto de conexión para que pueda consultar inmediatamente:

sqlcmd query "SELECT @@VERSION"

Crea un inicio de sesión de aplicación una vez y luego úsalo en tu código Python:

sqlcmd query --database <database> "CREATE LOGIN <app-login> WITH PASSWORD = '<password>';"
sqlcmd query --database <database> "CREATE USER <app-login> FOR LOGIN <app-login>;"
sqlcmd query --database <database> "ALTER ROLE db_datareader ADD MEMBER <app-login>;"
sqlcmd query --database <database> "ALTER ROLE db_datawriter ADD MEMBER <app-login>;"

Sustituye <database>, <app-login>, y <password> por valores de tu entorno.

Conéctese desde Python usando los datos de conexión que sqlcmd imprimió durante su creación. Use sqlcmd config view para recuperarlos más adelante:

import mssql_python

conn = mssql_python.connect(
    server="localhost,1433",
    uid="<app login>",
    pwd="<password>",
    encrypt="yes",
    trust_server_certificate="yes"
)

cursor = conn.cursor()
cursor.execute("SELECT @@VERSION")
print(cursor.fetchval())
conn.close()

Cuando haya terminado, detenga o elimine el contenedor:

sqlcmd stop
sqlcmd delete

SQL Server local desde VS Code

La extensión SQL Server para VS Code (ms-mssql.mssql) puede crear contenedores locales de SQL Server directamente desde el editor:

1. Abra la vista SQL Server en la barra de actividades.
2. Seleccione Agregar conexión>Crear SQL Server local (o use la paleta de comandos: MS SQL: Crear SQL Server local).
3. Elija la versión SQL Server y acepte el CLUF.
4. La extensión extrae la imagen del contenedor, genera una contraseña y agrega automáticamente un perfil de conexión.

Una vez que el contenedor está en ejecución, puedes navegar por bases de datos, hacer consultas y gestionar objetos directamente en VS Code antes de cambiar a código Python.

SQL Server local con Docker

Si prefiere administrar contenedores directamente, la imagen de contenedor de SQL Server oficial funciona con dos variables de entorno:

docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=YourStr0ngP@ssword" \
  -p 1433:1433 --name sql1 \
  -d mcr.microsoft.com/mssql/server:2022-latest

Espera unos segundos y luego conecta desde Python:

import mssql_python

conn = mssql_python.connect(
    server="localhost,1433",
    uid="<app login>",
    pwd="<password>",
    encrypt="yes",
    trust_server_certificate="yes"
)

cursor = conn.cursor()
cursor.execute("SELECT @@VERSION")
print(cursor.fetchval())
conn.close()

Para cargar la base de datos de ejemplo de AdventureWorks en el contenedor:

# Download AdventureWorks backup
curl -L -o AdventureWorks2022.bak \
  "https://github.com/Microsoft/sql-server-samples/releases/download/adventureworks/AdventureWorks2022.bak"

# Copy into container
docker cp AdventureWorks2022.bak sql1:/var/opt/mssql/backup/

# Restore
docker exec sql1 /opt/mssql-tools18/bin/sqlcmd \
  -S localhost -U sa -P "YourStr0ngP@ssword" -C \
  -Q "RESTORE DATABASE AdventureWorks2022 FROM DISK='/var/opt/mssql/backup/AdventureWorks2022.bak' WITH MOVE 'AdventureWorks2022' TO '/var/opt/mssql/data/AdventureWorks2022.mdf', MOVE 'AdventureWorks2022_log' TO '/var/opt/mssql/data/AdventureWorks2022_log.ldf'"

Dockerfile para aplicaciones Python

Mantén la referencia de la imagen base de Python en un solo lugar para que las compilaciones locales, devcontainers y pipelines de CI no se desvíen. Para la experimentación local, una etiqueta amplia y soportada como python:3-slim funciona bien. Para devcontainers compartidos, CI y producción, sustituye esa etiqueta por una imagen aprobada y fijada en resumen de la lista de permisos de tu organización.

Crea un archivo Docker mínimo para una aplicación Python que se conecte a Microsoft SQL:

ARG PYTHON_BASE=python:3-slim
FROM ${PYTHON_BASE}

# Install system libraries required by mssql-python on Linux
RUN apt-get update && \
    apt-get install -y --no-install-recommends libltdl7 libkrb5-3 libgssapi-krb5-2 && \
    rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .
CMD ["python", "app.py"]

Su requirements.txt:

mssql-python>=1.11.0

Compilación y ejecución:

docker build -t myapp .
docker run -e SQL_SERVER=host.docker.internal,1433 myapp

En entornos compartidos, pasa una referencia a una imagen base inmutable aprobada con --build-arg PYTHON_BASE=python:3-slim@sha256:<approved-digest>.

Alpine Linux

Alpine usa musl en lugar de glibc. Instale los paquetes necesarios:

ARG PYTHON_BASE=python:3-alpine
FROM ${PYTHON_BASE}

RUN apk add --no-cache libltdl krb5-libs

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .
CMD ["python", "app.py"]

Configuración del devcontainer

Reutiliza el mismo archivo Dockerfile con el que compila tu aplicación. Este enfoque mantiene el devcontainer alineado con tu imagen de ejecución y evita dispersar los pines de la versión de Python entre varios archivos.

Crea un .devcontainer/devcontainer.json para VS Code:

{
    "name": "Python + SQL Server",
    "build": {
        "dockerfile": "../Dockerfile",
        "context": ".."
    },
    "features": {
        "ghcr.io/devcontainers/features/docker-in-docker:2": {}
    },
    "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
    "postCreateCommand": "pip install --no-cache-dir -r requirements.txt",
    "forwardPorts": [1433],
    "customizations": {
        "vscode": {
            "extensions": [
                "ms-python.python",
                "ms-mssql.mssql"
            ]
        }
    }
}

Para incluir SQL Server como servicio en el devcontainer, use Docker Compose:

.devcontainer/docker-compose.yml:

services:
  app:
    build:
      context: ..
      dockerfile: Dockerfile
    volumes:
      - ..:/workspace:cached
    command: sleep infinity
    depends_on:
      - db

  db:
    image: mcr.microsoft.com/mssql/server:2022-latest
    environment:
      ACCEPT_EULA: "Y"
      MSSQL_SA_PASSWORD: "YourStr0ngP@ssword"
    ports:
      - "1433:1433"

.devcontainer/devcontainer.json (Versión de Compose):

{
    "name": "Python + SQL Server",
    "dockerComposeFile": "docker-compose.yml",
    "service": "app",
    "workspaceFolder": "/workspace",
    "postCreateCommand": "pip install -r requirements.txt",
    "customizations": {
        "vscode": {
            "extensions": [
                "ms-python.python",
                "ms-mssql.mssql"
            ]
        }
    }
}

Para espacios de trabajo compartidos, fija la imagen del servicio de SQL Server a un resumen aprobado en lugar de depender de una etiqueta flotante. Carga MSSQL_SA_PASSWORD desde un archivo local .env o desde un almacén de secretos de la plataforma, en lugar de incorporarlo al control de código fuente.

Conéctate al servicio SQL Server por tu nombre:

conn = mssql_python.connect(
    server="db,1433",
    uid="<app login>",
    pwd="<password>",
    encrypt="yes",
    trust_server_certificate="yes"
)

Dependencias específicas de la plataforma

El mssql-python controlador agrupa sus componentes nativos. No necesitas instalar un gestor externo de drivers ODBC. Sin embargo, el controlador requiere un pequeño conjunto de librerías de sistema en Linux y macOS.

Para macOS, si encuentras errores SSL, configura las banderas del enlazador:

export LDFLAGS="-L/opt/homebrew/opt/openssl/lib"
export CPPFLAGS="-I/opt/homebrew/opt/openssl/include"

Para las instrucciones completas de instalación, consulta Instalar mssql-python.

Autenticación para el desarrollo

Desarrollo local con Azure SQL

Úsalo ActiveDirectoryDefault para autenticación sin contraseña. Esta opción se encadena automáticamente a través de CLI de Azure, Visual Studio, variables de entorno e identidad gestionada:

conn = mssql_python.connect(
    server="<server>.database.windows.net",
    database="<database>",
    authentication="ActiveDirectoryDefault",
    encrypt="yes"
)

Asegúrate de iniciar sesión usando CLI de Azure:

az login

Desarrollo local frente a SQL Server

Usa autenticación SQL con una instancia local.

conn = mssql_python.connect(
    server="localhost,1433",
    uid="<app login>",
    pwd="<password>",
    encrypt="yes",
    trust_server_certificate="yes"
)

Desarrollo de contenedores con Azure SQL

Para contenedores que se ejecutan en Azure (App Service, Container Apps, AKS), usa la identidad gestionada.

conn = mssql_python.connect(
    server="<server>.database.windows.net",
    database="<database>",
    authentication="ActiveDirectoryMSI",
    encrypt="yes"
)

Para contenedores que se ejecutan localmente y necesitan conectarse a Azure SQL, asegúrate de que el contenedor tenga un código fuente de credenciales que ActiveDirectoryDefault pueda usar. Las opciones más fiables son:

• Instala CLI de Azure en el contenedor y inicia sesión allí. Monta ~/.azure desde el host solo si la imagen del contenedor ya incluye CLI de Azure y tienes intención de reutilizar esa caché de credenciales.
• Proporcionar credenciales principales de servicio mediante variables de entorno como AZURE_CLIENT_ID, AZURE_TENANT_ID, y AZURE_CLIENT_SECRET.

Luego, utiliza ActiveDirectoryDefault en tu código de conexión.

Endpoints SQL de Microsoft compatibles

El mssql-python controlador se conecta a todos los endpoints de Microsoft SQL:

Consulte Autenticación Microsoft Entra para los siete modos de autenticación y Ciclo de vida de Soporte para la matriz completa de compatibilidad.

Configuración de canalización de CI

Acciones de GitHub

Mantén el runtime de Python en una sola variable para que puedas revisarlo y actualizarlo en un solo lugar. Úsalo 3.x para canalizaciones de validación rápidas, o retitúelo por una versión exacta aprobada por la organización para canalizaciones de lanzamiento.

name: Test with SQL Server
on: [push, pull_request]

env:
  PYTHON_VERSION: "3.x"

jobs:
  test:
    runs-on: ubuntu-latest

    services:
      sqlserver:
        image: mcr.microsoft.com/mssql/server:2022-latest
        env:
          ACCEPT_EULA: Y
          MSSQL_SA_PASSWORD: YourStr0ngP@ssword
        ports:
          - 1433:1433
        options: >-
          --health-cmd "/opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P YourStr0ngP@ssword -C -Q 'SELECT 1'"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: ${{ env.PYTHON_VERSION }}
          check-latest: true

      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y libltdl7 libkrb5-3 libgssapi-krb5-2
          pip install -r requirements.txt

      - name: Run tests
        env:
          SQL_SERVER: localhost,1433
          SQL_UID: sa
          SQL_PWD: YourStr0ngP@ssword
        run: pytest

Para canalizaciones compartidas, sustituye la contraseña provisional en línea por un secreto cifrado, fija la imagen del servicio SQL Server en un resumen y mantén la versión de Python en una variable gestionada por la organización o en una entrada de flujo de trabajo reutilizable.

Azure Pipelines

Utiliza un recurso contenedor para ejecutar SQL Server como servicio junto con tu trabajo de prueba:

trigger:
  - main

variables:
  python.version: "3.x"

resources:
  containers:
    - container: sqlserver
      image: mcr.microsoft.com/mssql/server:2022-latest
      env:
        ACCEPT_EULA: Y
        MSSQL_SA_PASSWORD: YourStr0ngP@ssword
      ports:
        - 1433:1433

pool:
  vmImage: ubuntu-latest

services:
  sqlserver: sqlserver

steps:
  - task: UsePythonVersion@0
    inputs:
      versionSpec: "$(python.version)"

  - script: |
      sudo apt-get update
      sudo apt-get install -y libltdl7 libkrb5-3 libgssapi-krb5-2
      pip install -r requirements.txt
    displayName: Install dependencies

  - script: pytest
    displayName: Run tests
    env:
      SQL_SERVER: localhost,1433
      SQL_UID: sa
      SQL_PWD: YourStr0ngP@ssword

Como con Acciones de GitHub, sustituye la contraseña provisional en línea por una variable secreta antes de usar este patrón fuera de una pipeline de demostración desechable.

Seguridad y secretos

No codifiques contraseñas de base de datos ni cadenas de conexión en código fuente ni en Dockerfiles. Utiliza en su lugar variables de entorno y gestión de secretos.

Variables ambientales para el desarrollo local

Almacena las credenciales en variables de entorno o en un archivo .env que esté excluido del control de versiones:

# .env (add to .gitignore)
SQL_SERVER=localhost,1433
SQL_UID=sa
SQL_PWD=YourStr0ngP@ssword

import os
import mssql_python

conn = mssql_python.connect(
    server=os.environ["SQL_SERVER"],
    uid=os.environ["SQL_UID"],
    pwd=os.environ["SQL_PWD"],
    encrypt="yes",
    trust_server_certificate="yes"
)

Para Docker Compose, consulta un archivo .env:

services:
  app:
    build: .
    env_file: .env

Secretos CI/CD

En las canalizaciones de CI, utiliza el almacenamiento secreto de la plataforma en lugar de variables de entorno en texto plano:

• Acciones de GitHub: Utiliza secretos cifrados y refírelos como ${{ secrets.SQL_PWD }}.
• Azure Pipelines: Utiliza variables secretas y refírtalas como $(SQL_PWD).

Higiene de la cadena de suministro de contenedores

Utiliza estas prácticas para entornos de desarrollo compartidos y CI:

• Mantén referencias de imagen en un solo lugar, como un Docker ARG, una compilación de devcontainer o una variable de pipeline.
• Vincula las imágenes de contenedor compartidas a dígests inmutables en lugar de a etiquetas variables.
• Revisa y actualiza los digestes fijados mediante un proceso de actualización aprobado como Dependabot, Renovate o un flujo de trabajo interno de promoción de imágenes.
• Compromete un archivo de bloqueo de dependencia como uv.lock, o utiliza archivos de requisitos hashados para instalaciones reproducibles en Python.
• Prefiere imágenes base aprobadas por la organización y réplicas internas del registro cuando la plataforma las ofrezca.

Producción: autenticación sin contraseña

Para cargas de trabajo de producción contra Azure SQL, utiliza autenticación Microsoft Entra con identidad gestionada. Este enfoque elimina por completo las contraseñas:

conn = mssql_python.connect(
    server="<server>.database.windows.net",
    database="<database>",
    authentication="ActiveDirectoryMSI",
    encrypt="yes"
)

Para aplicaciones que necesitan almacenar secretos como contraseñas de autenticación SQL, usa Azure Key Vault y recupéralos en tiempo de ejecución.

Gestión de dependencias con uv

UV es un instalador rápido de paquetes Python que funciona bien en compilaciones de CI y contenedores:

ARG PYTHON_BASE=python:3-slim
FROM ${PYTHON_BASE}

RUN apt-get update && \
    apt-get install -y --no-install-recommends libltdl7 libkrb5-3 libgssapi-krb5-2 && \
    rm -rf /var/lib/apt/lists/*

# Install uv. In shared builds, pin the source image to an approved digest.
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev

COPY . .
CMD ["uv", "run", "python", "app.py"]

En CI:

pip install uv
uv sync
uv run pytest

Solución de problemas comunes de contenedor

Contenido relacionado

• Instalar mssql-python
• Ciclo de vida de soporte técnico
• Cadenas de conexión
• Autenticación de Microsoft Entra
• Inicio rápido: Despliegues repetibles