Kontejnerový a lokální vývoj s mssql-python

Tento průvodce se zaměřuje na nastavení prostředí pro vývojáře Python, kteří pracují s ovladačem mssql-python napříč Windows, Linuxem, macOS, Docker kontejnery, devkontejnery a CI pipeline.

Předpoklady

  • Python 3.10 nebo novější.
  • Docker Desktop (pro vývoj založený na kontejnerech).
  • Hostitel kompatibilní s x64 (Intel, AMD nebo x64 VM) pro kontejnery SQL Server Linux. Linuxové kontejnery SQL Server nepodporují hostitele ARM64.

Nástroj go-sqlcmd dokáže vytvořit SQL Server kontejner jedním příkazem. Zpracovává vyžádání image Dockeru, generování hesla, přiřazení portu a kontext připojení automaticky:

sqlcmd create mssql --accept-eula

Vytvoření kontejneru s připojenou ukázkovou databází:

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

Po vytvoření uloží kontext připojení, sqlcmd abyste se mohli dotazovat okamžitě:

sqlcmd query "SELECT @@VERSION"

Vytvořte si přihlášení do aplikace jednou a pak ho použijte ve svém Python kódu:

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

Nahraďte <database>, <app-login>, a <password> hodnotami z vašeho prostředí.

Připojte se z Pythonu pomocí údajů o připojení, které sqlcmd vypsal při vytvoření. Použijte sqlcmd config view k jejich pozdějšímu načtení:

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

Až budete hotovi, zastavte nebo odstraňte kontejner:

sqlcmd stop
sqlcmd delete

Tip

Spuštěním příkazu sqlcmd create mssql --user-database <database> vytvořte kontejner s prázdnou uživatelskou databází připravenou pro vývoj.

Lokální SQL Server z VS Code

Rozšíření SQL Server pro VS Code (ms-mssql.mssql) dokáže vytvářet lokální SQL Server kontejnery přímo z editoru:

  1. Otevřete zobrazení SQL Server na panelu aktivit.
  2. Vyberte Přidat připojení>Vytvořit místní SQL Server (nebo použijte Paletu příkazů: MS SQL: Vytvořit místní SQL Server).
  3. Zvolte verzi SQL Server a přijměte smlouvu EULA.
  4. Rozšíření načte image kontejneru, vygeneruje heslo a automaticky přidá profil připojení.

Jakmile kontejner běží, můžete procházet databáze, spouštět dotazy a spravovat objekty přímo ve VS Code před přechodem na Python kód.

Místní SQL Server s Dockerem

Pokud dáváte přednost přímé správě kontejnerů, oficiální image kontejneru SQL Server funguje se dvěma proměnnými prostředí:

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

Počkejte pár sekund a pak se připojte přes 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

Používá se MSSQL_SA_PASSWORD pro kontejnery SQL Server. Starší SA_PASSWORD proměnná je zastaralá. Heslo musí splňovat požadavky na složitost SQL Server: nejméně 8 znaků s velkými písmeny, malými písmeny, číslicemi a speciálními znaky.

Pro načtení ukázkové databáze AdventureWorks do kontejneru:

# 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

Přístup sqlcmd create mssql --using v předchozí části automaticky stahuje a obnovuje.

Dockerfile pro Python aplikace

Ponechte odkaz na základní image Pythonu na jednom místě, aby se lokální buildy, devcontainery a CI kanály nerozcházely. Pro místní experimenty dobře funguje široce podporovaný tag jako .python:3-slim Pro sdílené devcontainery, CI a produkční prostředí nahraďte tento tag schválenou imagí připnutou na digest ze seznamu povolených imagí vaší organizace.

Vytvořte minimální Dockerfile pro Python aplikaci, která se připojuje k 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"]

Vaše requirements.txt:

mssql-python>=1.12.0

Sestavení a spuštění:

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

Ve sdílených prostředích předáme schválenou neměnnou referenci základního obrazu pomocí --build-arg PYTHON_BASE=python:3-slim@sha256:<approved-digest>.

Note

Použijte v Docker Desktopu (Windows a macOS) host.docker.internal pro přístup k serveru SQL Server na hostitelském počítači. V Linuxu použijte --network host místo toho.

Alpine Linux

Alpine používá musl místo .glibc Nainstalujte požadované balíčky:

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

Nastavení devcontaineru

Použijte stejný soubor Dockerfile, pomocí kterého se vaše aplikace sestavuje. Tento přístup udržuje devcontainer v souladu s vaším runtime image a zabraňuje rozptýlení pevně zadaných verzí Pythonu do více souborů.

Vytvořte .devcontainer/devcontainer.json pro 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"
            ]
        }
    }
}

Pokud chcete do devcontaineru zahrnout SQL Server jako službu, použijte 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 (Složená verze):

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

Pro sdílené pracovní prostory připněte obraz služby SQL Server k schválenému digestu místo spoléhání se na plovoucí tag. Načítej MSSQL_SA_PASSWORD z lokálního .env souboru nebo tajného úložiště platformy místo toho, abys ho odevzdával do správy zdrojového kódu.

Připojte se ke službě SQL Server podle názvu:

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

Platformově specifické závislosti

Ovladač mssql-python obsahuje své nativní komponenty. Není potřeba instalovat externí správce ovladačů ODBC. Ovladač však vyžaduje malou sadu systémových knihoven na Linuxu a macOS.

Platforma Požadované balíčky Instalační příkaz
Windows Žádný Zahrnuto v kole.
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 (přes Homebrew) brew install openssl

U macOS, pokud narazíte na chyby SSL, nastavte linkerové příznaky:

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

Pro kompletní instalační instrukce viz Instalace mssql-python.

Ověřování pro vývoj

Místní vývoj proti Azure SQL

Použití ActiveDirectoryDefault pro autentizaci bez hesla. Tato možnost automaticky propojuje Azure CLI, Visual Studio, proměnné prostředí a spravovanou identitu:

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

Ujistěte se, že jste přihlášeni pomocí Azure CLI:

az login

Lokální vývoj proti SQL Server

Použijte SQL autentizaci s lokální instancí.

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

Vývoj kontejnerů pro Azure SQL

Pro kontejnery běžící v Azure (App Service, Container Apps, AKS) použijte managed identity.

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

U kontejnerů běžících lokálně a potřebujících připojení k Azure SQL se ujistěte, že kontejner má zdrojový kód přihlašovacích údajů, který ActiveDirectoryDefault lze použít. Nejspolehlivější možnosti jsou:

  • Nainstalujte Azure CLI do kontejneru a přihlaste se tam. Připojte ~/.azure z hostitele pouze v případě, že image kontejneru již obsahuje Azure CLI a chcete znovu použít tuto mezipaměť přihlašovacích údajů.
  • Poskytujte přihlašovací údaje k principu služby prostřednictvím proměnných prostředí jako AZURE_CLIENT_ID, AZURE_TENANT_ID, a AZURE_CLIENT_SECRET.

Pak použijte ActiveDirectoryDefault v kódu připojení.

Podporované Microsoft SQL endpointy

Ovladač mssql-python se připojuje ke všem Microsoft SQL endpointům:

Endpoint Autentizace
SQL Server (on-premises nebo ve VM) ověřování SQL, ověřování systému Windows
Azure SQL Database Microsoft Entra ID (doporučeno), SQL autentifikace
Azure SQL Managed Instance Microsoft Entra ID (doporučeno), SQL autentifikace
Azure Synapse Analytics (vyhrazené fondy) Microsoft Entra ID, ověřování SQL
SQL databáze v prostředí Fabric Microsoft Entra ID
Datový sklad Fabrique Microsoft Entra ID
Analytický koncový bod SQL (Lakehouse) Microsoft Entra ID
SQL analytics endpoint (zrcadlená databáze) Microsoft Entra ID

Viz Microsoft Entra autentizace pro všech sedm autentizačních režimů a Support lifecycle pro kompletní kompatibilitní matici.

Nastavení CI pipeline

GitHub Actions

Nechte Python runtime v jedné proměnné, abyste ho mohli zkontrolovat a aktualizovat na jednom místě. Použijte 3.x pro rychle se pohybující validační pipeline, nebo je nahraďte organizací schválenou přesnou verzí pro release pipeline.

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

Ve sdílených pipelinech nahraďte vložené zástupné heslo šifrovaným tajným údajem, připněte image služby SQL Server ke konkrétnímu digestu a verzi Pythonu uchovávejte v proměnné spravované organizací nebo ve vstupu znovu použitelného workflow.

Azure Pipelines

Použijte kontejnerový zdroj pro spuštění SQL Server jako služby vedle testovací úlohy:

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

Stejně jako u GitHub Actions nahraďte zástupné heslo vložené přímo v kódu proměnnou typu secret dříve, než tento vzor použijete mimo jednorázovou ukázkovou pipeline.

Zabezpečení a tajné kódy

Nezadávejte napevno hesla k databázi ani připojovací řetězce do zdrojového kódu nebo souborů Dockerfile. Používejte místo toho environmentální proměnné a správu tajemství.

Proměnné prostředí pro místní rozvoj

Ukládejte přihlašovací údaje do proměnných prostředí nebo do souboru .env , který je vyloučen ze správy zdrojového kódu:

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

Pro Docker Compose, odkazujte na .env soubor:

services:
  app:
    build: .
    env_file: .env

Caution

Nikdy neukládejte soubory .env do správy zdrojových kódů. Přidejte .env do .gitignore souboru.

Tajemství CI/CD

V CI pipelinách používejte úložiště tajných údajů platformy namísto proměnných prostředí uložených v prostém textu:

Hygiena dodavatelského řetězce kontejnerů

Použijte tyto postupy pro sdílená vývojářská prostředí a CI:

  • Uchovávejte reference na image na jednom místě, například v souboru Docker ARG, v sestavení devcontaineru nebo v proměnné kanálu.
  • Připněte sdílené obrázky kontejnerů do neměnných digestů místo plovoucích tagů.
  • Zkontrolujte a obnovte připnuté digesty prostřednictvím schváleného aktualizačního procesu, jako je Dependabot, Renovate, nebo interního workflow pro propagaci obrázků.
  • Zahrňte do repozitáře soubor pro uzamčení závislostí, například uv.lock, nebo použijte hashované soubory požadavků pro reprodukovatelné instalace Pythonu.
  • Preferujte základní obrázky schválené organizací a interní zrcadla registru, pokud je vaše platforma poskytuje.

Produkce: autentizace bez hesla

Pro produkční úlohy pro Azure SQL použijte ověřování Microsoft Entra pomocí spravované identity. Tento přístup zcela eliminuje hesla:

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

Pro aplikace, které potřebují uchovávat tajemství, jako jsou hesla pro ověřování SQL, použijte Azure Key Vault a načítejte je za běhu.

Správa závislostí pomocí UV

UV je rychlý instalátor Python balíčků, který dobře funguje v CI a kontejnerových buildech:

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

V CI:

pip install uv
uv sync
uv run pytest

Řešení běžných problémů s kontejnery

Příznak Příčina Opravit
ImportError: libltdl.so.7 Chybí systémová knihovna. Nainstalujte libltdl7 (Debian) nebo libltdl (Alpine).
ImportError: libkrb5.so.3 Chybějící knihovna Kerberos. Instalace libkrb5-3 (Debian) nebo krb5-libs (Alpine/RHEL).
SSL: CERTIFICATE_VERIFY_FAILED Samopodepsaný certifikát na lokálním SQL Server. Přidejte trust_server_certificate="yes" k propojení. Nepoužívej to ve výrobě.
Připojení odmítnuto na portu 1433 SQL Server kontejner není připravený. Přidejte kontrolu stavu nebo počkejte, než se služba spustí.
Login failed for user 'sa' Heslo nesplňuje požadavky na složitost. Používejte heslo s velkými, malými písmeny, číslicemi a speciálními znaky.
Cannot open database Databáze ještě neexistuje. Vytvořte nebo obnovit databázi před připojením.
Pomalé první připojení v kontejneru Překlad DNS nebo spouštění řetězce přihlašovacích údajů. Pro lokální SQL Server použijte localhost,1433 místo názvu hostitele. Pro Azure SQL se předem ověřte pomocí az login.

Související obsah

  • Last updated on