Container- und lokale Entwicklung mit mssql-python

Dieser Leitfaden behandelt die Umgebungseinrichtung für Python-Entwickler, die mit dem Treiber mssql-python über Windows, Linux, macOS, Docker-Container, Entwicklungscontainer und CI-Pipelines hinweg arbeiten.

Voraussetzungen

• Python 3.10 oder höher.
• Docker Desktop (für containerbasierte Entwicklung).
• Ein x64-kompatibler Host (Intel, AMD oder x64 VM) für SQL Server Linux-Container. SQL Server Linux-Container unterstützen keine ARM64-Hosts.

Lokale SQL Server mit sqlcmd (empfohlen)

Das go-sqlcmd-Dienstprogramm kann mit einem einzigen Befehl einen SQL Server-Container 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"

Erstelle einmal Anmeldeinformationen für eine Anwendung und verwende sie dann in deinem Python-Code:

sqlcmd query --database <database> "CREATE LOGIN <app-login> WITH PASSWORD = '<password>';"
sqlcmd query --database <database> "CREATE USER <app-login> FOR LOGIN <app-login>;"
sqlcmd query --database <database> "ALTER ROLE db_datareader ADD MEMBER <app-login>;"
sqlcmd query --database <database> "ALTER ROLE db_datawriter ADD MEMBER <app-login>;"

Ersetze <database>, <app-login>, und <password> durch Werte aus deiner Umgebung.

Stelle die Verbindung aus Python heraus mit den Verbindungsdetails her, die sqlcmd beim Erstellen ausgegeben hat. Verwenden Sie sqlcmd config view, um sie später abzurufen:

import mssql_python

conn = mssql_python.connect(
    server="localhost,1433",
    uid="<app login>",
    pwd="<password>",
    encrypt="yes",
    trust_server_certificate="yes"
)

cursor = conn.cursor()
cursor.execute("SELECT @@VERSION")
print(cursor.fetchval())
conn.close()

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

sqlcmd stop
sqlcmd delete

Lokaler SQL Server von VS Code

Die SQL Server-Erweiterung für VS Code (ms-mssql.mssql) 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 läuft, kannst du Datenbanken durchsuchen, Abfragen ausführen und Objekte direkt in VS Code verwalten, bevor du auf Python-Code umsteigst.

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

Warte ein paar Sekunden, dann verbinde dich mit Python:

import mssql_python

conn = mssql_python.connect(
    server="localhost,1433",
    uid="<app login>",
    pwd="<password>",
    encrypt="yes",
    trust_server_certificate="yes"
)

cursor = conn.cursor()
cursor.execute("SELECT @@VERSION")
print(cursor.fetchval())
conn.close()

Um die AdventureWorks-Beispieldatenbank in den Container zu laden:

# Download AdventureWorks backup
curl -L -o AdventureWorks2022.bak \
  "https://github.com/Microsoft/sql-server-samples/releases/download/adventureworks/AdventureWorks2022.bak"

# Copy into container
docker cp AdventureWorks2022.bak sql1:/var/opt/mssql/backup/

# Restore
docker exec sql1 /opt/mssql-tools18/bin/sqlcmd \
  -S localhost -U sa -P "YourStr0ngP@ssword" -C \
  -Q "RESTORE DATABASE AdventureWorks2022 FROM DISK='/var/opt/mssql/backup/AdventureWorks2022.bak' WITH MOVE 'AdventureWorks2022' TO '/var/opt/mssql/data/AdventureWorks2022.mdf', MOVE 'AdventureWorks2022_log' TO '/var/opt/mssql/data/AdventureWorks2022_log.ldf'"

Dockerfile für Python-Anwendungen

Bewahren Sie die Python-Basis-Image-Referenz an einem Ort auf, damit lokale Builds, Entwicklungscontainer und CI-Pipelines nicht driften. Für lokale Tests eignet sich ein breit unterstützter Tag wie python:3-slim gut. Für geteilte Devcontainer, CI und Production ersetze dieses Tag durch ein genehmigtes, mit Digest gepinntes Image aus der Zulassungsliste deiner Organisation.

Erstellen Sie eine minimale Dockerfile für eine Python-Anwendung, die sich mit Microsoft SQL verbindet:

ARG PYTHON_BASE=python:3-slim
FROM ${PYTHON_BASE}

# Install system libraries required by mssql-python on Linux
RUN apt-get update && \
    apt-get install -y --no-install-recommends libltdl7 libkrb5-3 libgssapi-krb5-2 && \
    rm -rf /var/lib/apt/lists/*

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

COPY . .
CMD ["python", "app.py"]

Ihr requirements.txt:

mssql-python>=1.11.0

Erstellen und Ausführen:

docker build -t myapp .
docker run -e SQL_SERVER=host.docker.internal,1433 myapp

In freigegebenen Umgebungen übergebe mit --build-arg PYTHON_BASE=python:3-slim@sha256:<approved-digest> eine genehmigte Referenz auf ein unveränderliches Basis-Image.

Alpine Linux

Alpine verwendet musl anstelle von glibc. Installieren Sie die erforderlichen Pakete:

ARG PYTHON_BASE=python:3-alpine
FROM ${PYTHON_BASE}

RUN apk add --no-cache libltdl krb5-libs

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

COPY . .
CMD ["python", "app.py"]

Devcontainer-Einrichtung

Verwenden Sie dieselbe Dockerfile, mit der Ihre Anwendung erstellt wird, wieder. Dieser Ansatz hält den Devcontainer am Runtime-Image ausgerichtet und verhindert, dass Python-Versionspins über mehrere Dateien verteilt werden.

Erstellen Sie ein .devcontainer/devcontainer.json für VS Code:

{
    "name": "Python + SQL Server",
    "build": {
        "dockerfile": "../Dockerfile",
        "context": ".."
    },
    "features": {
        "ghcr.io/devcontainers/features/docker-in-docker:2": {}
    },
    "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
    "postCreateCommand": "pip install --no-cache-dir -r requirements.txt",
    "forwardPorts": [1433],
    "customizations": {
        "vscode": {
            "extensions": [
                "ms-python.python",
                "ms-mssql.mssql"
            ]
        }
    }
}

Um SQL Server als Dienst in den Devcontainer einzuschließen, verwenden Sie Docker Compose:

.devcontainer/docker-compose.yml:

services:
  app:
    build:
      context: ..
      dockerfile: Dockerfile
    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-Version):

{
    "name": "Python + SQL Server",
    "dockerComposeFile": "docker-compose.yml",
    "service": "app",
    "workspaceFolder": "/workspace",
    "postCreateCommand": "pip install -r requirements.txt",
    "customizations": {
        "vscode": {
            "extensions": [
                "ms-python.python",
                "ms-mssql.mssql"
            ]
        }
    }
}

Für gemeinsame Arbeitsbereiche sollten Sie das SQL Server-Service-Image auf einen freigegebenen Digest festlegen, anstatt ein variables Tag zu verwenden. Lade MSSQL_SA_PASSWORD aus einer lokalen .env-Datei oder einem plattformeigenen Secret-Store, anstatt sie in die Quellcodeverwaltung einzuchecken.

Verbinden Sie sich mit dem SQL Server-Dienst nach Namen:

conn = mssql_python.connect(
    server="db,1433",
    uid="<app login>",
    pwd="<password>",
    encrypt="yes",
    trust_server_certificate="yes"
)

Plattformspezifische Abhängigkeiten

Der Treiber mssql-python bündelt seine nativen Komponenten. Du musst keinen externen ODBC-Treibermanager installieren. Der Treiber benötigt jedoch eine kleine Anzahl von Systembibliotheken unter Linux und macOS.

Für macOS gilt: Wenn du auf SSL-Fehler stößt, setze die Linker-Flags:

export LDFLAGS="-L/opt/homebrew/opt/openssl/lib"
export CPPFLAGS="-I/opt/homebrew/opt/openssl/include"

Für vollständige Installationsanweisungen siehe Install mssql-python.

Authentifizierung für die Entwicklung

Lokale Entwicklung gegen Azure SQL

Verwenden Sie ActiveDirectoryDefault für die passwortlose Authentifizierung. Diese Option durchläuft automatisch Azure CLI, Visual Studio, Umgebungsvariablen und verwaltete Identität:

conn = mssql_python.connect(
    server="<server>.database.windows.net",
    database="<database>",
    authentication="ActiveDirectoryDefault",
    encrypt="yes"
)

Stellen Sie sicher, dass Sie mit der Azure CLI angemeldet sind:

az login

Lokale Entwicklung gegen SQL Server

Verwenden Sie SQL-Authentifizierung mit einer lokalen Instanz.

conn = mssql_python.connect(
    server="localhost,1433",
    uid="<app login>",
    pwd="<password>",
    encrypt="yes",
    trust_server_certificate="yes"
)

Containerentwicklung für Azure SQL

Für Container, die in Azure laufen (App Service, Container Apps, AKS), verwenden Sie Managed Identity.

conn = mssql_python.connect(
    server="<server>.database.windows.net",
    database="<database>",
    authentication="ActiveDirectoryMSI",
    encrypt="yes"
)

Für lokal ausgeführte Container, die eine Verbindung mit Azure SQL herstellen müssen, stellen Sie sicher, dass der Container über eine Anmeldeinformationsquelle verfügt, die von ActiveDirectoryDefault verwendet werden kann. Die zuverlässigsten Optionen sind:

• Installiere Azure CLI im Container und melde dich dort an. Mounte ~/.azure nur vom Host, wenn das Container-Image bereits eine Azure CLI enthält und du beabsichtigst, diesen Credential-Cache wiederzuverwenden.
• Bereitstellen Sie Serviceprincipal-Zugangsdaten über Umgebungsvariablen wie AZURE_CLIENT_ID, AZURE_TENANT_ID, und AZURE_CLIENT_SECRET.

Dann verwenden Sie ActiveDirectoryDefault in Ihrem Verbindungscode.

Unterstützte Microsoft SQL-Endpunkte

Der Treiber mssql-python verbindet sich mit allen Microsoft SQL-Endpunkten:

Siehe Microsoft Entra-Authentifizierung für alle sieben Authentifizierungsmodi und Support-Lebenszyklus für die vollständige Kompatibilitätsmatrix.

Einrichtung der CI-Pipeline

GitHub Actions

Halte die Python-Laufzeit in einer Variable, damit du sie an einem Ort überprüfen und aktualisieren kannst. Verwenden Sie 3.x für schnelle Validierungspipelines, oder ersetzen Sie es durch eine von der Organisation genehmigte genaue Version für Release-Pipelines.

name: Test with SQL Server
on: [push, pull_request]

env:
  PYTHON_VERSION: "3.x"

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 YourStr0ngP@ssword -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: ${{ env.PYTHON_VERSION }}
          check-latest: true

      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y libltdl7 libkrb5-3 libgssapi-krb5-2
          pip install -r requirements.txt

      - name: Run tests
        env:
          SQL_SERVER: localhost,1433
          SQL_UID: sa
          SQL_PWD: YourStr0ngP@ssword
        run: pytest

Für geteilte Pipelines ersetzen Sie das Inline-Platzhalterpasswort durch ein verschlüsseltes Geheimnis, pinnen Sie das SQL Server-Service-Image an einen Digest und behalten Sie die Python-Version in einer von der Organisation verwalteten Variable oder in wiederverwendbaren Workflow-Eingaben.

Azure Pipelines

Verwenden Sie eine Container-Ressource, um SQL Server als Service parallel zu Ihrem Testjob auszuführen:

trigger:
  - main

variables:
  python.version: "3.x"

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: "$(python.version)"

  - script: |
      sudo apt-get update
      sudo apt-get install -y libltdl7 libkrb5-3 libgssapi-krb5-2
      pip install -r requirements.txt
    displayName: Install dependencies

  - script: pytest
    displayName: Run tests
    env:
      SQL_SERVER: localhost,1433
      SQL_UID: sa
      SQL_PWD: YourStr0ngP@ssword

Wie bei GitHub Actions ersetze das Inline-Platzhalter-Passwort durch eine geheime Variable, bevor du dieses Muster außerhalb einer Wegwerf-Demo-Pipeline verwendest.

Sicherheit und Geheime Schlüssel

Programmieren Sie Datenbankpasswörter oder Verbindungsfolgen nicht fest im Quellcode oder in Dockerfiles. Nutze stattdessen Umgebungsvariablen und Secrets-Management.

Umweltvariablen für lokale Entwicklung

Speichere Zugangsdaten in Umgebungsvariablen oder einer .env Datei, die von der Quellcode-Kontrolle ausgeschlossen ist:

# .env (add to .gitignore)
SQL_SERVER=localhost,1433
SQL_UID=sa
SQL_PWD=YourStr0ngP@ssword

import os
import mssql_python

conn = mssql_python.connect(
    server=os.environ["SQL_SERVER"],
    uid=os.environ["SQL_UID"],
    pwd=os.environ["SQL_PWD"],
    encrypt="yes",
    trust_server_certificate="yes"
)

Für Docker Compose verweisen Sie auf eine .env Datei:

services:
  app:
    build: .
    env_file: .env

CI/CD-Geheimnisse

In CI-Pipelines verwenden Sie den geheimen Speicher der Plattform anstelle der Klartext-Umgebungsvariablen:

• GitHub Actions: Verwenden Sie verschlüsselte Geheimnisse und referenzieren Sie sie als ${{ secrets.SQL_PWD }}.
• Azure Pipelines: Verwenden Sie geheime Variablen und referenzieren Sie sie als $(SQL_PWD).

Hygiene der Container-Lieferkette

Nutzen Sie diese Praktiken für gemeinsame Entwicklerumgebungen und CI:

• Speichern Sie Bildreferenzen an einem Ort, zum Beispiel in einem Docker ARG, einem Devcontainer-Build oder einer Pipeline-Variable.
• Verwenden Sie für freigegebene Container-Images unveränderliche Digests anstelle von variablen Tags.
• Überprüfen und aktualisieren Sie festgeschriebene Digests über einen freigegebenen Aktualisierungsprozess wie Dependabot, Renovate oder einen internen Image-Promotion-Workflow.
• Committen Sie eine Abhängigkeitssperrdatei wie uv.lock, oder verwenden Sie gehashte Anforderungsdateien für reproduzierbare Python-Installationen.
• Bevorzugen Sie von der Organisation genehmigte Basisbilder und interne Registry-Spiegel, wenn Ihre Plattform diese bereitstellt.

Produktion: passwortlose Authentifizierung

Für Produktionsworkloads gegen Azure SQL verwenden Sie Microsoft Entra-Authentifizierung mit verwalteter Identität. Dieser Ansatz eliminiert Passwörter vollständig:

conn = mssql_python.connect(
    server="<server>.database.windows.net",
    database="<database>",
    authentication="ActiveDirectoryMSI",
    encrypt="yes"
)

Für Anwendungen, die Geheimnisse wie SQL-Authentifizierungspasswörter speichern müssen, verwenden Sie Azure Key Vault und rufen Sie diese zur Laufzeit ab.

Abhängigkeitsmanagement mit UV

uv ist ein schneller Python-Paket-Installer, der gut in CI- und Container-Builds funktioniert:

ARG PYTHON_BASE=python:3-slim
FROM ${PYTHON_BASE}

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

# Install uv. In shared builds, pin the source image to an approved digest.
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev

COPY . .
CMD ["uv", "run", "python", "app.py"]

In CI:

pip install uv
uv sync
uv run pytest

Behandeln häufiger Containerprobleme

Verwandte Inhalte

• Installiere mssql-python
• Supportlebenszyklus
• Verbindungszeichenfolgen
• Microsoft Entra-Authentifizierung
• Schnellstart: Wiederholbare Bereitstellungen