Desarrollo local y en contenedores con mssql-django

En esta guía se describe la configuración del entorno para los desarrolladores de Django que trabajan con el mssql-django back-end en Windows, Linux, macOS, contenedores de Docker, devcontainers y canalizaciones de CI.

Prerequisites

• Python 3.10 a 3.14. Django 6.0 y 6.1 requieren versiones de Python 3.12 y posteriores.
• Docker Desktop (para el desarrollo basado en contenedores)
• Microsoft ODBC Driver 17 o 18 para SQL Server cuando usas la ruta predeterminada de pyodbc. Consulte Descarga del controlador ODBC para SQL Server.
• Una imagen base compatible con el paquete requeridomssql-python: Windows x64, Windows ARM64 con Python 3.11 y versiones posteriores, macOS 15 y versiones posteriores, o Linux x64/ARM64 con glibc 2.28 y versiones posteriores o musl 1.2 y versiones posteriores. SUSE Linux en ARM64 no es compatible.

La ruta mssql-python no requiere un controlador Microsoft ODBC separado para una instalación de SQL Server. Sigue necesitando el runtime de unixODBC, porque el backend importa pyodbc cuando Django lo carga. Para más información, consulte Seleccionar el controlador de base de datos para mssql-django.

SQL Server local con sqlcmd (recomendado)

La utilidad sqlcmd (Go) puede crear un contenedor de 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"

Configura Django para conectarse con los datos de conexión que sqlcmd mostró al crearse. Use sqlcmd config view para recuperarlos más adelante:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "master",
        "USER": "sa",
        "PASSWORD": "<password from sqlcmd output>",
        "HOST": "localhost",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "TrustServerCertificate=yes",
        },
    },
}

Cuando haya terminado, detenga o elimine el contenedor:

sqlcmd stop
sqlcmd delete

SQL Server local en Visual Studio Code

La extensión MSSQL para Visual Studio Code puede crear contenedores de SQL Server locales 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 se ejecuta el contenedor, puede examinar bases de datos, ejecutar consultas y administrar objetos en Visual Studio Code antes de cambiar al código de Django.

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=<strong_password>" \
  -p 1433:1433 --name sql1 \
  -d mcr.microsoft.com/mssql/server:2022-latest

Espere unos segundos para que se inicie el contenedor y, a continuación, ejecute migraciones:

python manage.py migrate
python manage.py createsuperuser

Dockerfile para aplicaciones de Django

Crea un archivo Docker mínimo para una aplicación Django que se conecte a SQL Server por la ruta pyodbc predeterminada. El controlador ODBC es la dependencia de clave que no viene con la imagen base de Python:

FROM python:3.12-slim

# Install ODBC Driver 18 for SQL Server
RUN apt-get update && \
    apt-get install -y --no-install-recommends curl gnupg2 && \
    curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | \
        gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg && \
    echo "deb [signed-by=/usr/share/keyrings/microsoft-prod.gpg] https://packages.microsoft.com/debian/12/prod bookworm main" > \
        /etc/apt/sources.list.d/mssql-release.list && \
    apt-get update && \
    ACCEPT_EULA=Y apt-get install -y --no-install-recommends msodbcsql18 unixodbc-dev && \
    apt-get purge -y curl gnupg2 && \
    rm -rf /var/lib/apt/lists/*

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

COPY . .

# Collect static files
RUN python manage.py collectstatic --noinput

EXPOSE 8000
CMD ["gunicorn", "myproject.wsgi:application", "--bind", "0.0.0.0:8000"]

Su requirements.txt:

django>=5.2,<6.2
mssql-django>=2.0
gunicorn>=22.0

Si tu alias de base de datos usa la ruta del controlador mssql-python con "python_driver": "mssql_python", aún necesitas unixODBC, porque el backend importa pyodbc cuando Django lo carga. No necesitas el repositorio de paquetes de Microsoft ni msodbcsql18, así que el bloque de instalación ODBC se reduce a:

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

Compilación y ejecución:

docker build -t mydjango .
docker run -e "DB_HOST=host.docker.internal" -e "DB_NAME=<database>" \
  -e "DB_USER=<user_id>" -e "DB_PASSWORD=<password>" \
  -p 8000:8000 mydjango

Configuración del devcontainer

Crea un .devcontainer/devcontainer.json para Visual Studio Code que incluya SQL Server como servicio sidecar:

{
    "name": "Django + SQL Server",
    "image": "mcr.microsoft.com/devcontainers/python:3",
    "features": {
        "ghcr.io/devcontainers/features/docker-in-docker:2": {}
    },
    "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
    "postCreateCommand": "bash .devcontainer/post-create.sh",
    "forwardPorts": [1433, 8000],
    "customizations": {
        "vscode": {
            "extensions": [
                "ms-python.python",
                "ms-mssql.mssql"
            ]
        }
    }
}

Este devcontainer instala el controlador ODBC para la ruta pyodbc por defecto y las dependencias de Python, pero no incluye una instancia de SQL Server. Inicie uno dentro del devcontainer mediante sqlcmd create mssql --accept-eula (ya que Docker-in-Docker está disponible) o use el enfoque de Docker Compose para un servicio de SQL Server integrado. Si usas la opción mssql-python, sustituye la instrucción de instalación msodbcsql18 en el script posterior a la creación por sudo apt-get install -y unixodbc libkrb5-3 libgssapi-krb5-2.

Crear .devcontainer/post-create.sh para instalar el controlador ODBC para dependencias de pyodbc y Python:

#!/bin/bash
set -e

# Install ODBC Driver 18
curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | \
    sudo gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg
echo "deb [signed-by=/usr/share/keyrings/microsoft-prod.gpg] https://packages.microsoft.com/debian/12/prod bookworm main" | \
    sudo tee /etc/apt/sources.list.d/mssql-release.list
sudo apt-get update
sudo ACCEPT_EULA=Y apt-get install -y msodbcsql18 unixodbc-dev

pip install -r requirements.txt

Incluir SQL Server con Docker Compose

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

.devcontainer/docker-compose.yml:

services:
  app:
    image: mcr.microsoft.com/devcontainers/python:3
    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: "<strong_password>"
    ports:
      - "1433:1433"

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

{
    "name": "Django + SQL Server",
    "dockerComposeFile": "docker-compose.yml",
    "service": "app",
    "workspaceFolder": "/workspace",
    "postCreateCommand": "bash .devcontainer/post-create.sh",
    "customizations": {
        "vscode": {
            "extensions": [
                "ms-python.python",
                "ms-mssql.mssql"
            ]
        }
    }
}

Conecte Django al servicio SQL Server por nombre:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "mydb",
        "USER": "sa",
        "PASSWORD": "<password>",
        "HOST": "db",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "TrustServerCertificate=yes",
        },
    },
}

Autenticación para el desarrollo

Elija un enfoque de autenticación basado en dónde se ejecuta la aplicación y dónde se hospeda la base de datos.

Desarrollo local con Azure SQL

Para el desarrollo local contra Azure SQL, usa o bien Authentication=ActiveDirectoryDefault en OPTIONS["extra_params"] la ruta pyodbc, o la TOKEN configuración con DefaultAzureCredential. DefaultAzureCredential reanuda automáticamente tu az login sesión:

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
token = credential.get_token("https://database.windows.net/.default").token

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "mydb",
        "HOST": "<server>.database.windows.net",
        "PORT": "1433",
        "TOKEN": token,
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
        },
    },
}

Para obtener la matriz de autenticación completa y las precauciones, consulte Microsoft Entra autenticación con mssql-django.

Desarrollo de contenedores con Azure SQL

Para los contenedores que se ejecutan en Azure, use la configuración TOKEN con ManagedIdentityCredential para obtener de forma explícita un token de acceso de Microsoft Entra:

from azure.identity import ManagedIdentityCredential

credential = ManagedIdentityCredential()
token = credential.get_token("https://database.windows.net/.default").token

DATABASES = {
  "default": {
    "ENGINE": "mssql",
    "NAME": "mydb",
    "HOST": "<server>.database.windows.net",
    "PORT": "1433",
    "TOKEN": token,
    "OPTIONS": {
      "driver": "ODBC Driver 18 for SQL Server",
    },
  },
}

Para obtener una lista completa de los métodos de autenticación, consulte Microsoft Entra autenticación con mssql-django.

Configuración del canal de CI

Ejecuta tu conjunto de pruebas de Django con un contenedor de servicio de SQL Server en tu canal de CI.

Acciones de GitHub

name: Django Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    services:
      sqlserver:
        image: mcr.microsoft.com/mssql/server:2022-latest
        env:
          ACCEPT_EULA: Y
          MSSQL_SA_PASSWORD: "<strong_password>"
        ports:
          - 1433:1433
        options: >-
          --health-cmd "/opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P \"$$MSSQL_SA_PASSWORD\" -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: "3.12"

      - name: Install ODBC Driver for pyodbc
        run: |
          curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | \
              sudo gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg
          echo "deb [signed-by=/usr/share/keyrings/microsoft-prod.gpg] https://packages.microsoft.com/ubuntu/$(lsb_release -rs)/prod $(lsb_release -cs) main" | \
              sudo tee /etc/apt/sources.list.d/mssql-release.list
          sudo apt-get update
          sudo ACCEPT_EULA=Y apt-get install -y msodbcsql18 unixodbc-dev

      - name: Install dependencies
        run: pip install -r requirements.txt

      - name: Run tests
        env:
          DB_HOST: localhost
          DB_NAME: "master"
          DB_USER: "<user_id>"
          DB_PASSWORD: "<password>"
        run: python manage.py test

Azure Pipelines

trigger:
  - main

resources:
  containers:
    - container: sqlserver
      image: mcr.microsoft.com/mssql/server:2022-latest
      env:
        ACCEPT_EULA: Y
        MSSQL_SA_PASSWORD: "<strong_password>"
      ports:
        - 1433:1433

pool:
  vmImage: ubuntu-latest

services:
  sqlserver: sqlserver

steps:
  - task: UsePythonVersion@0
    inputs:
      versionSpec: "3.12"

  - script: |
      curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | \
          sudo gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg
      echo "deb [signed-by=/usr/share/keyrings/microsoft-prod.gpg] https://packages.microsoft.com/ubuntu/$(lsb_release -rs)/prod $(lsb_release -cs) main" | \
          sudo tee /etc/apt/sources.list.d/mssql-release.list
      sudo apt-get update
      sudo ACCEPT_EULA=Y apt-get install -y msodbcsql18 unixodbc-dev
      pip install -r requirements.txt
    displayName: Install dependencies

  - script: python manage.py test
    displayName: Run tests
    env:
      DB_HOST: "localhost"
      DB_NAME: "master"
      DB_USER: "<user_id>"
      DB_PASSWORD: "<password>"

Fichero settings.py basado en el entorno

Configure settings.py para que lea las credenciales de la base de datos a partir de variables de entorno. Esta única configuración funciona en el desarrollo local, Docker y CI:

import os

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": os.environ.get("DB_NAME", "mydb"),
        "USER": os.environ.get("DB_USER", ""),
        "PASSWORD": os.environ.get("DB_PASSWORD", ""),
        "HOST": os.environ.get("DB_HOST", "localhost"),
        "PORT": os.environ.get("DB_PORT", "1433"),
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": os.environ.get("DB_EXTRA_PARAMS", "TrustServerCertificate=yes"),
        },
    },
}

Almacene las credenciales en un .env archivo para el desarrollo local (agregue .env a .gitignore):

DB_HOST=localhost
DB_NAME=mydb
DB_USER=<user_id>
DB_PASSWORD=<password>

Carga de variables de entorno con django-environ o python-dotenv:

pip install django-environ

import environ

env = environ.Env()
environ.Env.read_env()  # Reads .env from the directory holding this settings file

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": env("DB_NAME"),
        "USER": env("DB_USER", default=""),
        "PASSWORD": env("DB_PASSWORD", default=""),
        "HOST": env("DB_HOST", default="localhost"),
        "PORT": env("DB_PORT", default="1433"),
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": env("DB_EXTRA_PARAMS", default="TrustServerCertificate=yes"),
        },
    },
}

Solución de problemas comunes de contenedor

Contenido relacionado

• Instalación de mssql-django
• Opciones de conexión para mssql-django
• autenticación de Microsoft Entra con mssql-django
• Implementación de una aplicación de Django con SQL Server en Azure App Service
• Prueba de aplicaciones de Django con SQL Server