Pengembangan kontainer dan lokal dengan mssql-python

Panduan ini mencakup penyiapan lingkungan untuk pengembang Python yang bekerja dengan mssql-python driver di seluruh Windows, Linux, macOS, kontainer Docker, devcontainer, dan alur CI.

Prasyarat

  • Python 3.10 atau yang lebih baru.
  • Docker Desktop (untuk pengembangan berbasis kontainer).
  • Host yang kompatibel dengan x64 (Intel, AMD, atau x64 VM) untuk kontainer SQL Server Linux. Kontainer SQL Server Linux tidak mendukung host ARM64.

Utilitas go-sqlcmd dapat membuat kontainer SQL Server dalam satu perintah. Ini menangani penarikan gambar Docker, pembuatan kata sandi, penetapan port, dan konteks koneksi secara otomatis:

sqlcmd create mssql --accept-eula

Untuk membuat kontainer dengan database sampel yang sudah dilampirkan:

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

Setelah pembuatan, sqlcmd simpan konteks koneksi sehingga Anda dapat segera mengkueri:

sqlcmd query "SELECT @@VERSION"

Buat login aplikasi sekali, lalu gunakan di kode Python Anda:

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

Ganti <database>, <app-login>, dan <password> dengan nilai dari lingkungan Anda.

Hubungkan dari Python menggunakan detail koneksi yang dicetak sqlcmd saat pembuatan. Gunakan sqlcmd config view untuk mengambilnya nanti:

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

Setelah selesai, hentikan atau hapus kontainer:

sqlcmd stop
sqlcmd delete

Tip

Jalankan sqlcmd create mssql --user-database <database> untuk membuat kontainer dengan database pengguna kosong yang siap untuk pengembangan.

SQL Server Lokal dari VS Code

Ekstensi SQL Server untuk VS Code (ms-mssql.mssql) dapat membuat kontainer SQL Server lokal langsung dari editor:

  1. Buka tampilan SQL Server di Bilah Aktivitas.
  2. Pilih Tambahkan Koneksi>Buat SQL Server Lokal (atau gunakan Palet Perintah: MS SQL: Buat SQL Server Lokal).
  3. Pilih versi SQL Server dan terima EULA.
  4. Ekstensi menarik gambar kontainer, menghasilkan kata sandi, dan menambahkan profil koneksi secara otomatis.

Setelah kontainer berjalan, Anda dapat menelusuri database, menjalankan kueri, dan mengelola objek langsung di VS Code sebelum beralih ke kode Python.

SQL Server lokal dengan Docker

Jika Anda lebih suka mengelola kontainer secara langsung, gambar kontainer resmi SQL Server berfungsi dengan dua variabel lingkungan:

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

Tunggu beberapa detik, lalu sambungkan dari 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()

Penting

Gunakan MSSQL_SA_PASSWORD untuk kontainer SQL Server. Variabel lama SA_PASSWORD tidak digunakan lagi. Kata sandi harus memenuhi persyaratan kompleksitas SQL Server: setidaknya 8 karakter, dengan huruf besar, huruf kecil, digit, dan karakter khusus.

Untuk memuat database sampel AdventureWorks ke dalam kontainer:

# 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

Pendekatan sqlcmd create mssql --using di bagian sebelumnya menangani pengunduhan dan pemulihan secara otomatis.

Dockerfile untuk aplikasi Python

Simpan referensi image dasar Python di satu tempat agar build lokal, devcontainers, dan pipeline CI tetap konsisten. Untuk eksperimen lokal, tag yang didukung secara luas seperti python:3-slim berfungsi dengan baik. Untuk devcontainer, CI, dan produksi bersama, ganti tag tersebut dengan gambar yang disematkan ringkasan yang disetujui dari daftar yang diizinkan organisasi Anda.

Buat Dockerfile minimal untuk aplikasi Python yang terhubung ke 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"]

requirements.txt Anda:

mssql-python>=1.11.0

Bangun dan jalankan:

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

Dalam lingkungan bersama, sertakan referensi image dasar yang tidak berubah dan telah disetujui dengan --build-arg PYTHON_BASE=python:3-slim@sha256:<approved-digest>.

Note

Gunakan host.docker.internal di Docker Desktop (Windows dan macOS) untuk mencapai SQL Server di komputer host. Di Linux, gunakan --network host sebagai gantinya.

Alpine Linux

Alpine menggunakan musl alih-alih glibc. Instal paket yang diperlukan:

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

Menyiapkan Devcontainer

Gunakan kembali Dockerfile yang sama dengan yang digunakan aplikasi Anda. Pendekatan ini membuat devcontainer selaras dengan gambar runtime Anda dan mencegah penyebaran pin versi Python di beberapa file.

Buat .devcontainer/devcontainer.json untuk Kode VS:

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

Untuk menyertakan SQL Server sebagai layanan di devcontainer, gunakan 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 (Buat versi):

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

Untuk ruang kerja bersama, sematkan gambar layanan SQL Server ke ringkasan yang disetujui alih-alih mengandalkan tag mengambang. Muat MSSQL_SA_PASSWORD dari file lokal .env atau penyimpanan rahasia platform alih-alih memeriksanya ke dalam kontrol sumber.

Sambungkan ke layanan SQL Server berdasarkan nama:

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

Dependensi khusus platform

mssql-python Driver menggabungkan komponen aslinya. Anda tidak perlu menginstal pengelola driver ODBC eksternal. Namun, driver memerlukan sekumpulan kecil pustaka sistem di Linux dan macOS.

Platform Paket yang diperlukan Perintah instalasi
Windows None Disertakan pada roda.
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 (melalui Homebrew) brew install openssl

Untuk macOS, jika Anda mengalami error SSL, atur bendera linker:

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

Untuk instruksi penginstalan lengkap, lihat Menginstal mssql-python.

Autentikasi untuk pengembangan

Pengembangan lokal terhadap Azure SQL

Gunakan ActiveDirectoryDefault untuk autentikasi tanpa kata sandi. Opsi ini dirantai melalui Azure CLI, Visual Studio, variabel lingkungan, dan identitas terkelola secara otomatis:

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

Pastikan Anda masuk dengan menggunakan Azure CLI:

az login

Pengembangan lokal terhadap SQL Server

Gunakan autentikasi SQL dengan instans lokal.

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

Pengembangan kontainer terhadap Azure SQL

Untuk kontainer yang berjalan di Azure (App Service, Container Apps, AKS), gunakan identitas terkelola.

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

Untuk kontainer yang berjalan secara lokal yang perlu tersambung ke Azure SQL, pastikan kontainer memiliki sumber kredensial yang ActiveDirectoryDefault dapat digunakan. Opsi yang paling andal adalah:

  • Instal Azure CLI di kontainer dan masuk ke sana. Pasang ~/.azure dari host hanya jika gambar kontainer sudah menyertakan Azure CLI dan Anda bermaksud untuk menggunakan kembali cache kredensial tersebut.
  • Berikan kredensial prinsipal layanan melalui variabel lingkungan seperti AZURE_CLIENT_ID, AZURE_TENANT_ID, dan AZURE_CLIENT_SECRET.

Kemudian gunakan ActiveDirectoryDefault dalam kode koneksi Anda.

Titik akhir Microsoft SQL yang didukung

Driver mssql-python terhubung ke semua titik akhir Microsoft SQL:

Titik Akhir Authentication
SQL Server (lokal atau di VM) Autentikasi SQL, autentikasi Windows
Azure SQL Database Microsoft Entra ID (disarankan), autentikasi SQL
Azure SQL Managed Instance Microsoft Entra ID (disarankan), autentikasi SQL
Azure Synapse Analytics (pool khusus) Microsoft Entra ID, autentikasi SQL
Basis data SQL dalam Fabric Microsoft Entra ID
Fabric Data Warehouse Microsoft Entra ID
Titik akhir analitik SQL (Lakehouse) Microsoft Entra ID
Titik akhir analitik SQL (database cermin) Microsoft Entra ID

Lihat autentikasi Microsoft Entra untuk ketujuh mode autentikasi dan Siklus hidup Dukungan untuk matriks kompatibilitas lengkap.

Penyiapan alur CI

GitHub Actions

Pertahankan runtime Python dalam satu variabel sehingga Anda dapat meninjau dan memperbaruinya di satu tempat. Gunakan 3.x untuk alur validasi yang bergerak cepat, atau ganti dengan versi persis yang disetujui organisasi untuk alur rilis.

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

Untuk alur bersama, ganti kata sandi placeholder sebaris dengan rahasia terenkripsi, sematkan gambar layanan SQL Server ke intisari, dan simpan versi Python dalam variabel yang dikelola organisasi atau input alur kerja yang dapat digunakan kembali.

Azure Pipelines

Gunakan sumber daya kontainer untuk menjalankan SQL Server sebagai layanan bersama pekerjaan pengujian Anda:

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

Seperti halnya GitHub Actions, ganti kata sandi placeholder sebaris dengan variabel rahasia sebelum Anda menggunakan pola ini di luar alur demo sekali pakai.

Keamanan dan rahasia

Jangan menuliskan secara langsung kata sandi database atau string koneksi di dalam kode sumber atau file Docker. Gunakan variabel lingkungan dan manajemen rahasia sebagai gantinya.

Variabel lingkungan untuk pembangunan lokal

Simpan kredensial dalam variabel lingkungan atau .env file yang dikecualikan dari kontrol sumber:

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

Untuk Docker Compose, referensikan file .env :

services:
  app:
    build: .
    env_file: .env

Caution

Jangan pernah menerapkan .env file ke kontrol sumber. Tambahkan .env ke file Anda .gitignore .

Rahasia CI/CD

Di alur CI, gunakan penyimpanan rahasia platform alih-alih variabel lingkungan teks biasa:

Kebersihan rantai pasokan kontainer

Gunakan praktik ini untuk lingkungan pengembang bersama dan CI:

  • Simpan referensi gambar di satu tempat, seperti Docker ARG, build devcontainer, atau variabel alur.
  • Sematkan image kontainer yang dibagikan ke digest yang tidak dapat diubah, bukan tag yang berubah-ubah.
  • Tinjau dan segarkan ringkasan yang disematkan melalui proses pembaruan yang disetujui seperti Dependabot, Renovate, atau alur kerja promosi gambar internal.
  • Terapkan file kunci dependensi seperti uv.lock, atau gunakan file persyaratan hash untuk penginstalan Python yang dapat direproduksi.
  • Utamakan image dasar yang disetujui organisasi dan mirror registri internal jika platform Anda menyediakannya.

Produksi: autentikasi tanpa kata sandi

Untuk beban kerja produksi terhadap Azure SQL, gunakan autentikasi Microsoft Entra dengan identitas terkelola. Pendekatan ini menghilangkan kata sandi sepenuhnya:

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

Untuk aplikasi yang perlu menyimpan rahasia seperti kata sandi autentikasi SQL, gunakan Azure Key Vault dan ambil saat runtime.

Manajemen dependensi dengan uv

uv adalah penginstal paket Python cepat yang berfungsi dengan baik dalam build CI dan kontainer:

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

Di CI:

pip install uv
uv sync
uv run pytest

Memecahkan masalah umum kontainer

Gejala Cause Perbaiki
ImportError: libltdl.so.7 Pustaka sistem hilang. Instal libltdl7 (Debian) atau libltdl (Alpine).
ImportError: libkrb5.so.3 Pustaka Kerberos tidak ditemukan. Instal libkrb5-3 (Debian) atau krb5-libs (Alpine/RHEL).
SSL: CERTIFICATE_VERIFY_FAILED Sertifikat yang ditandatangani sendiri di SQL Server lokal. Tambahkan trust_server_certificate="yes" ke koneksi. Jangan gunakan ini dalam produksi.
Koneksi ditolak pada port 1433 SQL Server kontainer belum siap. Tambahkan pemeriksaan kesehatan atau tunggu layanan dimulai.
Login failed for user 'sa' Kata sandi tidak memenuhi persyaratan kompleksitas. Gunakan kata sandi dengan huruf besar, huruf kecil, digit, dan karakter khusus.
Cannot open database Database belum ada. Buat atau pulihkan database sebelum menghubungkan.
Koneksi pertama yang lambat di dalam kontainer Inisialisasi resolusi DNS atau rantai kredensial. Untuk SQL Server lokal, gunakan localhost,1433 alih-alih nama host. Untuk Azure SQL, lakukan autentikasi terlebih dahulu dengan az login.

Konten terkait

  • Last updated on