Sviluppo locale e in container con mssql-django

Questa guida illustra la configurazione dell'ambiente per gli sviluppatori Django che lavorano con il backend mssql-django in ambienti Windows, Linux, macOS, container Docker, devcontainer e pipeline CI.

Prerequisiti

• Python 3.10 fino a 3.14. Django 6.0 e 6.1 richiedono Python 3.12 e versioni successive.
• Docker Desktop (per lo sviluppo basato su contenitori)
• Microsoft ODBC Driver 17 o 18 per SQL Server quando usi il percorso pyodbc predefinito. Vedere Scaricare il driver ODBC per SQL Server.
• Un'immagine base compatibile con il pacchetto richiestomssql-python: Windows x64, Windows ARM64 con Python 3.11 e versioni successive, macOS 15 e versioni successive, o Linux x64/ARM64 con glibc 2.28 e versioni successive o musl 1.2 e versioni successive. SUSE Linux su ARM64 non è supportato.

Il percorso mssql-python non richiede un driver Microsoft ODBC separato per l'installazione di SQL Server. Serve comunque il runtime unixODBC, perché il backend importa pyodbc quando Django lo carica. Per ulteriori informazioni, vedi Seleziona il driver del database per mssql-django.

SQL Server locale con sqlcmd (scelta consigliata)

L'utilità sqlcmd (Go) può creare un contenitore SQL Server in un singolo comando. Gestisce automaticamente il pull dell'immagine Docker, la generazione di password, l'assegnazione di porte e il contesto di connessione:

sqlcmd create mssql --accept-eula

Per creare un contenitore con un database di esempio già collegato:

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

Dopo la creazione, sqlcmd archivia il contesto di connessione in modo da poter eseguire immediatamente una query:

sqlcmd query "SELECT @@VERSION"

Configura Django per connettersi usando i dettagli di connessione che sqlcmd ha stampato durante la creazione. Usare sqlcmd config view per recuperarli in un secondo momento:

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",
        },
    },
}

Una volta terminato, arrestare o eliminare il container:

sqlcmd stop
sqlcmd delete

SQL Server locale in Visual Studio Code

L'estensione MSSQL per Visual Studio Code può creare contenitori SQL Server locali direttamente dall'editor:

1. Aprire la visualizzazione SQL Server nella barra delle attività.
2. Selezionare Aggiungi connessione>Crea SQL Server locale oppure usare il riquadro comandi MS SQL: Crea SQL Server locale.
3. Scegliere la versione SQL Server e accettare il contratto di licenza.
4. L'estensione esegue il pull dell'immagine del contenitore, genera una password e aggiunge automaticamente un profilo di connessione.

Quando il contenitore è in esecuzione, è possibile esplorare i database, eseguire query e gestire gli oggetti in Visual Studio Code prima di passare al codice Django.

SQL Server locale con Docker

Se si preferisce gestire direttamente i contenitori, l'immagine ufficiale del contenitore SQL Server funziona con due variabili di ambiente:

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

Attendere alcuni secondi per l'avvio del contenitore, quindi eseguire le migrazioni:

python manage.py migrate
python manage.py createsuperuser

Dockerfile per applicazioni Django

Crea un Dockerfile minimale per un'applicazione Django che si connetta a SQL Server tramite il percorso pyodbc predefinito. Il driver ODBC è la dipendenza chiave che non è disponibile con l'immagine di base 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"]

Il tuo requirements.txt:

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

Se il tuo alias database usa il percorso driver mssql-python con "python_driver": "mssql_python", ti serve comunque unixODBC, perché il backend importa pyodbc quando Django lo carica. Non hai bisogno del repository dei pacchetti Microsoft o msodbcsql18, quindi il blocco di installazione ODBC si riduce a:

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

Compilare ed eseguire:

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

Configurazione di Devcontainer

Crea un .devcontainer/devcontainer.json per Visual Studio Code che includa SQL Server come servizio 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"
            ]
        }
    }
}

Questo devcontainer installa il driver ODBC per il percorso pyodbc predefinito e le dipendenze Python ma non include un'istanza di SQL Server. Avviarne uno all'interno del devcontainer usando sqlcmd create mssql --accept-eula (poiché Docker-in-Docker è disponibile) o usare l'approccio Docker Compose per un servizio di SQL Server predefinito. Se utilizzi l'opzione mssql-python, sostituisci il comando di installazione msodbcsql18 nello script post-create con sudo apt-get install -y unixodbc libkrb5-3 libgssapi-krb5-2.

Crea .devcontainer/post-create.sh per installare il driver ODBC per le dipendenze di pyodbc e 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

Includere SQL Server con Docker Compose

Per includere SQL Server come servizio in devcontainer, usare 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 (Versione 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"
            ]
        }
    }
}

Connettere Django al servizio SQL Server in base al nome:

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",
        },
    },
}

Autenticazione per lo sviluppo

Scegliere un approccio di autenticazione basato sulla posizione in cui viene eseguita l'applicazione e sulla posizione in cui è ospitato il database.

Sviluppo locale con Azure SQL

Per lo sviluppo locale con Azure SQL, usa Authentication=ActiveDirectoryDefault in OPTIONS["extra_params"] nel percorso pyodbc, oppure l'impostazione TOKEN con DefaultAzureCredential. DefaultAzureCredential riprende automaticamente la tua az login sessione:

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",
        },
    },
}

Per la matrice completa di autenticazione e le avvertenze, vedere Autenticazione Microsoft Entra con mssql-django.

Sviluppo di contenitori con Azure SQL

Per i contenitori in esecuzione in Azure, usare l'impostazione TOKEN con ManagedIdentityCredential per acquisire un token di accesso Microsoft Entra in modo esplicito:

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",
    },
  },
}

Per un elenco completo dei metodi di autenticazione, vedi autenticazione Microsoft Entra con mssql-django.

Configurazione della pipeline CI

Esegui la suite di test di Django con un contenitore di servizio SQL Server nella tua pipeline CI.

GitHub Actions

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>"

Impostazioni di settings.py in base all'ambiente

Configurare settings.py per leggere le credenziali del database dalle variabili di ambiente. Questa singola configurazione funziona in tutto lo sviluppo locale, Docker e 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"),
        },
    },
}

Archiviare le credenziali in un .env file per lo sviluppo locale (aggiungere .env a .gitignore):

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

Caricare le variabili di ambiente 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"),
        },
    },
}

Risolvere i problemi comuni relativi ai contenitori

Contenuti correlati

• Installare mssql-django
• Opzioni di connessione per mssql-django
• Autenticazione Microsoft Entra con mssql-django
• Distribuire un'app Django con SQL Server su Servizio app di Azure
• Testare le app Django con SQL Server