mssql-python ile konteyner ve yerel geliştirme

Bu rehber, Windows, Linux, macOS, Docker konteynerleri, devcontainerlar ve CI boru hatları arasında sürücüyle mssql-python çalışan Python geliştiricileri için ortam kurulumunu kapsar.

Prerequisites

  • Python 3.10 veya üzeri.
  • Docker Desktop (konteyner tabanlı geliştirme için).
  • SQL Server Linux konteynerleri için x64 uyumlu bir ana bilgisayar (Intel, AMD veya x64 VM). SQL Server Linux konteynerleri ARM64 ana bilgisayarlarını desteklemiyor.

Go-sqlcmd aracı, tek bir komutla bir SQL Server konteyneri oluşturabilir. Docker görüntüsü çekme, parola oluşturma, bağlantı noktası ataması ve bağlantı bağlamını otomatik olarak işler:

sqlcmd create mssql --accept-eula

Önceden bağlanmış örnek bir veritabanına sahip bir kapsayıcı oluşturmak için:

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

Oluşturma işleminden sonra bağlantı sqlcmd bağlamını depolar, böylece hemen sorgulayabilirsiniz:

sqlcmd query "SELECT @@VERSION"

Bir kez uygulama girişi oluşturun, sonra Python kodunda kullanın:

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

<database>, <app-login> ve <password> öğelerini ortamınızdaki değerlerle değiştirin.

Oluşturulma sırasında basılan bağlantı detaylarını sqlcmd kullanarak Python'dan bağlanın. sqlcmd config view öğesini bunları daha sonra geri almak için kullanın:

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

İşiniz bittiğinde kapsayıcıyı durdurun veya silin:

sqlcmd stop
sqlcmd delete

Tip

Geliştirmeye hazır, boş bir kullanıcı veritabanına sahip bir konteyner oluşturmak için sqlcmd create mssql --user-database <database> komutunu çalıştırın.

VS Code'dan Yerel SQL Server

VS Code için SQL Server uzantısı (ms-mssql.mssql), düzenleyiciden doğrudan yerel SQL Server konteynerleri oluşturabilir:

  1. Etkinlik Çubuğu'nda SQL Server görünümünü açın.
  2. Bağlantı> EkleYerel SQL Server Oluştur'u seçin (veya Komut Paleti: MS SQL: Yerel SQL Server Oluştur'u kullanın).
  3. SQL Server sürümünü seçin ve EULA'yı kabul edin.
  4. Uzantı kapsayıcı görüntüsünü çeker, bir parola oluşturur ve otomatik olarak bir bağlantı profili ekler.

Konteyner çalışırken veritabanlarını gezdirebilir, sorgular çalıştırabilir ve nesneleri doğrudan VS Code'da yönetebilir, sonra Python koduna geçebilirsiniz.

Docker ile yerel SQL Server

Kapsayıcıları doğrudan yönetmeyi tercih ediyorsanız, resmi SQL Server kapsayıcı görüntüsü iki ortam değişkeniyle çalışır:

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

Birkaç saniye bekleyin, sonra Python'dan bağlanın:

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 kapsayıcılar için kullanınMSSQL_SA_PASSWORD. Eski SA_PASSWORD değişken kullanım dışıdır. Parolanın SQL Server karmaşıklık gereksinimlerini karşılaması gerekir: büyük harf, küçük harf, rakam ve özel karakter içeren en az 8 karakter.

AdventureWorks örnek veritabanını konteynere yüklemek için:

# 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

Önceki bölümdeki sqlcmd create mssql --using yaklaşım indirme ve geri yüklemeyi otomatik olarak yönetir.

Python uygulamaları için Dockerfile

Python temel görüntü referansını tek bir yerde tutun ki yerel derlemeler, devcontainer'lar ve CI pipeline'lar kaymasın. Yerel denemeler için, örneğin python:3-slim geniş destekli bir etiket iyi çalışır. Paylaşılan devcontainer’lar, CI ve üretim ortamları için bu etiketi kuruluşunuzun izin verilenler listesindeki onaylanmış, digest’e sabitlenmiş bir imajla değiştirin.

Microsoft SQL'e bağlanan bir Python uygulaması için minimal bir Dockerfile oluşturun:

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

requirements.txtnız:

mssql-python>=1.11.0

Derleme ve çalıştırma:

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

Paylaşılan ortamlarda, --build-arg PYTHON_BASE=python:3-slim@sha256:<approved-digest> ile onaylanmış değiştirilemez bir temel imaj referansı iletin.

Note

Ana makinedeki bir SQL Server’a ulaşmak için Docker Desktop’ta (Windows ve macOS) host.docker.internal kullanın. Linux'ta bunun yerine kullanın --network host .

Alpine Linux

Alpine, glibc yerine musl kullanır. Gerekli paketleri yükleyin:

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 kurulumu

Uygulamanızın oluşturduğu aynı Dockerfile'ı tekrar kullanın. Bu yaklaşım, devcontainer'ı çalışma zamanında görselinizle hizalanmış tutar ve Python sürüm pinlerinin birden fazla dosya arasında dağılmasını engeller.

VS Code için bir .devcontainer/devcontainer.json oluşturun:

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

SQL Server devcontainer'a hizmet olarak eklemek için Docker Compose'u kullanın:

.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 (Oluşturma sürümü):

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

Paylaşılan çalışma alanları için, SQL Server hizmet görüntüsünü değişken bir etikete güvenmek yerine onaylanmış bir digest'e sabitleyin. Kaynak denetimine eklemek yerine, MSSQL_SA_PASSWORD öğesini yerel bir .env dosyasından veya platformun gizli deposundan yükleyin.

SQL Server hizmetine isimle bağlanın:

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

Platforma özgü bağımlılıklar

mssql-python sürücü, yerel bileşenleriyle birlikte gelir. Harici bir ODBC sürücü yöneticisi kurmanıza gerek yok. Ancak, sürücü Linux ve macOS'ta küçük bir sistem kütüphanesi seti gerektirir.

Platform Gerekli paketler Yükle komutu
Windows Hiçbiri Tekerleğe dahildir.
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 (Homebrew aracılığıyla) brew install openssl

macOS için, SSL hatalarıyla karşılaşırsanız, linker bayraklarını ayarlayın:

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

Tam kurulum talimatları için mssql-python'u Install (mssql-python'u Kurul) bölümüne bakınız.

Geliştirme için kimlik doğrulaması

Azure SQL karşı yerel geliştirme

Şifresiz kimlik doğrulama için kullanın ActiveDirectoryDefault . Bu seçenek, Azure CLI, Visual Studio, ortam değişkenleri ve yönetilen kimlik üzerinden otomatik olarak zincirlenir:

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

Azure CLI kullanarak giriş yaptığınızdan emin olun:

az login

SQL Server'a karşı yerel geliştirme

Yerel bir örnekle SQL kimlik doğrulaması kullanın.

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

Azure SQL’e yönelik kapsayıcı geliştirme

Azure'da çalışan konteynerler için (App Service, Container Apps, AKS) yönetilen kimlik kullanın.

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

Yerel olarak çalışan ve Azure SQL'e bağlanması gereken konteynerler için, konteynerin kullanabileceği bir kimlik kaynağı ActiveDirectoryDefault olduğundan emin olun. En güvenilir seçenekler şunlardır:

  • Azure CLI'yi konteynere kur ve oraya giriş yap. Sadece konteyner görüntüsü zaten Azure CLI'yı içeriyorsa ve o credential önbelleğini tekrar kullanmayı düşünüyorsanız ana bilgisayardan monte ~/.azure edin.
  • Hizmet sorumlusu kimlik bilgilerini AZURE_CLIENT_ID, AZURE_TENANT_ID ve AZURE_CLIENT_SECRET gibi ortam değişkenleri aracılığıyla sağlayın.

Ardından ActiveDirectoryDefault öğesini bağlantı kodunuzda kullanın.

Desteklenen Microsoft SQL uç noktaları

Sürücü, mssql-python tüm Microsoft SQL uç noktalarına bağlanır:

Bitiş noktası Authentication
SQL Server (on-premises veya VM içinde) SQL kimlik doğrulaması, Windows kimlik doğrulaması
Azure SQL Veritabanı Microsoft Entra ID (önerilen), SQL kimlik doğrulaması
Azure SQL Yönetilen Varlık Microsoft Entra ID (önerilen), SQL kimlik doğrulaması
Azure Synapse Analytics (dedicated pools) Microsoft Entra ID, SQL kimlik doğrulaması
Fabric'de SQL veritabanı Microsoft Entra Kimliği
Fabric Veri Ambarı Microsoft Entra Kimliği
SQL analiz uç noktası (Lakehouse) Microsoft Entra Kimliği
SQL analiz uç noktası (yansıtılmış veritabanı) Microsoft Entra Kimliği

Tüm yedi kimlik doğrulama modu için Microsoft Entra kimlik doğrulama ve tam uyumluluk matrisi için Destek yaşam döngüsüne bakınız.

CI işlem hattı kurulumu

GitHub Actions

Python çalışma zamanını tek bir değişkende tutun ki tek bir yerde inceleyip güncelleyebilesiniz. Hızlı ilerleyen doğrulama işlem hatları için 3.x kullanın veya yayın işlem hatlarında bunu kuruluş tarafından onaylanmış belirli bir sürümle değiştirin.

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

Paylaşılan boru hatları için, satır içi yer tutucu şifreyi şifreli bir sırla değiştirin, SQL Server servis görgesini bir digest olarak sabitleyin ve Python sürümünü organizasyon tarafından yönetilen bir değişken veya yeniden kullanılabilir iş akışı girdisinde tutun.

Azure Pipelines

Test işinizin yanında SQL Server'ı hizmet olarak çalıştırmak için bir konteyner kaynağı kullanın:

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

GitHub Actions'ta olduğu gibi, bu deseni tek kullanımlık demo pipeline dışında kullanmadan önce satır içi yer tutucu şifreyi gizli bir değişkenle değiştirin.

Güvenlik ve sırlar

Veritabanı parolalarını veya bağlantı dizelerini kaynak kodda ya da Dockerfile'larda sabit olarak kodlamayın. Bunun yerine ortam değişkenleri ve sır yönetimi kullanın.

Yerel gelişim için çevresel değişkenler

Kimlik bilgilerini ortam değişkenlerinde veya .env kaynak kontrolünden dışlanmış bir dosyada depolayın:

# .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 için bir .env dosyaya başvurun:

services:
  app:
    build: .
    env_file: .env

Caution

.env dosyaları hiçbir zaman kaynak denetimine kaydetmeyin. Dosyanıza .env ekleyin.gitignore.

CI/CD sırları

CI boru hatlarında, düz metin ortam değişkenleri yerine platformun gizli deposunu kullanın:

Konteyner tedarik zinciri hijyeni

Bu uygulamaları paylaşılan geliştirici ortamları ve CI için kullanın:

  • Görüntü referanslarını tek bir yerde tutun; örneğin bir Docker ARG, bir devcontainer derlemesi veya bir pipeline değişkeni.
  • Paylaşılan container imajlarını, değişken etiketler yerine değiştirilemez özetlere sabitleyin.
  • Sabitlenmiş digest'leri Dependabot, Renovate veya dahili bir imaj yükseltme iş akışı gibi onaylı bir güncelleme süreci aracılığıyla gözden geçirin ve yenileyin.
  • Bir uv.lockbağımlılık kilidi dosyası gibi commit edin veya tekrarlanabilir Python kurulumları için hash gereksinim dosyalarını kullanın.
  • Platformunuz bunları sağlıyorsa kuruluş tarafından onaylanmış temel görüntüleri ve dahili kayıt deposu yansılarını tercih edin.

Üretim: şifresiz kimlik doğrulama

Azure SQL'e karşı üretim iş yükleri için, yönetilen kimlik ile Microsoft Entra authenticasyonunu kullanın. Bu yaklaşım şifreleri tamamen ortadan kaldırır:

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

SQL doğrulama şifreleri gibi sırları depolaması gereken uygulamalar için Azure Key Vault kullanın ve bunları çalışma zamanında alın.

UV ile bağımlılık yönetimi

uv, CI ve konteyner derlemelerinde iyi çalışan hızlı bir Python paket yükleyicisidir:

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'de:

pip install uv
uv sync
uv run pytest

Yaygın konteyner sorunlarını giderin

Belirti Cause Düzelt
ImportError: libltdl.so.7 Eksik sistem kütüphanesi. Kurulum libltdl7 (Debian) veya libltdl (Alpine).
ImportError: libkrb5.so.3 Kerberos kütüphanesi eksik. Kurulum libkrb5-3 (Debian) veya krb5-libs (Alpine/RHEL).
SSL: CERTIFICATE_VERIFY_FAILED Yerel SQL Server'da kendi kendine imzalanan sertifika. trust_server_certificate="yes" öğesini bağlantıya ekleyin. Bunu üretimde kullanma.
Bağlantı 1433 numaralı bağlantı noktasında reddedildi SQL Server kapsayıcı hazır değil. Sistem durumu denetimi ekleyin veya hizmetin başlatılmasını bekleyin.
Login failed for user 'sa' Şifre karmaşıklık gereksinimlerini karşılamaz. Büyük harf, küçük harfler, rakamlar ve özel karakterlerle bir şifre kullanın.
Cannot open database Veritabanı henüz yok. Bağlantı kurmadan önce veritabanını oluşturun veya geri yükleyin.
Kapsayıcıda yavaş ilk bağlantı DNS çözümlemesi veya kimlik bilgisi zinciri başlatma. Yerel SQL Server için, host adı yerine kullanınlocalhost,1433. Azure SQL için, az login ile ön kimlik doğrulaması yapın.

İlgili içerik

  • Last updated on