Container- en lokale ontwikkeling met mssql-python

Deze gids behandelt omgevingsinstellingen voor Python-ontwikkelaars die met de mssql-python driver werken over Windows, Linux, macOS, Docker-containers, devcontainers en CI-pijplijnen.

Prerequisites

• Python 3.10 of hoger.
• Docker Desktop (voor containergebaseerde ontwikkeling).
• Een x64-compatibele host (Intel, AMD of x64 VM) voor SQL Server Linux-containers. SQL Server Linux-containers ondersteunen geen ARM64-hosts.

Lokale SQL Server met sqlcmd (aanbevolen)

De go-sqlcmd-tool kan een SQL Server-container aanmaken in één enkel commando. 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"

Maak één keer een applicatielogin aan en gebruik die vervolgens in je 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>;"

Vervang <database>, <app-login>, en <password> door waarden uit je omgeving.

Maak vanuit Python verbinding met de verbindingsgegevens die sqlcmd bij het aanmaken heeft weergegeven. Gebruik sqlcmd config view dit om ze later op te halen:

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()

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

sqlcmd stop
sqlcmd delete

Lokale SQL Server van VS Code

De SQL Server-extensie voor VS Code (ms-mssql.mssql) kan lokale SQL Server-containers direct vanuit de editor aanmaken:

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 draait, kun je databases doorzoeken, queries uitvoeren en objecten beheren direct in VS Code voordat je overstapt op Python-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 een paar seconden, maak dan verbinding vanuit 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()

Om de AdventureWorks-voorbeelddatabase in de container te 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 voor Python-applicaties

Houd de Python-basisafbeeldingsreferentie op één plek zodat lokale builds, devcontainers en CI-pijplijnen niet afdriften. Voor lokale experimenten werkt een breed ondersteund tag, zoals zoals python:3-slim goed. Voor gedeelde devcontainers, CI en productie vervang je die tag door een goedgekeurde, vastgepinde afbeelding uit de toelaatlijst van je organisatie.

Maak een minimale Dockerfile aan voor een Python-applicatie die verbinding maakt met Microsoft SQL:

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

Uw requirements.txt:

mssql-python>=1.11.0

Bouwen en uitvoeren:

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

In gedeelde omgevingen geef je een goedgekeurde onveranderlijke basisafbeeldingsreferentie door met --build-arg PYTHON_BASE=python:3-slim@sha256:<approved-digest>.

Alpine Linux

Alpiene gebruikt musl in plaats van glibc. Installeer de vereiste pakketten:

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 instellen

Hergebruik hetzelfde Dockerfile waarmee je applicatie bouwt. Deze aanpak houdt de devcontainer uitgelijnd met je runtime-image en voorkomt dat Python-versiepins over meerdere bestanden worden verspreid.

Maak een .devcontainer/devcontainer.json voor 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"
            ]
        }
    }
}

Als u SQL Server als een service wilt opnemen in de devcontainer, gebruikt u 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-versie):

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

Voor gedeelde werkruimtes pinne je de SQL Server-serviceafbeelding aan een goedgekeurde digest in plaats van te vertrouwen op een drijvende tag. Laad MSSQL_SA_PASSWORD uit een lokaal .env-bestand of de geheimenopslag van het platform in plaats van het op te nemen in versiebeheer.

Maak verbinding met de SQL Server-dienst op naam:

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

Platformspecifieke afhankelijkheden

Het mssql-pythonstuurprogramma bevat zijn native componenten. Je hoeft geen externe ODBC-drivermanager te installeren. De driver vereist echter een kleine set systeembibliotheken op Linux en macOS.

Voor macOS, als je SSL-fouten tegenkomt, stel dan de linker-vlaggen in:

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

Voor volledige installatie-instructies, zie Install mssql-python.

Verificatie voor ontwikkeling

Lokale ontwikkeling tegen Azure SQL

Gebruik ActiveDirectoryDefault voor wachtwoordloze authenticatie. Deze optie doorloopt automatisch Azure CLI, Visual Studio, omgevingsvariabelen en beheerde identiteit:

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

Zorg dat je bent ingelogd met Azure CLI:

az login

Lokale ontwikkeling tegen SQL Server

Gebruik SQL-authenticatie met een lokale instantie.

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

Ontwikkeling van containers voor Azure SQL

Voor containers die draaien in Azure (App Service, Container Apps, AKS), gebruik een beheerde identiteit.

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

Voor containers die lokaal worden uitgevoerd en verbinding moeten maken met Azure SQL, zorg er dan voor dat de container een bron voor aanmeldingsgegevens heeft die ActiveDirectoryDefault kan gebruiken. De meest betrouwbare opties zijn:

• Installeer Azure CLI in de container en log daar in. Mount ~/.azure alleen vanaf de host als het containerimage al Azure CLI bevat en je van plan bent die credentialcache opnieuw te gebruiken.
• Geef de referenties van de service-principal op via omgevingsvariabelen zoals AZURE_CLIENT_ID, AZURE_TENANT_ID en AZURE_CLIENT_SECRET.

Gebruik vervolgens ActiveDirectoryDefault in je verbindingscode.

Ondersteunde Microsoft SQL-endpoints

De mssql-python driver maakt verbinding met alle Microsoft SQL-eindpunten:

Zie Microsoft Entra-authenticatie voor alle zeven authenticatiemodi en Support-levenscyclus voor de volledige compatibiliteitsmatrix.

Configuratie van CI-pipeline

GitHub Actions

Houd de Python-runtime in één variabele zodat je het op één plek kunt bekijken en bijwerken. Gebruik 3.x het voor snel bewegende validatiepijplijnen, of vervang het door een door de organisatie goedgekeurde exacte versie voor release-pijplijnen.

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

Voor gedeelde pijplijnen vervang je het inline tijdelijke wachtwoord door een versleuteld geheim, zet je de service-image van SQL Server vast op een digest en bewaar je de Python-versie in een door de organisatie beheerde variabele of als invoer van een herbruikbare workflow.

Azure-pipelines

Gebruik een containerresource om SQL Server als een dienst te draaien naast je testopdracht:

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

Net als bij GitHub Actions vervang je het inline placeholder-wachtwoord door een geheime variabele voordat je dit patroon buiten een disposable demo-pipeline gebruikt.

Beveiliging en geheimen

Code geen databasewachtwoorden of verbindingsreeksen in broncode of Dockerfiles. Gebruik in plaats daarvan omgevingsvariabelen en secretsbeheer.

Omgevingsvariabelen voor lokale ontwikkeling

Sla inloggegevens op in omgevingsvariabelen of een .env bestand dat is uitgesloten van broncodebeheer:

# .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"
)

Voor Docker Compose, raadpleeg een .env bestand:

services:
  app:
    build: .
    env_file: .env

CI/CD-geheimen

Gebruik in CI-pijplijnen de geheime opslag van het platform in plaats van platte tekst omgevingsvariabelen:

• GitHub Actions: Gebruik versleutelde geheimen en verwijs ernaar als ${{ secrets.SQL_PWD }}.
• Azure-pipelines: Gebruik geheime variabelen en verwijs ze als $(SQL_PWD).

Hygiëne in de toeleveringsketen van containers

Gebruik deze praktijken voor gedeelde ontwikkelaarsomgevingen en CI:

• Houd afbeeldingsreferenties op één plek, zoals een Docker ARG, een devcontainer-build of een pipeline-variabele.
• Zet gedeelde containerimages vast op basis van onveranderlijke digests in plaats van variabele tags.
• Bekijk en ververs vastgepinde digests via een goedgekeurd updateproces zoals Dependabot, Renovate, of een interne workflow voor beeldpromotie.
• Leg een lockbestand voor afhankelijkheden vast, zoals uv.lock, of gebruik gehashte requirementsbestanden voor reproduceerbare Python-installaties.
• Geef de voorkeur aan door de organisatie goedgekeurde basisafbeeldingen en interne registerspiegels wanneer je platform deze aanbiedt.

Productie: wachtwoordloze authenticatie

Voor productieworkloads tegen Azure SQL gebruik je Microsoft Entra-authenticatie met beheerde identiteit. Deze aanpak elimineert wachtwoorden volledig:

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

Voor applicaties die geheimen moeten opslaan, zoals SQL-authenticatiewachtwoorden, gebruik Azure Key Vault en haal deze tijdens runtime op.

Afhankelijkheidsbeheer met uv

uv is een snelle Python-pakketinstaller die goed werkt in CI- en containerbouwen:

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

Veelvoorkomende containerproblemen oplossen

Verwante onderwerpen

• Installeer mssql-python
• Ondersteuningslevenscyclus
• Verbindingsreeksen
• Microsoft Entra-authenticatie
• Quickstart: Herhaalbare inzetten