Konténer és helyi fejlesztés mssql-pythonnal

Ez az útmutató a környezet beállítását mutatja be Python fejlesztők számára, akik az mssql-python illesztőprogramdal dolgoznak Windows, Linux, macOS, Docker konténerek, devcontainerek és CI pipeline-ok között.

Prerequisites

• Python 3.10 vagy újabb verzió.
• Docker Desktop (konténeralapú fejlesztéshez).
• Egy x64-kompatibilis haszt (Intel, AMD vagy x64 VM) SQL Server Linux konténerekhez. Az SQL Server Linux konténerei nem támogatják az ARM64 hosztokat.

Helyi SQL Server sqlcmd használatával (ajánlott)

A go-sqlcmd segédprogram egyetlen parancs alatt képes létrehozni egy SQL Server konténert. Automatikusan kezeli a Docker-rendszerkép lekérését, a jelszógenerálást, a porthozzárendelést és a kapcsolati környezetet:

sqlcmd create mssql --accept-eula

Tároló létrehozása már csatolt mintaadatbázissal:

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

A létrehozás után tárolja a kapcsolati környezetet, sqlcmd hogy azonnal lekérdezhesse:

sqlcmd query "SELECT @@VERSION"

Egyszer hozz létre egy alkalmazásbejelentkezést, majd használd a Python kódodban:

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

Helyettesítsd a(z) <database>, <app-login> és <password> elemeket a környezetedből származó értékekkel.

Csatlakozz Pythonból a létrehozáskor a sqlcmd által kiírt kapcsolódási adatokkal. Használja a(z) sqlcmd config view elemet a későbbi lekéréshez:

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

Amikor végzett, állítsa le vagy törölje a konténert:

sqlcmd stop
sqlcmd delete

Jótanács

Üres felhasználói adatbázissal rendelkező, fejlesztésre kész konténer létrehozásához futtassa a(z) sqlcmd create mssql --user-database <database> parancsot.

Helyi SQL Server a VS Code-ból

Az SQL Server kiterjesztése VS Code-hoz (ms-mssql.mssql) közvetlenül a szerkesztőből képes helyi SQL Server konténereket létrehozni:

1. Nyissa meg a SQL Server nézetet a tevékenységsávon.
2. Válassza a Kapcsolat hozzáadása>Helyi SQL Server létrehozása lehetőséget (vagy használja a Parancspalettát: MS SQL: Helyi SQL Server létrehozása).
3. Válassza ki a SQL Server verziót, és fogadja el az EULA-t.
4. A bővítmény lekéri a tárolórendszerképet, létrehoz egy jelszót, és automatikusan hozzáad egy kapcsolatprofilt.

Miután a konténer elindul, VS Code-ban böngészhetsz adatbázisokat, lekérdezéseket futtathatsz és objektumokat kezelhetsz, mielőtt Python kódra váltasz.

Helyi SQL Server a Dockerrel

Ha inkább közvetlenül szeretné kezelni a tárolókat, a hivatalos SQL Server tárolórendszerkép két környezeti változóval működik:

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árj pár másodpercet, majd csatlakozz Python-ról:

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

SQL Server tárolókhoz használhatóMSSQL_SA_PASSWORD. A régebbi SA_PASSWORD változó elavult. A jelszónak meg kell felelnie SQL Server összetettségi követelményeknek: legalább 8 karakter, nagybetűvel, kisbetűvel, számjegyekkel és speciális karakterekkel.

Az AdventureWorks mintaadatbázis betöltéséhez a konténerbe:

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

Jótanács

Az sqlcmd create mssql --using előző szakaszban szereplő megközelítés automatikusan kezeli a letöltést és visszaállítást.

Dockerfile Python alkalmazásokhoz

Tartsd a Python alapkép hivatkozását egy helyen, hogy a helyi buildek, a fejlesztői konténerek és a CI-folyamatok ne térjenek el egymástól. Helyi kísérletezéshez egy széles, támogatott címke, például python:3-slim jól működik. Megosztott devcontainerek, CI és produkciós környezet esetében cseréld le ezt a címkét a szervezeted engedélyezési listáján szereplő, jóváhagyott, digesttel rögzített rendszerképre.

Minimális Dockerfile létrehozása egy Python alkalmazáshoz, amely csatlakozik a Microsoft SQL-hez:

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

Az Ön requirements.txt:

mssql-python>=1.11.0

Építés és futtatás:

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

Megosztott környezetekben a --build-arg PYTHON_BASE=python:3-slim@sha256:<approved-digest> használatával egy jóváhagyott, módosíthatatlan alapképre mutató hivatkozást kell megadni.

Megjegyzés:

A Docker Desktopben (Windows és macOS rendszeren) a host.docker.internal használatával érheti el a gazdagépen futó SQL Servert. Linuxon használja --network host inkább.

Alpine Linux

Az Alpine musl használ glibc helyett. Telepítse a szükséges csomagokat:

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 beállítása

Használd újra ugyanazt a Dockerfile-t, amivel az alkalmazásod épít. Ez a megközelítés összhangban tartja a devcontainert a futtatókörnyezeti lemezképpel, és megakadályozza, hogy a Python-verziórögzítések több fájlban legyenek szétszórva.

Hozz létre egy .devcontainer/devcontainer.json a VS Code-hoz:

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

Ha szolgáltatásként SQL Server szeretne szerepelni a devcontainerben, használja a Docker Compose-t:

.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 verzió):

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

Megosztott munkaterületek esetén rögzítsd az SQL Server szolgáltatási képét egy jóváhagyott digest-hez a lebegő címkék helyett. A(z) MSSQL_SA_PASSWORD elemet helyi .env fájlból vagy a platform titoktárolójából töltsd be ahelyett, hogy a forráskódkezelőbe helyeznéd.

Csatlakozz az SQL Server szolgáltatáshoz név szerint:

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

Platformspecifikus függőségek

A mssql-python meghajtó a natív komponenseit csomagolja. Nem kell külső ODBC driver managert telepíteni. Azonban az illesztőprogramhoz egy kis rendszerkönyvtári készlet szükséges Linux és macOS rendszerre.

Plattform	Szükséges csomagok	Parancs telepítése
Windows	None	A kerékben van.
Ubuntu / Debian	\, \, \	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 (Homebrew révén)	brew install openssl

MacOS esetén, ha SSL hibákkal találkozol, állítsd be a linker zászlókat:

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

A teljes telepítési utasításokért lásd: Install mssql-python.

Hitelesítés fejlesztéshez

Helyi fejlesztés Azure SQL használatával

Jelszó nélküli hitelesítéshez használjuk ActiveDirectoryDefault . Ez a beállítás automatikusan végighalad az Azure CLI-n, a Visual Studión, a környezeti változókon és a felügyelt identitáson:

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

Győződj meg róla, hogy Azure CLI-vel vagy bejelentkezve:

az login

Helyi fejlesztés az SQL Server ellen

Használj SQL hitelesítést egy helyi példánynál.

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

Konténerfejlesztés Azure SQL-hez

Az Azure-ban futó konténerek esetén (App Service, Container Apps, AKS) használj menedzselt identitást.

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

Azoknál a konténereknél, amelyek helyben futnak, és Azure SQL-hez kell csatlakozniuk, győződj meg róla, hogy a konténernek van egy használható hitelesítő forrásaActiveDirectoryDefault. A legmegbízhatóbb lehetőségek a következők:

• Telepítsd az Azure CLI-t a konténerbe, és jelentkezz be ott. A hostról csak akkor csatold fel a ~/.azure elemet, ha a konténerkép már tartalmazza az Azure CLI-t, és ezt a hitelesítési gyorsítótárat újra kívánod használni.
• Szolgáltatásfő hitelesítéseket biztosíts környezeti változókkal, mint AZURE_CLIENT_ID, AZURE_TENANT_ID, és AZURE_CLIENT_SECRET.

Ezután használd a(z) ActiveDirectoryDefault elemet a kapcsolatkódban.

Támogatott Microsoft SQL végpontok

Az illezőgép mssql-python minden Microsoft SQL végponthoz csatlakozik:

Endpoint	Authentication
SQL Server (on-premises vagy VM-ben)	SQL-hitelesítés, Windows-hitelesítés
Azure SQL Database	Microsoft Entra ID (ajánlott), SQL-hitelesítés
Azure SQL Managed Instance	Microsoft Entra ID (ajánlott), SQL-hitelesítés
Azure Synapse Analytics (dedikált készletek)	Microsoft Entra ID, SQL-hitelesítés
SQL-adatbázis a Fabricben	Microsoft Entra ID
Fabric adattárház	Microsoft Entra ID
SQL-elemzési végpont (Lakehouse)	Microsoft Entra ID
SQL-elemzési végpont (tükrözött adatbázis)	Microsoft Entra ID

Lásd a Microsoft Entra hitelesítést mind a hét hitelesítési módhoz, valamint a Támogató életciklust a teljes kompatibilitási mátrixhoz.

CI-folyamat konfigurálása

GitHub Actions

Tartsd a Python futóidőt egy változóban, hogy egy helyen átnézhesd és frissíthesd. Gyorsan változó validációs pipeline-okhoz használd a 3.x elemet, vagy helyettesítsd a szervezet által jóváhagyott konkrét verzióval a kiadási pipeline-okhoz.

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

Megosztott pipeline-ok esetén cseréld le a beágyazott helyőrző jelszót egy titkosított bizalmas értékre, rögzítsd az SQL Server-szolgáltatás lemezképét egy konkrét digeszthez, és a Python-verziót tartsd egy szervezet által kezelt változóban vagy egy újrahasználható munkafolyamat bemeneteként.

Azure Pipelines

Használj egy konténer erőforrást, hogy az SQL Server szolgáltatásként futtasd a tesztfeladatod mellett:

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

A GitHub Actions esetében is cseréld le a soron belüli helyőrző jelszót egy titkos változóval, mielőtt ezt a mintát egy eldobható demófolyamaton kívül használnád.

Biztonság és titkos kódok

Ne kódolj adatbázis-jelszavakat vagy kapcsolati stringeket a forráskódban vagy a Dockerfiles-ban. Használj inkább környezeti változókat és titkkezelést.

Környezeti változók a helyi fejlődéshez

Tárolja a hitelesítő adatokat környezeti változókban vagy egy, a verziókezelésből kizárt .env fájlban:

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

Docker Compose-hoz hivatkozz egy .env fájlra:

services:
  app:
    build: .
    env_file: .env

Caution

Soha ne véglegesítse .env a fájlokat a forrásvezérlőben. Adja hozzá a .env elemet a .gitignore fájljához.

CI/CD hitelesítési adatok

A CI vezetékekben a platform titkos tárolóját használjuk a tiszta szöveges környezeti változók helyett:

• GitHub Actions:Használj titkosított titkokat és hivatkozz rájuk .${{ secrets.SQL_PWD }}
• Azure Pipelines:Titkos változókat használjunk, és hivatkozz rájuk .$(SQL_PWD)

Konténer-ellátási lánc higiénia

Ezeket a gyakorlatokat használd megosztott fejlesztői környezetekhez és CI-hez:

• Tartsd a képhivatkozásokat egy helyen, például egy Dockerben ARG, egy devcontainer buildben vagy egy pipeline változóban.
• Rögzítsd a megosztott konténerlemezképeket változhatatlan digesztekhez a lebegő tagek helyett.
• Vizsgáld felül és frissítsd a rögzített digeste-ket egy jóváhagyott frissítési folyamat, például a Dependabot, a Renovate vagy egy belső image-promóciós munkafolyamat segítségével.
• Kötelez egy függőségi zár fájlt, például uv.lock, vagy használj hashelt követelményfájlokat reprodukálható Python telepítésekhez.
• A szervezet által jóváhagyott alapképeket és belső regiszter tükörképeket részesítse előnyben, ha a platformod biztosítja azokat.

Gyártás: jelszó nélküli hitelesítés

Azure SQL elleni termelési munkaterhelésekhez használd a Microsoft Entra hitelesítést menedzselt identitással. Ez a megközelítés teljesen megszünteti a jelszavakat:

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

Azoknál az alkalmazásoknál, amelyeknek titkokat kell tárolniuk, például SQL hitelesítési jelszavakat, használd az Azure Key Vault-t, és keresd le őket futáskor.

Függőségkezelés uv-val

uv egy gyors Python csomagtelepítő, amely jól működik CI és konténer építésekben:

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

CI-ben:

pip install uv
uv sync
uv run pytest

A tárolóval kapcsolatos gyakori problémák elhárítása

Tünet	A probléma oka	Kijavítás
ImportError: libltdl.so.7	Hiányzó rendszerkönyvtár.	Telepítse a(z) libltdl7-t (Debian) vagy a(z) libltdl-et (Alpine).
ImportError: libkrb5.so.3	Hiányzó Kerberos könyvtár.	Telepítsd libkrb5-3 (Debian) vagy krb5-libs (Alpine/RHEL).
SSL: CERTIFICATE_VERIFY_FAILED	Önként aláírt tanúsítvány helyi SQL Server-en.	Adja hozzá a(z) trust_server_certificate="yes" elemet a kapcsolathoz. Ne használd ezt a produkcióban.
A kapcsolat megtagadva az 1433-as porton	SQL Server tároló nem áll készen.	Adjon hozzá állapotellenőrzést, vagy várja meg, amíg a szolgáltatás elindul.
Login failed for user 'sa'	A jelszó nem felel meg a bonyolultsági követelményeknek.	Használj jelszót nagybetűkkel, kisbetűkkel, számjegyekkel és speciális karakterekkel.
Cannot open database	Az adatbázis még nem létezik.	Létrehozza vagy állítsa vissza az adatbázist a csatlakozás előtt.
Lassú első kapcsolat a tárolóban	DNS-feloldás vagy hitelesítőadat-lánc indítása.	Helyi SQL Server esetén használd localhost,1433 a hostname helyett. Az Azure SQL-hez hitelesítsen előre a(z) az login használatával.

Kapcsolódó tartalom

• Install mssql-python
• Támogatási életciklus
• Kapcsolati karakterláncok
• Microsoft Entra-hitelesítés
• Gyorsindítás: Ismételhető telepítések