mssql-pythonを用いたコンテナおよびローカル開発

このガイドでは、Windows、Linux、macOS、Dockerコンテナ、開発コンテナ、CIパイプラインを横断してmssql-pythonドライバーを扱うPython開発者向けの環境設定をカバーしています。

前提条件

• Python 3.10 以降。
• Docker Desktop(コンテナベース開発用)。
• SQL Server Linuxコンテナ用のx64互換ホスト(Intel、AMD、またはx64 VM)。 SQL ServerのLinuxコンテナはARM64ホストをサポートしていません。

sqlcmd を使用したローカル SQL Server (推奨)

go-sqlcmdユーティリティは、単一のコマンドでSQL Serverコンテナを作成できます。 Docker イメージのプル、パスワードの生成、ポートの割り当て、接続コンテキストが自動的に処理されます。

sqlcmd create mssql --accept-eula

サンプル データベースが既にアタッチされているコンテナーを作成するには:

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

作成後、 sqlcmd は接続コンテキストを格納して、すぐにクエリを実行できるようにします。

sqlcmd query "SELECT @@VERSION"

一度アプリケーションログインを作成し、それを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>;"

<database>、<app-login>、<password>を環境の価値観に置き換えましょう。

作成時にsqlcmdが出力した接続情報を使用して、Pythonから接続してください。 後でそれらを取得するには、sqlcmd config view を使用します:

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

完了したら、コンテナーを停止または削除します。

sqlcmd stop
sqlcmd delete

VS Code からのローカル SQL Server

VS Code用のSQL Server拡張(ms-mssql.mssql)は、エディターから直接ローカルSQL Serverコンテナを作成できます:

1. アクティビティ バーでSQL Server ビューを開きます。
2. [>を選択します (または、[コマンド パレット: MS SQL: ローカル SQL Serverの作成] を使用します)。
3. SQL Serverバージョンを選択し、EULA に同意します。
4. 拡張機能によってコンテナー イメージがプルされ、パスワードが生成され、接続プロファイルが自動的に追加されます。

コンテナが稼働すれば、データベースの閲覧、クエリの実行、オブジェクト管理がVS Codeで行え、その後Pythonコードに切り替えられます。

Docker を使用したローカル SQL Server

コンテナーを直接管理する場合、公式のSQL Server コンテナー イメージは、次の 2 つの環境変数で動作します。

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

数秒待ってから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()

AdventureWorksのサンプルデータベースをコンテナに読み込むには:

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

Pythonアプリケーション用のDockerfile

Pythonのベースイメージ参照は一か所にまとめて、ローカルビルド、devcontainer、CIパイプラインがドリフトしないようにしましょう。 局所的な実験には、 python:3-slim のような広くサポートされたタグが効果的です。 共有の devcontainer、CI、本番環境では、そのタグを組織の許可済みリストにある承認済みのダイジェスト固定イメージに置き換えてください。

Microsoft SQLに接続するPythonアプリケーション用の最小限のDockerファイルを作成します:

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:

mssql-python>=1.11.0

ビルドして実行します。

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

共有環境では、承認された不変の基底イメージ参照を --build-arg PYTHON_BASE=python:3-slim@sha256:<approved-digest>と共に渡します。

Alpine Linux

アルパインはmuslの代わりにglibcを使います。 必要なパッケージをインストールします。

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 のセットアップ

アプリケーションでビルドしているのと同じDockerファイルを再利用してください。 この方法により、開発者コンテナはランタイムイメージと整合し、Pythonバージョンのピンが複数のファイルに分散するのを防ぎます。

VS Code 用の.devcontainer/devcontainer.jsonを作成する:

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

devcontainer にサービスとしてSQL Serverを含めるには、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 (作成バージョン):

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

共有ワークスペースの場合は、フローティングタグに頼らず承認されたダイジェストにSQL Serverサービスイメージをピン留めしてください。 ソース管理に確認するのではなく、ローカルMSSQL_SA_PASSWORDファイルやプラットフォームの秘密ストアから.env読み込みましょう。

名前でSQL Serverサービスに接続する:

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

プラットフォーム固有の依存関係

mssql-pythonドライバーはネイティブコンポーネントをバンドルしています。 外部のODBCドライバーマネージャーをインストールする必要はありません。 しかし、このドライバーはLinuxやmacOSで少数のシステムライブラリを必要とします。

macOSではSSLエラーが発生した場合、リンカーフラグを設定してください:

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

完全なインストール手順については、「 Install mssql-python」をご覧ください。

開発用の認証

Azure SQLに対するローカル開発

パスワードレス認証には ActiveDirectoryDefault を使いましょう。 このオプションはAzure CLI、Visual Studio、環境変数、マネージドIDを自動でチェーン接続します:

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

Azure CLIを使ってサインインしていることを確認してください:

az login

SQL Serverに対するローカル開発

ローカルインスタンスでSQL認証を使いましょう。

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

Azure SQLに対するコンテナー開発

Azureで動作するコンテナ(App Service、Container Apps、AKS)にはmanaged identityを使用します。

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

ローカルで動作するコンテナでAzure SQLに接続する必要がある場合は、コンテナにActiveDirectoryDefaultが使える認証情報ソースがあることを確認してください。 最も信頼できる選択肢は以下の通りです:

• コンテナにAzure CLIをインストールしてサインインしてください。 コンテナ イメージに Azure CLI が既に含まれていて、その資格情報キャッシュを再利用する場合にのみ、ホストから ~/.azure をマウントしてください。
• AZURE_CLIENT_ID、AZURE_TENANT_ID、AZURE_CLIENT_SECRETなどの環境変数を通じてサービスプリンシパルの資格情報を提供します。

そして接続コードに「 ActiveDirectoryDefault 」を使いましょう。

対応Microsoft SQLエンドポイント

mssql-pythonドライバーはすべてのMicrosoft SQLエンドポイントに接続します:

7つの認証モードすべてについてはMicrosoft Entra認証、互換性マトリックスについてはサポートライフサイクルを参照してください。

CI パイプラインのセットアップ

GitHub Actions

Pythonランタイムを1つの変数にまとめて、一か所でレビューや更新ができるようにしましょう。 迅速な検証パイプラインには 3.x を使い、リリースパイプラインには組織承認の正確なバージョンに置き換えてください。

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

共有パイプラインの場合は、インラインのプレースホルダーパスワードを暗号化されたシークレットに置き換え、SQL Serverサービスイメージをダイジェストにピン留めし、Python版は組織管理変数または再利用可能なワークフロー入力に保存します。

Azure Pipelines

コンテナリソースを使って、テストジョブと並行してSQL Serverをサービスとして実行してください:

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と同様に、使い捨てデモパイプライン以外でこのパターンを使う前に、インラインのプレースホルダーパスワードを秘密変数に置き換えてください。

セキュリティとシークレット

ソースコードやDockerファイルにデータベースのパスワードや接続文字列をハードコーディングしないでください。 代わりに環境変数と秘密管理を使いましょう。

地域開発のための環境変数

認証情報を環境変数やソース管理から除外された .env ファイルに保存します:

# .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については、 .env ファイルを参照してください:

services:
  app:
    build: .
    env_file: .env

CI/CDの秘密

CIパイプラインでは、プレーンテキスト環境変数の代わりにプラットフォームのシークレットストアを使用します。

• GitHub Actions:暗号化された秘密を使い、それを${{ secrets.SQL_PWD }}として参照してください。
• Azure Pipelines:秘密変数を使い、$(SQL_PWD)として参照してください。

コンテナサプライチェーン衛生

共有開発者環境およびCIにおいて以下の実践を活用してください:

• Docker ARG、devcontainerビルド、パイプライン変数など、イメージ参照は一箇所にまとめておきましょう。
• 共有コンテナ画像を浮動タグの代わりに、不変なダイジェストにピン留めしましょう。
• Dependabot、Renovate、または社内の画像プロモーションワークフローなどの承認された更新プロセスを通じて、ピン留めされたダイジェストをレビュー・更新してください。
• uv.lockのような依存関係ロックファイルをコミットするか、ハッシュ化された要件ファイルを用いて再現可能なPythonインストールを行ってください。
• プラットフォームが提供している場合は、組織承認のベースイメージや内部レジストリミラーを優先してください。

プロダクション:パスワードレス認証

Azure SQLに対する本番ワークロードでは、管理されたIDでMicrosoft Entra認証を使いましょう。 この方法により、パスワードは完全に排除されます:

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

SQL認証パスワードなどの秘密を保存する必要があるアプリケーションは、Azure Key Vaultを使い、実行時に取得してください。

UVによる依存管理

uvは高速なPythonパッケージインストーラーで、CIやコンテナビルドでよく機能します:

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 では:

pip install uv
uv sync
uv run pytest

コンテナーに関する一般的な問題のトラブルシューティング

関連するコンテンツ

• mssql-pythonをインストールする
• サポート ライフサイクル
• 接続文字列
• Microsoft Entra 認証
• クイックスタート:繰り返し展開