Container en lokale ontwikkeling met mssql-django

In deze handleiding worden de omgevingsinstellingen voor Django-ontwikkelaars beschreven die met de mssql-django back-end werken in Windows, Linux, macOS, Docker-containers, devcontainers en CI-pijplijnen.

Prerequisites

• Python 3.8 of hoger (Django 6.0 vereist Python 3.12 en latere versies)
• Docker Desktop (voor ontwikkeling op basis van containers)
• Microsoft ODBC-stuurprogramma 17 of 18 voor SQL Server. Zie ODBC-stuurprogramma downloaden voor SQL Server.

Lokale SQL Server met sqlcmd (aanbevolen)

Het hulpprogramma sqlcmd (Go) kan in één opdracht een SQL Server-container maken. Het regelt automatisch het ophalen van de Docker-image, het genereren van het wachtwoord, de poorttoewijzing en de verbindingsinstellingen:

sqlcmd create mssql --accept-eula

Een container maken waaraan al een voorbeelddatabase is gekoppeld:

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

Na het maken slaat u de verbindingscontext op, sqlcmd zodat u direct een query kunt uitvoeren:

sqlcmd query "SELECT @@VERSION"

Configureer Django zo dat het verbinding maakt met de verbindingsgegevens die sqlcmd bij het aanmaken heeft weergegeven. Gebruik sqlcmd config view dit om ze later op te halen:

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

Wanneer u klaar bent, stopt of verwijdert u de container:

sqlcmd stop
sqlcmd delete

Lokale SQL Server in Visual Studio Code

Met de MSSQL-extensie voor Visual Studio Code kunt u rechtstreeks vanuit de editor lokale SQL Server-containers maken:

1. Open de weergave SQL Server op de activiteitenbalk.
2. Selecteer Verbinding toevoegen>Lokale SQL Server maken (of gebruik het opdrachtpalet: MS SQL: Lokale SQL Server maken).
3. Kies de SQL Server versie en accepteer de gebruiksrechtovereenkomst.
4. De extensie haalt de containerinstallatiekopie op, genereert een wachtwoord en voegt automatisch een verbindingsprofiel toe.

Zodra de container wordt uitgevoerd, kunt u door databases bladeren, query's uitvoeren en objecten beheren in Visual Studio Code voordat u overschakelt naar uw Django-code.

Lokale SQL Server met Docker

Als u containers liever rechtstreeks beheert, gebruikt de officiële SQL Server-containerimage twee omgevingsvariabelen:

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

Wacht enkele seconden totdat de container is gestart en voer vervolgens migraties uit:

python manage.py migrate
python manage.py createsuperuser

Dockerfile voor Django-toepassingen

Maak een minimaal Dockerfile voor een Django-toepassing die verbinding maakt met SQL Server. Het ODBC-stuurprogramma is de sleutelafhankelijkheid die niet wordt geleverd bij de Python basisinstallatiekopieën:

FROM python:3-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 && \
    apt-get autoremove -y && \
    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"]

Uw requirements.txt:

django>=5.2
mssql-django>=1.5
gunicorn>=22.0

Bouwen en uitvoeren:

docker build -t mydjango .
docker run -e DB_HOST=host.docker.internal -e DB_NAME=mydb \
  -e DB_USER=<your-username> -e DB_PASSWORD=<your-password> \
  -p 8000:8000 mydjango

Devcontainer instellen

Maak een .devcontainer/devcontainer.json voor Visual Studio Code met SQL Server als sidecar-service:

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

Deze devcontainer installeert het ODBC-stuurprogramma en Python afhankelijkheden, maar bevat geen SQL Server exemplaar. Start er een in de devcontainer met (sqlcmd create mssql --accept-eulaomdat Docker-in-Docker beschikbaar is) of gebruik de Docker Compose-benadering voor een ingebouwde SQL Server-service.

Maak .devcontainer/post-create.sh om het ODBC-stuurprogramma en Python-afhankelijkheden te installeren:

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

Neem SQL Server op met Docker Compose

Als u SQL Server als een service wilt opnemen in de devcontainer, gebruikt u 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: "YourStr0ngP@ssword"
    ports:
      - "1433:1433"

.devcontainer/devcontainer.json (Compose-versie):

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

Verbind Django met de SQL Server-service op naam:

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

Verificatie voor ontwikkeling

Kies een verificatiemethode op basis van waar uw toepassing wordt uitgevoerd en waar de database wordt gehost.

Lokale ontwikkeling tegen Azure SQL

Gebruik voor lokale ontwikkeling met Azure SQL Authentication=ActiveDirectoryDefault in OPTIONS["extra_params"] (met mssql-django 1.7.3 en hoger, plus een compatibel Microsoft ODBC-stuurprogramma) of de instelling TOKEN met DefaultAzureCredential. DefaultAzureCredential neemt automatisch uw az login sessie op:

from azure.identity import DefaultAzureCredential

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

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

Zie Microsoft Entra verificatie met mssql-django voor de volledige verificatiematrix en waarschuwingen.

Ontwikkeling van containers voor Azure SQL

Voor containers die in Azure worden uitgevoerd, gebruikt u de instelling TOKEN met ManagedIdentityCredential om expliciet een Microsoft Entra-toegangstoken te verkrijgen:

from azure.identity import ManagedIdentityCredential

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

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

Zie Microsoft Entra verificatie met mssql-django voor een volledige lijst met verificatiemethoden.

Configuratie van CI-pipeline

Voer uw Django-testpakket uit op een SQL Server servicecontainer in uw CI-pijplijn.

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: YourStr0ngP@ssword
        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.x"

      - name: Install ODBC Driver
        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: <username>
          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: YourStr0ngP@ssword
      ports:
        - 1433:1433

pool:
  vmImage: ubuntu-latest

services:
  sqlserver: sqlserver

steps:
  - task: UsePythonVersion@0
    inputs:
      versionSpec: "3.x"

  - 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: <username>
      DB_PASSWORD: <password>

Op omgeving gebaseerde settings.py

Configureren settings.py voor het lezen van databasereferenties uit omgevingsvariabelen. Deze enkele configuratie werkt voor lokale ontwikkeling, Docker en 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"),
        },
    },
}

Referenties opslaan in een .env bestand voor lokale ontwikkeling (toevoegen .env aan .gitignore):

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

Omgevingsvariabelen laden met django-environ of python-dotenv:

pip install django-environ

import environ

env = environ.Env()
environ.Env.read_env()  # Reads .env 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",
        },
    },
}

Veelvoorkomende containerproblemen oplossen

Verwante inhoud

• mssql-django installeren
• Verbindingsopties voor mssql-django
• Microsoft Entra-authenticatie met mssql-django
• Een Django-app met SQL Server implementeren in Azure App Service
• Django-apps testen met SQL Server