Container und lokale Entwicklung mit mssql-django

Dieses Handbuch befasst sich mit der Umgebungseinrichtung für Django-Entwickler, die mit dem mssql-django Back-End in Windows, Linux, macOS, Docker-Containern, Devcontainern und CI-Pipelines arbeiten.

Voraussetzungen

• Python 3.10 bis 3.14. Django 6.0 und 6.1 erfordern Python 3.12 und neuere Versionen.
• Docker Desktop (für containerbasierte Entwicklung)
• Microsoft ODBC Driver 17 oder 18 für SQL Server, wenn du den Standardpfad pyodbc verwendest. Siehe "ODBC-Treiber herunterladen" für SQL Server.
• Ein Basisimage, das mit dem erforderlichen mssql-python Paket kompatibel ist: Windows x64, Windows ARM64 mit Python 3.11 und neueren Versionen, macOS 15 und neueren Versionen oder Linux x64/ARM64 mit glibc 2.28 und neueren Versionen oder musl 1.2 und späteren Versionen. SUSE Linux auf ARM64 wird nicht unterstützt.

Der mssql-python-Pfad erfordert keinen separaten Microsoft ODBC-Treiber für die Installation eines SQL Server. Es wird weiterhin die unixODBC-Laufzeit benötigt, weil das Backend Pyodbc importiert, wenn Django es lädt. Weitere Informationen finden Sie unter Select the database driver for mssql-django.

Lokale SQL Server mit sqlcmd (empfohlen)

Das Hilfsprogramm sqlcmd (Go) kann einen SQL Server Container in einem einzigen Befehl erstellen. Er behandelt den Docker-Image-Pull, die Kennwortgenerierung, die Portzuweisung und den Verbindungskontext automatisch:

sqlcmd create mssql --accept-eula

So erstellen Sie einen Container mit bereits angefügter Beispieldatenbank:

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

Speichert nach der Erstellung den Verbindungskontext, sqlcmd damit Sie sofort abfragen können:

sqlcmd query "SELECT @@VERSION"

Konfigurieren Sie Django so, dass es die Verbindungsdetails verwendet, die sqlcmd bei der Erstellung ausgegeben hat. Verwenden Sie sqlcmd config view, um sie später abzurufen:

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

Wenn Sie fertig sind, beenden oder löschen Sie den Container:

sqlcmd stop
sqlcmd delete

Lokaler SQL Server in Visual Studio Code

Die MSSQL-Erweiterung für Visual Studio Code kann lokale SQL Server Container direkt aus dem Editor erstellen:

1. Öffnen Sie die ansicht SQL Server in der Aktivitätsleiste.
2. Wählen Sie Verbindung hinzufügen>Lokalen SQL Server erstellen aus (oder verwenden Sie die Befehlspalette: MS SQL: Lokalen SQL Server erstellen).
3. Wählen Sie die SQL Server Version aus, und akzeptieren Sie die EULA.
4. Die Erweiterung ruft das Containerimage ab, generiert ein Kennwort und fügt automatisch ein Verbindungsprofil hinzu.

Sobald der Container ausgeführt wird, können Sie Datenbanken durchsuchen, Abfragen ausführen und Objekte in Visual Studio Code verwalten, bevor Sie zu Ihrem Django-Code wechseln.

Lokale SQL Server mit Docker

Wenn Sie Container lieber direkt verwalten möchten, funktioniert das offizielle SQL Server Containerimage mit zwei Umgebungsvariablen:

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

Warten Sie einige Sekunden, bis der Container gestartet wird, und führen Sie dann Migrationen aus:

python manage.py migrate
python manage.py createsuperuser

Dockerfile für Django-Anwendungen

Erstelle eine minimale Dockerfile für eine Django-Anwendung, die sich über den Standardpfad pyodbc mit SQL Server verbindet. Der ODBC-Treiber ist die zentrale Abhängigkeit, die nicht mit dem Python-Basis-Image mitgeliefert wird:

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

Ihr requirements.txt:

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

Wenn dein Datenbankalias den mssql-python-Treiberpfad mit "python_driver": "mssql_python"verwendet, brauchst du trotzdem unixODBC, weil das Backend Pyodbc importiert, wenn Django es lädt. Du brauchst nicht das Microsoft-Paket-Repository oder msodbcsql18, daher schrumpft der ODBC-Installationsblock auf:

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

Erstellen und Ausführen:

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

Devcontainer-Einrichtung

Erstellen Sie .devcontainer/devcontainer.json für Visual Studio Code, das SQL Server als Sidecar-Dienst umfasst:

{
    "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"
            ]
        }
    }
}

Dieser Devcontainer installiert den ODBC-Treiber für den Standardpfad von pyodbc und Python-Abhängigkeiten, enthält aber keine SQL Server-Instanz. Starten Sie einen innerhalb des Devcontainers mit sqlcmd create mssql --accept-eula (da Docker-in-Docker verfügbar ist) oder verwenden Sie den Docker Compose-Ansatz für einen integrierten SQL Server-Dienst. Wenn du den mssql-python-Pfad verwendest, ersetze die msodbcsql18 Installation im Post-create-Skript durch sudo apt-get install -y unixodbc libkrb5-3 libgssapi-krb5-2.

Erstellen Sie .devcontainer/post-create.sh, um den ODBC-Treiber für pyodbc und die Python-Abhängigkeiten zu installieren:

#!/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

Einschließen SQL Server mit Docker Compose

Um SQL Server als Dienst in den Devcontainer einzuschließen, verwenden Sie 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 (Compose-Version):

{
    "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"
            ]
        }
    }
}

Verbinden Sie Django mit dem SQL Server-Dienst anhand des Namens:

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

Authentifizierung für die Entwicklung

Wählen Sie einen Authentifizierungsansatz basierend darauf aus, wo Ihre Anwendung ausgeführt wird und wo die Datenbank gehostet wird.

Lokale Entwicklung gegen Azure SQL

Für die lokale Entwicklung mit Azure SQL verwenden Sie entweder Authentication=ActiveDirectoryDefault in OPTIONS["extra_params"] im pyodbc-Pfad oder die Einstellung DefaultAzureCredential mit TOKEN. DefaultAzureCredential setzt Ihre az login Sitzung automatisch fort:

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

Die vollständige Authentifizierungsmatrix und Hinweise finden Sie unter Microsoft Entra-Authentifizierung mit mssql-django.

Containerentwicklung für Azure SQL

Verwenden Sie für Container, die in Azure ausgeführt werden, die Einstellung TOKEN mit ManagedIdentityCredential, um explizit ein Microsoft Entra-Zugriffstoken abzurufen:

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

Eine vollständige Liste der Authentifizierungsmethoden finden Sie unter Microsoft Entra Authentifizierung mit mssql-django.

Einrichtung der CI-Pipeline

Führen Sie Ihre Django-Testsuite mit einem SQL Server-Dienstcontainer in Ihrer CI-Pipeline aus.

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

Umgebungsabhängige settings.py

Konfigurieren Sie settings.py so, dass Datenbankanmeldeinformationen aus Umgebungsvariablen gelesen werden. Diese einzelne Konfiguration funktioniert für lokale Entwicklung, Docker und 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"),
        },
    },
}

Speichern von Anmeldeinformationen in einer .env Datei für die lokale Entwicklung (hinzufügen .env zu .gitignore):

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

Laden von Umgebungsvariablen mit django-environ oder 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"),
        },
    },
}

Behandeln häufiger Containerprobleme

Verwandte Inhalte

• Installieren von mssql-django
• Verbindungsoptionen für mssql-django
• Microsoft Entra Authentifizierung mit mssql-django
• Bereitstellen einer Django-App mit SQL Server zum Azure App Service
• Testen von Django-Apps mit SQL Server