Tworzenie aplikacji w kontenerach i lokalnie za pomocą mssql-django

Ten przewodnik obejmuje konfigurację środowiska dla programistów Django pracujących z backendem mssql-django w systemach Windows, Linux i macOS oraz w kontenerach Docker, kontenerach deweloperskich i potokach CI.

Prerequisites

• Python 3.10 do 3.14. Django 6.0 i 6.1 wymagają wersji Python 3.12 i nowszych.
• Docker Desktop (na potrzeby programowania opartego na kontenerach)
• Microsoft ODBC Driver 17 lub 18 do programu SQL Server w przypadku użycia domyślnej ścieżki pyodbc. Zobacz Pobieranie sterownika ODBC dla programu SQL Server.
• Obraz bazowy zgodny z wymaganym mssql-python pakietem: Windows x64, Windows ARM64 z wersjami Python 3.11 i nowszymi, macOS 15 i nowszymi, lub Linux x64/ARM64 z glibc 2.28 i nowszymi wersjami albo musl 1.2 i nowszymi. SUSE Linux na ARM64 nie jest obsługiwany.

Ścieżka mssql-python nie wymaga osobnego sterownika Microsoft ODBC do instalacji SQL Server. Nadal wymaga środowiska uruchomieniowego unixODBC, ponieważ backend importuje moduł pyodbc, gdy Django go wczytuje. Więcej informacji można znaleźć w artykule Wybierz sterownik bazy danych dla mssql-django.

Lokalny SQL Server za pomocą sqlcmd (zalecane)

Narzędzie sqlcmd (Go) może utworzyć kontener SQL Server w jednym poleceniu. Automatycznie obsługuje pobieranie obrazu Dockera, generowanie haseł, przypisywanie portów i kontekst połączenia:

sqlcmd create mssql --accept-eula

Aby utworzyć kontener z już dołączoną przykładową bazą danych:

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

Po utworzeniu sqlcmd przechowuje kontekst połączenia, dzięki czemu można od razu wykonywać zapytania:

sqlcmd query "SELECT @@VERSION"

Skonfiguruj Django tak, aby łączył się przy użyciu danych połączenia, które sqlcmd wyświetlił podczas tworzenia. Użyj polecenia sqlcmd config view, aby odzyskać je później:

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

Po zakończeniu zatrzymaj lub usuń kontener:

sqlcmd stop
sqlcmd delete

Lokalny SQL Server w programie Visual Studio Code

Rozszerzenie MSSQL dla Visual Studio Code może tworzyć lokalne kontenery SQL Server bezpośrednio z poziomu edytora:

1. Otwórz widok SQL Server na pasku działań.
2. Wybierz pozycję Dodaj połączenie>Utwórz lokalne SQL Server (lub użyj palety poleceń: MS SQL: Utwórz lokalny SQL Server).
3. Wybierz wersję SQL Server i zaakceptuj umowy EULA.
4. Rozszerzenie ściąga obraz kontenera, generuje hasło i automatycznie dodaje profil połączenia.

Po uruchomieniu kontenera można przeglądać bazy danych, uruchamiać zapytania i zarządzać obiektami w Visual Studio Code przed przełączeniem do kodu Django.

Lokalny SQL Server z Dockerem

Jeśli wolisz zarządzać kontenerami bezpośrednio, oficjalny obraz kontenera SQL Server działa z dwiema zmiennymi środowiskowymi:

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

Poczekaj kilka sekund na uruchomienie kontenera, a następnie uruchom migracje:

python manage.py migrate
python manage.py createsuperuser

Plik Dockerfile dla aplikacji Django

Utwórz minimalny Dockerfile dla aplikacji Django, która łączy się z SQL Server przy użyciu domyślnej ścieżki pyodbc. Sterownik ODBC jest kluczową zależnością, która nie pochodzi z obrazu podstawowego 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"]

Twój requirements.txt:

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

Jeśli alias twojej bazy danych używa ścieżki sterownika mssql-python z "python_driver": "mssql_python", nadal potrzebujesz unixODBC, ponieważ backend importuje pyodbc, gdy Django go ładuje. Nie potrzebujesz repozytorium pakietów Microsoft ani msodbcsql18, więc blok instalacyjny ODBC kurczy się do:

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

Kompilowanie i uruchamianie:

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

Konfiguracja usługi Devcontainer

Utwórz element .devcontainer/devcontainer.json dla Visual Studio Code, który obejmuje SQL Server jako usługę przyczepki:

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

Ten devcontainer instaluje sterownik ODBC dla domyślnej ścieżki pyodbc oraz zależności Python, ale nie zawiera instancji SQL Server. Uruchom jedną instancję w devcontainerze przy użyciu sqlcmd create mssql --accept-eula (ponieważ Docker-in-Docker jest dostępny) lub skorzystaj z podejścia Docker Compose, aby użyć wbudowanej usługi SQL Server. Jeśli używasz wariantu mssql-python, zastąp polecenie instalacji msodbcsql18 w skrypcie post-create poleceniem sudo apt-get install -y unixodbc libkrb5-3 libgssapi-krb5-2.

Utwórz .devcontainer/post-create.sh, aby zainstalować sterownik ODBC dla pyodbc oraz zależności języka 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

Dołączanie SQL Server za pomocą narzędzia Docker Compose

Aby uwzględnić SQL Server jako usługę w devcontainer, użyj narzędzia 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 (Redaguj wersję):

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

Połącz platformę Django z usługą SQL Server według nazwy:

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

Uwierzytelnianie na potrzeby programowania

Wybierz metodę uwierzytelniania w zależności od tego, gdzie działa aplikacja i gdzie jest hostowana baza danych.

Lokalne tworzenie aplikacji z użyciem Azure SQL

Do lokalnego programowania z użyciem Azure SQL użyj albo Authentication=ActiveDirectoryDefault w OPTIONS["extra_params"] w ścieżce pyodbc, albo ustawienia TOKEN z DefaultAzureCredential. DefaultAzureCredential automatycznie pobiera sesję az login :

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

Aby zapoznać się z pełną macierzą uwierzytelniania i ostrzeżeniami, zobacz Uwierzytelnianie Microsoft Entra za pomocą mssql-django.

Tworzenie aplikacji kontenerowych dla usługi Azure SQL

W przypadku kontenerów działających na platformie Azure, użyj ustawienia TOKEN wraz z poleceniem ManagedIdentityCredential, aby jawnie uzyskać token dostępu 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",
    },
  },
}

Aby uzyskać pełną listę metod uwierzytelniania, zobacz Microsoft Entra uwierzytelnianie za pomocą narzędzia mssql-django.

Konfiguracja potoku ciągłej integracji

Uruchom zestaw testów Django z użyciem kontenera usługi SQL Server w potoku 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>"

Settings.py oparte na środowisku

Skonfiguruj settings.py do odczytu poświadczeń bazy danych ze zmiennych środowiskowych. Ta pojedyncza konfiguracja działa w lokalnym środowisku deweloperskim, Dockerze i 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"),
        },
    },
}

Zapisz poświadczenia w pliku .env na potrzeby lokalnego programowania (dodaj .env do .gitignore):

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

Wczytaj zmienne środowiskowe za pomocą django-environ lub 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"),
        },
    },
}

Rozwiązywanie typowych problemów z kontenerem

Treści powiązane

• Instalowanie narzędzia mssql-django
• Opcje połączenia dla mssql-django
• Uwierzytelnianie Microsoft Entra w mssql-django
• Wdróż aplikację Django z serwerem SQL Server w usłudze Azure App Service
• Testowanie aplikacji Django przy użyciu SQL Server