Développement de conteneurs et local avec mssql-python

Ce guide couvre la configuration de l’environnement pour les développeurs Python travaillant avec le mssql-python pilote sur Windows, Linux, macOS, conteneurs Docker, devcontainers et pipelines CI.

Logiciels requis

• Python 3.10 ou version ultérieure.
• Docker Desktop (pour le développement basé sur conteneurs).
• Un hôte compatible x64 (Intel, AMD ou VM x64) pour les conteneurs Linux SQL Server. Les conteneurs Linux SQL Server ne prennent pas en charge les hôtes ARM64.

SQL Server local avec sqlcmd (recommandé)

L’utilitaire go-sqlcmd peut créer un conteneur SQL Server en une seule commande. Il gère automatiquement le contexte d’extraction d’images Docker, de génération de mot de passe, d’affectation de port et de connexion :

sqlcmd create mssql --accept-eula

Pour créer un conteneur avec un exemple de base de données déjà attaché :

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

Après la création, sqlcmd stocke le contexte de connexion afin de pouvoir interroger immédiatement :

sqlcmd query "SELECT @@VERSION"

Créez une connexion d’application une fois, puis utilisez-la dans votre code Python :

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

Remplacez <database>, <app-login>, et <password> par des valeurs de votre environnement.

Connectez-vous depuis Python en utilisant les détails de connexion que sqlcmd a imprimés à la création. Utilisez sqlcmd config view pour les récupérer ultérieurement :

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

Lorsque vous avez terminé, arrêtez ou supprimez le conteneur :

sqlcmd stop
sqlcmd delete

SQL Server local depuis VS Code

L’extension SQL Server pour VS Code (ms-mssql.mssql) peut créer des conteneurs SQL Server locaux directement depuis l’éditeur :

1. Ouvrez la vue SQL Server dans la barre d’activité.
2. Sélectionnez Ajouter une connexion>créer un SQL Server local (ou utilisez la palette de commandes MS SQL : Créer un SQL Server local).
3. Choisissez la version SQL Server et acceptez le CLUF.
4. L’extension extrait l’image conteneur, génère un mot de passe et ajoute automatiquement un profil de connexion.

Une fois le conteneur en cours, vous pouvez parcourir les bases de données, lancer des requêtes et gérer des objets directement dans VS Code avant de passer au code Python.

SQL Server local avec Docker

Si vous préférez gérer directement des conteneurs, l’image de conteneur SQL Server officielle fonctionne avec deux variables d’environnement :

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

Attends quelques secondes, puis connecte-toi depuis 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()

Pour charger la base de données d’exemples AdventureWorks dans le conteneur :

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

Dockerfile pour les applications Python

Conservez la référence de l’image de base Python en un seul endroit afin que les builds locaux, les devcontainers et les pipelines CI ne divergent pas. Pour l’expérimentation locale, un tag large et supporté comme python:3-slim fonctionne bien. Pour les devcontainers partagés, les CI et la production, remplacez cette étiquette par une image approuvée épinglée dans le digest de la liste des autorisations de votre organisation.

Créez un fichier Docker minimal pour une application Python qui se connecte à 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"]

Votre requirements.txt:

mssql-python>=1.11.0

Construire et lancer :

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

Dans les environnements partagés, on transmet une référence d’image de base immuable approuvée avec --build-arg PYTHON_BASE=python:3-slim@sha256:<approved-digest>.

Alpine Linux

Alpine utilise musl à la place de glibc. Installez les packages nécessaires :

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

Configuration de Devcontainer

Réutilisez le même fichier Docker avec lequel votre application construit. Cette approche permet de garder le devcontainer cohérent avec votre image d’exécution et évite de disperser les contraintes de version de Python dans plusieurs fichiers.

Créez un .devcontainer/devcontainer.json pour 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"
            ]
        }
    }
}

Pour inclure SQL Server en tant que service dans le devcontainer, utilisez 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 (Version de composition) :

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

Pour les espaces de travail partagés, épinglez l’image du service SQL Server à un digest approuvé au lieu de vous fier à une balise flottante. Chargez MSSQL_SA_PASSWORD depuis un fichier local .env ou un magasin secret de plateforme au lieu de le vérifier dans le contrôle de version.

Connectez-vous au service SQL Server par nom :

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

Dépendances spécifiques à la plateforme

Le mssql-python pilote regroupe ses composants natifs. Vous n’avez pas besoin d’installer un gestionnaire de pilotes ODBC externe. Cependant, le pilote nécessite un petit ensemble de bibliothèques système sous Linux et macOS.

Pour macOS, si vous rencontrez des erreurs SSL, réglez les drapeaux de liaison :

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

Pour les instructions complètes d’installation, voir Installer mssql-python.

Authentification pour le développement

Développement local contre Azure SQL

Utilisez ActiveDirectoryDefault pour l’authentification sans mot de passe. Cette option passe automatiquement via Azure CLI, Visual Studio, variables d’environnement et identité gérée :

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

Assurez-vous d'être connecté en utilisant Azure CLI :

az login

Développement local avec SQL Server

Utilisez l’authentification SQL avec une instance locale.

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

Développement de conteneurs sur Azure SQL

Pour les conteneurs fonctionnant sous Azure (App Service, Container Apps, AKS), utilisez l’identité managée.

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

Pour les conteneurs qui tournent localement et qui doivent se connecter à Azure SQL, assurez-vous que le conteneur possède une source d’identifiants utilisableActiveDirectoryDefault. Les options les plus fiables sont :

• Installez Azure CLI dans le conteneur et connectez-vous là-bas. Montez ~/.azure depuis l’hôte seulement si l’image du conteneur inclut déjà Azure CLI et que vous comptez réutiliser ce cache d’identifiants.
• Fournir des identifiants de principal de service via des variables d’environnement telles que AZURE_CLIENT_ID, AZURE_TENANT_ID, et AZURE_CLIENT_SECRET.

Ensuite, utilisez ActiveDirectoryDefault dans votre code de connexion.

Terminaux SQL Microsoft pris en charge

Le pilote mssql-python se connecte à toutes les terminaisons Microsoft SQL :

Voir l’authentification Microsoft Entra pour les sept modes d’authentification et le cycle de vie du support pour consulter la matrice de compatibilité complète.

Configuration du pipeline CI

GitHub Actions

Gardez l’exécution Python dans une seule variable pour pouvoir la revoir et la mettre à jour en un seul endroit. Utilisez 3.x pour des pipelines de validation rapides, ou remplacez-la par une version exacte approuvée par l’organisation pour les pipelines de release.

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

Pour les pipelines partagés, remplacez le mot de passe provisoire en ligne par un secret chiffré, épinglez l’image du service SQL Server à un digest, et conservez la version Python dans une variable gérée par l’organisation ou une entrée de workflow réutilisable.

Azure Pipelines

Utilisez une ressource conteneur pour exécuter SQL Server en tant que service en parallèle de votre tâche de test :

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

Comme pour GitHub Actions, remplacez le mot de passe provisoire en ligne par une variable secrète avant d’utiliser ce schéma en dehors d’un pipeline de démonstration jetable.

Sécurité et secrets

Ne codez pas en dur les mots de passe de base de données ou les chaînes de connexion dans le code source ou Dockerfiles. Utilisez plutôt la gestion des variables d’environnement et des secrets.

Variables environnementales pour le développement local

Stockez les identifiants dans des variables d’environnement ou un .env fichier exclu du contrôle de version :

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

Pour Docker Compose, référez-vous à un .env fichier :

services:
  app:
    build: .
    env_file: .env

secrets de CI/CD

Dans les pipelines CI, utilisez le magasin secret de la plateforme au lieu des variables d’environnement en clair :

• GitHub Actions: Utilisez des secrets chiffrés et référencez-les sous la forme ${{ secrets.SQL_PWD }}.
• Azure Pipelines : Utilisez des variables secrètes et référez-les sous le nom $(SQL_PWD).

Hygiène de la chaîne d’approvisionnement en conteneurs

Utilisez ces pratiques pour les environnements de développement partagés et les interfaces de développement :

• Gardez les références d’image en un seul endroit, comme un Docker ARG, une compilation devcontainer ou une variable pipeline.
• Fixez les images de conteneur partagées à des digests immuables plutôt qu’à des tags non figés.
• Examinez et rafraîchez les résumés épinglés via un processus de mise à jour approuvé tel que Dependabot, Renovate ou un flux de travail interne de promotion d’images.
• Validez un fichier de verrouillage des dépendances tel que uv.lock, ou utilisez des fichiers d’exigences avec hachage pour garantir des installations Python reproductibles.
• Privilégiez les images de base approuvées par l’organisation et les miroirs internes du registre lorsque votre plateforme les propose.

Production : authentification sans mot de passe

Pour les charges de travail en production avec Azure SQL, utilisez l’authentification Microsoft Entra avec identité managée. Cette approche élimine complètement les mots de passe :

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

Pour les applications qui doivent stocker des secrets comme les mots de passe d’authentification SQL, utilisez Azure Key Vault et récupérez-les à l’exécution.

Gestion des dépendances avec uv

UV est un installateur rapide de paquets Python qui fonctionne bien dans les builds CI et conteneurs :

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

En CI :

pip install uv
uv sync
uv run pytest

Résoudre les problèmes courants liés aux conteneurs

Contenu connexe

• Installer mssql-python
• Cycle de vie de support
• Chaînes de connexion
• Authentification Microsoft Entra
• Démarrage rapide : Déploiements répétables