Container- och lokal utveckling med mssql-python

Denna guide täcker miljöuppsättning för Python-utvecklare som arbetar med drivrutinen mssql-python över Windows, Linux, macOS, Docker-containrar, devcontainers och CI-pipelines.

Förutsättningar

  • Python 3.10 eller senare.
  • Docker Desktop (för containerbaserad utveckling).
  • En x64-kompatibel värd (Intel, AMD eller x64 VM) för SQL Server Linux-containrar. SQL Server Linux-containrar stöder inte ARM64-värdar.

Go-sqlcmd-verktyget kan skapa en SQL Server-container i ett enda kommando. Den hanterar Automatiskt Docker-avbildningshämtning, lösenordsgenerering, porttilldelning och anslutningskontext:

sqlcmd create mssql --accept-eula

Så här skapar du en container med en exempeldatabas som redan är ansluten:

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

Efter att sqlcmd har skapats lagrar den anslutningskontexten så att du kan fråga direkt:

sqlcmd query "SELECT @@VERSION"

Skapa en applikationsinloggning en gång, använd den sedan i din Python-kod:

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

Ersätt <database>, <app-login>, och <password> med värden från din omgivning.

Anslut från Python med anslutningsdetaljerna som sqlcmd visade när den skapades. Använd sqlcmd config view för att hämta dem senare:

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

När du är klar stoppar eller tar du bort containern:

sqlcmd stop
sqlcmd delete

Tip

Kör sqlcmd create mssql --user-database <database> för att skapa en container med en tom användardatabas som är redo för utveckling.

Lokal SQL Server från VS Code

SQL Server-tillägget för VS Code (ms-mssql.mssql) kan skapa lokala SQL Server-containrar direkt från editorn:

  1. Öppna vyn SQL Server i aktivitetsfältet.
  2. Välj Lägg till anslutning>Skapa lokal SQL Server (eller använd kommandopaletten: MS SQL: Skapa lokal SQL Server).
  3. Välj den SQL Server versionen och godkänn serviceavtalet.
  4. Tillägget hämtar containeravbildningen, genererar ett lösenord och lägger till en anslutningsprofil automatiskt.

När containern körs kan du bläddra i databaser, köra frågor och hantera objekt direkt i VS Code innan du byter till Python-kod.

Lokal SQL Server med Docker

Om du föredrar att hantera containrar direkt fungerar den officiella SQL Server containeravbildningen med två miljövariabler:

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

Vänta några sekunder, sedan ansluter du från 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()

Important

Använd MSSQL_SA_PASSWORD för SQL Server containers. Den äldre SA_PASSWORD variabeln är inaktuell. Lösenordet måste uppfylla SQL Server komplexitetskrav: minst 8 tecken, med versaler, gemener, siffror och specialtecken.

För att ladda AdventureWorks exempeldatabas i containern:

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

Tip

Metoden sqlcmd create mssql --using i föregående avsnitt hanterar nedladdning och återställning automatiskt.

Dockerfile för Python-applikationer

Håll referensen till Python-basavbildningen samlad på ett ställe så att lokala byggen, devcontainers och CI-pipelines inte glider isär. För lokal experimentering fungerar en bred stödd tagg som för eksempel python:3-slim bra. För delade devcontainers, CI och produktion, ersätt taggen med en godkänd digest-fastnålad bild från organisationens tillåten-lista.

Skapa en minimal Dockerfile för en Python-applikation som ansluter till 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"]

Din requirements.txt:

mssql-python>=1.11.0

Skapa och kör:

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

I delade miljöer, skicka en godkänd oföränderlig basbildreferens med --build-arg PYTHON_BASE=python:3-slim@sha256:<approved-digest>.

Note

Använd host.docker.internal på Docker Desktop (Windows och macOS) för att nå en SQL Server på värddatorn. I Linux använder du --network host i stället.

Alpine Linux

Alpina använder musl istället för glibc. Installera de paket som krävs:

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

Återanvänd samma Dockerfile som din applikation bygger med. Detta tillvägagångssätt håller devcontainern justerad med din runtime-image och förhindrar att Python-versionens pinnar sprids över flera filer.

Skapa en .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"
            ]
        }
    }
}

Om du vill inkludera SQL Server som en tjänst i devcontainer använder du 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 delade arbetsytor, fäst SQL Server-tjänstebilden i en godkänd digest istället för att förlita dig på en flytande tagg. Ladda MSSQL_SA_PASSWORD från en lokal .env-fil eller plattformens hemlighetslagring i stället för att checka in den i versionshanteringen.

Anslut dig till SQL Server-tjänsten med namn:

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

Plattformsspecifika beroenden

Drivrutinen mssql-python paketerar sina inbyggda komponenter. Du behöver inte installera en extern ODBC-drivrutinshanterare. Drivrutinen kräver dock en liten uppsättning systembibliotek på Linux och macOS.

Platform Nödvändiga paket Installationskommando
Windows None Ingår med hjulet.
Ubuntu/Debian libltdl7, libkrb5-3, libgssapi-krb5-2 sudo apt-get install libltdl7 libkrb5-3 libgssapi-krb5-2
Red Hat / CentOS / Fedora libtool-ltdl, krb5-libs sudo dnf install libtool-ltdl krb5-libs
Alpine libltdl, krb5-libs apk add libltdl krb5-libs
macOS OpenSSL (via Homebrew) brew install openssl

För macOS, om du stöter på SSL-fel, ställ in länkarflaggorna:

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

För fullständiga installationsinstruktioner, se Installera mssql-python.

Autentisering för utveckling

Lokal utveckling mot Azure SQL

Använd ActiveDirectoryDefault för lösenordslös autentisering. Detta alternativ kedjas automatiskt genom Azure CLI, Visual Studio, miljövariabler och hanterad identitet:

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

Se till att du är inloggad med Azure CLI:

az login

Lokal utveckling mot SQL Server

Använd SQL-autentisering med en lokal instans.

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

Containerutveckling mot Azure SQL

För containrar som körs i Azure (App Service, Container Apps, AKS), använd managed identity.

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

För containrar som körs lokalt och behöver ansluta till Azure SQL, se till att containern har en legitimationskälla som ActiveDirectoryDefault kan användas. De mest pålitliga alternativen är:

  • Installera Azure CLI i containern och logga in där. Montera ~/.azure från värden endast om containeravbilden redan innehåller Azure CLI och du avser att återanvända den autentiseringscachen.
  • Tillhandahålla tjänsteprincipautentisering via miljövariabler som AZURE_CLIENT_ID, AZURE_TENANT_ID, och AZURE_CLIENT_SECRET.

Använd sedan ActiveDirectoryDefault i din anslutningskod.

Microsoft SQL-slutpunkter som stöds

Drivrutinen mssql-python ansluter till alla Microsoft SQL-endpoints:

Endpoint Authentication
SQL Server (lokalt eller i en virtuell maskin) SQL-autentisering, Windows-autentisering
Azure SQL Database Microsoft Entra ID (rekommenderas), SQL-autentisering
Hanterad instans i Azure SQL Microsoft Entra ID (rekommenderas), SQL-autentisering
Azure Synapse Analytics (dedikerade pooler) Microsoft Entra ID, SQL-autentisering
SQL-databasen i Fabric Microsoft Entra ID
Fabric-datalager Microsoft Entra ID
SQL-analysändpunkt (Lakehouse) Microsoft Entra ID
SQL-analysslutpunkt (speglad databas) Microsoft Entra ID

Se Microsoft Entra-autentisering för alla sju autentiseringslägen och Support Lifecycle för hela kompatibilitetsmatrisen.

Konfiguration av CI-pipeline

GitHub Actions

Håll Python-runtimen i en variabel så att du kan granska och uppdatera den på ett ställe. Använd 3.x för snabbrörliga valideringspipelines, eller ersätt den med en organisationsgodkänd exakt version för releasepipelines.

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 delade pipelines, ersätt det inbyggda platshållarlösenordet med en krypterad hemlighet, fäst SQL Server-tjänstebilden i en digest och behåll Python-versionen i en organisationshanterad variabel eller återanvändbar arbetsflödesinmatning.

Azure-pipelines

Använd en containerresurs för att köra SQL Server som en tjänst tillsammans med ditt testjobb:

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

Precis som med GitHub Actions bör du ersätta platshållarlösenordet som anges direkt i koden med en hemlig variabel innan du använder det här mönstret utanför en tillfällig demopipeline.

Säkerhet och hemligheter

Hårdkoda inte databaslösenord eller anslutningssträngar i källkoden eller Dockerfiles. Använd istället miljövariabler och hemlighetshantering.

Miljövariabler för lokal utveckling

Lagra referensuppgifter i miljövariabler eller en .env fil som är undantagen från versionskontroll:

# .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, referera till en .env fil:

services:
  app:
    build: .
    env_file: .env

Caution

Checka aldrig in .env-filer i versionshanteringen. Lägg till .env i .gitignore filen.

CI/CD-hemligheter

I CI-pipelines använder du plattformens hemliga lagring istället för klartextmiljövariabler:

Hygien i container-leveranskedjan

Använd dessa metoder för delade utvecklarmiljöer och CI:

  • Spara bildreferenser på ett ställe, som en Docker ARG, en devcontainer-build eller en pipeline-variabel.
  • Fäst delade containerbilder till oföränderliga digests istället för flytande taggar.
  • Gå igenom och uppdatera fastnålade sammanfattningar genom en godkänd uppdateringsprocess såsom Dependabot, Renovate eller ett internt arbetsflöde för bildmarknadsföring.
  • Lägg till en låsfil för beroenden, till exempel uv.lock, eller använd hashade kravfiler för reproducerbara Python-installationer.
  • Föredra företagsgodkända basbilder och interna registerspegelbilder när din plattform tillhandahåller dem.

Produktion: lösenordslös autentisering

För produktionsarbetsbelastningar mot Azure SQL, använd Microsoft Entra-autentisering med hanterad identitet. Denna metod eliminerar lösenord helt:

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

För applikationer som behöver lagra hemligheter som SQL-autentiseringslösenord, använd Azure Key Vault och hämta dem vid körning.

Beroendehantering med UV

uv är en snabb Python-paketinstallatör som fungerar bra i CI- och containerbyggen:

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

I CI:

pip install uv
uv sync
uv run pytest

Felsöka vanliga containerproblem

Symptom Orsak Reparera
ImportError: libltdl.so.7 Saknad systembibliotek. Installera libltdl7 (Debian) eller libltdl (Alpine).
ImportError: libkrb5.so.3 Saknar Kerberos-biblioteket. Installera libkrb5-3 (Debian) eller krb5-libs (Alpine/RHEL).
SSL: CERTIFICATE_VERIFY_FAILED Självsignerat certifikat på lokal SQL Server. Lägg till trust_server_certificate="yes" i anslutningen. Använd inte detta i produktionen.
Anslutning nekad på port 1433 SQL Server containern är inte klar. Lägg till en hälsokontroll eller vänta tills tjänsten startas.
Login failed for user 'sa' Lösenordet uppfyller inte komplexitetskraven. Använd ett lösenord med versaler, gemener, siffror och specialtecken.
Cannot open database Databasen finns inte än. Skapa eller återställ databasen innan du ansluter upp.
Långsam första anslutning i container Start av DNS-matchning eller autentiseringskedja. För lokal SQL Server, använd localhost,1433 istället för värdnamn. För Azure SQL, förautentisera med az login.

Relaterat innehåll

  • Last updated on