mssql-django を使用したコンテナーとローカル開発

このガイドでは、Windows、Linux、macOS、Docker コンテナー、devcontainers、CI パイプライン全体でmssql-django バックエンドを操作する Django 開発者向けの環境セットアップについて説明します。

Prerequisites

Python 3.10から3.14まで。 Django 6.0および6.1はPython 3.12以降のバージョンが必要です。
Docker Desktop (コンテナーベースの開発用)
既定の pyodbc パスを使用する場合は、SQL Server 用 Microsoft ODBC Driver 17 または 18 を使用してください。「ODBC Driver for SQL Server のダウンロード」を参照してください。
必要なmssql-pythonパッケージに対応したベースイメージ:Windows x64、Windows Python 3.11以降のバージョンのARM64、macOS 15以降のバージョン、またはglibc 2.28以降のバージョンを持つLinux x64/ARM64、またはmusl 1.2以降のバージョン。 ARM64上のSUSE Linuxはサポートされていません。

mssql-pythonパスはMicrosoft ODBCドライバーfor SQL Serverの別インストールを必要としません。それでもunixODBCランタイムは必要で、バックエンドはDjangoが読み込むときにpyodbcを取り込むからです。詳細については、 mssql-djangoのデータベースドライバーを選択することをご覧ください。

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

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

sqlcmd create mssql --accept-eula

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

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

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

sqlcmd query "SELECT @@VERSION"

作成時にsqlcmdが出力した接続情報を使用して接続するように、Django を構成します。後でそれらを取得するには、sqlcmd config view を使用します:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "master",
        "USER": "sa",
        "PASSWORD": "<password from sqlcmd output>",
        "HOST": "localhost",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "TrustServerCertificate=yes",
        },
    },
}

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

sqlcmd stop
sqlcmd delete

Tip

sqlcmd create mssql --user-database mydbを実行して、開発の準備ができている空のユーザーデータベースを含むコンテナーを作成します。

Visual Studio Code のローカル SQL Server

Visual Studio Code用の MSSQL 拡張機能は、エディターから直接ローカル SQL Server コンテナーを作成できます。

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

コンテナーが実行されたら、Django コードに切り替える前に、データベースの参照、クエリの実行、Visual Studio Code内のオブジェクトの管理を行うことができます。

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

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

docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=<strong_password>" \
  -p 1433:1433 --name sql1 \
  -d mcr.microsoft.com/mssql/server:2022-latest

Important

SQL Server コンテナーにはMSSQL_SA_PASSWORDを使用します。古い SA_PASSWORD 変数は非推奨です。パスワードは、SQL Server複雑さの要件 (大文字、小文字、数字、特殊文字を含む 8 文字以上) を満たしている必要があります。

コンテナーが起動するまで数秒待ってから、移行を実行します。

python manage.py migrate
python manage.py createsuperuser

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

デフォルトのpyodbcパスを通じてSQL Serverに接続するDjangoアプリケーション用の最小限のDockerファイルを作成します。 ODBC ドライバーは、Python基本イメージに付属していないキーの依存関係です。

FROM python:3.12-slim

# Install ODBC Driver 18 for SQL Server
RUN apt-get update && \
    apt-get install -y --no-install-recommends curl gnupg2 && \
    curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | \
        gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg && \
    echo "deb [signed-by=/usr/share/keyrings/microsoft-prod.gpg] https://packages.microsoft.com/debian/12/prod bookworm main" > \
        /etc/apt/sources.list.d/mssql-release.list && \
    apt-get update && \
    ACCEPT_EULA=Y apt-get install -y --no-install-recommends msodbcsql18 unixodbc-dev && \
    apt-get purge -y curl gnupg2 && \
    rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

# Collect static files
RUN python manage.py collectstatic --noinput

EXPOSE 8000
CMD ["gunicorn", "myproject.wsgi:application", "--bind", "0.0.0.0:8000"]

Important

パージ後に apt-get autoremove -y を加えないでください。 libgssapi-krb5-2を除去し、ODBCドライバーは実行時にロードしますが依存関係として宣言しません。ビルドは成功しましたが、すべての接続が失敗します。 pyodbcエラーは誤解を招きます。バージョン18は読み込まれず、mssql-djangoはバージョン17にフォールバックし、エラーは失敗したバージョン18ではなく欠けているバージョン17を名付けています。

あなたのrequirements.txt:

django>=5.2,<6.2
mssql-django>=2.0
gunicorn>=22.0

データベースのエイリアスが "python_driver": "mssql_python" で mssql-python ドライバーパスを使っている場合でも、unixODBC は必要です。なぜなら、Django が読み込むときにバックエンドが pyodbc をインポートするからです。 Microsoftパッケージリポジトリやmsodbcsql18は必要ないため、ODBCのインストールブロックは以下に縮小されます:

RUN apt-get update && \
    apt-get install -y --no-install-recommends unixodbc libkrb5-3 libgssapi-krb5-2 && \
    rm -rf /var/lib/apt/lists/*

ビルドして実行します。

docker build -t mydjango .
docker run -e "DB_HOST=host.docker.internal" -e "DB_NAME=<database>" \
  -e "DB_USER=<user_id>" -e "DB_PASSWORD=<password>" \
  -p 8000:8000 mydjango

Note

Docker Desktop (Windows および macOS) のhost.docker.internalを使用して、ホストコンピューター上のSQL Serverに到達します。 Linux では、代わりに --network host を使用します。

Devcontainer のセットアップ

SQL Server をサイドカーサービスとして含む、Visual Studio Code 用の .devcontainer/devcontainer.json を作成します。

{
    "name": "Django + SQL Server",
    "image": "mcr.microsoft.com/devcontainers/python:3",
    "features": {
        "ghcr.io/devcontainers/features/docker-in-docker:2": {}
    },
    "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
    "postCreateCommand": "bash .devcontainer/post-create.sh",
    "forwardPorts": [1433, 8000],
    "customizations": {
        "vscode": {
            "extensions": [
                "ms-python.python",
                "ms-mssql.mssql"
            ]
        }
    }
}

このdevcontainerはデフォルトのpyodbcパスとPython依存関係のODBCドライバーをインストールしますが、SQL Serverインスタンスは含まれていません。 sqlcmd create mssql --accept-eulaを使用して devcontainer 内で開始するか (Docker-in-Docker が使用可能であるため)、組み込みのSQL Server サービスに Docker Compose アプローチを使用します。 mssql-pythonパスを使う場合は、post-createスクリプトの msodbcsql18 インストールを sudo apt-get install -y unixodbc libkrb5-3 libgssapi-krb5-2に置き換えてください。

pyodbcおよびPython依存関係用のODBCドライバーをインストールするための.devcontainer/post-create.shを作成してください:

#!/bin/bash
set -e

# Install ODBC Driver 18
curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | \
    sudo gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg
echo "deb [signed-by=/usr/share/keyrings/microsoft-prod.gpg] https://packages.microsoft.com/debian/12/prod bookworm main" | \
    sudo tee /etc/apt/sources.list.d/mssql-release.list
sudo apt-get update
sudo ACCEPT_EULA=Y apt-get install -y msodbcsql18 unixodbc-dev

pip install -r requirements.txt

Docker Compose にSQL Serverを含める

devcontainer にサービスとしてSQL Serverを含めるには、Docker Compose を使用します。

.devcontainer/docker-compose.yml:

services:
  app:
    image: mcr.microsoft.com/devcontainers/python:3
    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: "<strong_password>"
    ports:
      - "1433:1433"

.devcontainer/devcontainer.json (作成バージョン):

{
    "name": "Django + SQL Server",
    "dockerComposeFile": "docker-compose.yml",
    "service": "app",
    "workspaceFolder": "/workspace",
    "postCreateCommand": "bash .devcontainer/post-create.sh",
    "customizations": {
        "vscode": {
            "extensions": [
                "ms-python.python",
                "ms-mssql.mssql"
            ]
        }
    }
}

名前で Django を SQL Server サービスに接続します。

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "mydb",
        "USER": "sa",
        "PASSWORD": "<password>",
        "HOST": "db",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "TrustServerCertificate=yes",
        },
    },
}

開発用の認証

アプリケーションの実行場所とデータベースのホスト場所に基づいて、認証方法を選択します。

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

Azure SQLに対する局所開発の場合は、pyodbc経路のOPTIONS["extra_params"]でAuthentication=ActiveDirectoryDefaultを使うか、DefaultAzureCredentialTOKEN設定を使います。 DefaultAzureCredential が az login セッションを自動的に引き継ぎます:

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
token = credential.get_token("https://database.windows.net/.default").token

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "mydb",
        "HOST": "<server>.database.windows.net",
        "PORT": "1433",
        "TOKEN": token,
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
        },
    },
}

完全な認証マトリックスと注意事項については、mssql-django での認証Microsoft Entraを参照してください。

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

Azureで実行されているコンテナーの場合は、TOKENでManagedIdentityCredential設定を使用して、Microsoft Entraアクセストークンを明示的に取得します。

from azure.identity import ManagedIdentityCredential

credential = ManagedIdentityCredential()
token = credential.get_token("https://database.windows.net/.default").token

DATABASES = {
  "default": {
    "ENGINE": "mssql",
    "NAME": "mydb",
    "HOST": "<server>.database.windows.net",
    "PORT": "1433",
    "TOKEN": token,
    "OPTIONS": {
      "driver": "ODBC Driver 18 for SQL Server",
    },
  },
}

認証方法の完全な一覧については、mssql-django での Microsoft Entra 認証を参照してください。

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

CI パイプライン内の SQL Server サービスコンテナーに対して Django テストスイートを実行します。

GitHub Actions

name: Django Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    services:
      sqlserver:
        image: mcr.microsoft.com/mssql/server:2022-latest
        env:
          ACCEPT_EULA: Y
          MSSQL_SA_PASSWORD: "<strong_password>"
        ports:
          - 1433:1433
        options: >-
          --health-cmd "/opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P \"$$MSSQL_SA_PASSWORD\" -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: "3.12"

      - name: Install ODBC Driver for pyodbc
        run: |
          curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | \
              sudo gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg
          echo "deb [signed-by=/usr/share/keyrings/microsoft-prod.gpg] https://packages.microsoft.com/ubuntu/$(lsb_release -rs)/prod $(lsb_release -cs) main" | \
              sudo tee /etc/apt/sources.list.d/mssql-release.list
          sudo apt-get update
          sudo ACCEPT_EULA=Y apt-get install -y msodbcsql18 unixodbc-dev

      - name: Install dependencies
        run: pip install -r requirements.txt

      - name: Run tests
        env:
          DB_HOST: localhost
          DB_NAME: "master"
          DB_USER: "<user_id>"
          DB_PASSWORD: "<password>"
        run: python manage.py test

Tip

共有パイプラインの場合は、インラインプレースホルダーのパスワードを暗号化されたシークレット (${{ secrets.SQL_PWD }}) に置き換え、SQL Server サービスイメージをダイジェストにピン留めします。

Azure Pipelines

trigger:
  - main

resources:
  containers:
    - container: sqlserver
      image: mcr.microsoft.com/mssql/server:2022-latest
      env:
        ACCEPT_EULA: Y
        MSSQL_SA_PASSWORD: "<strong_password>"
      ports:
        - 1433:1433

pool:
  vmImage: ubuntu-latest

services:
  sqlserver: sqlserver

steps:
  - task: UsePythonVersion@0
    inputs:
      versionSpec: "3.12"

  - script: |
      curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | \
          sudo gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg
      echo "deb [signed-by=/usr/share/keyrings/microsoft-prod.gpg] https://packages.microsoft.com/ubuntu/$(lsb_release -rs)/prod $(lsb_release -cs) main" | \
          sudo tee /etc/apt/sources.list.d/mssql-release.list
      sudo apt-get update
      sudo ACCEPT_EULA=Y apt-get install -y msodbcsql18 unixodbc-dev
      pip install -r requirements.txt
    displayName: Install dependencies

  - script: python manage.py test
    displayName: Run tests
    env:
      DB_HOST: "localhost"
      DB_NAME: "master"
      DB_USER: "<user_id>"
      DB_PASSWORD: "<password>"

環境ベースの settings.py

環境変数からデータベース資格情報を読み取る settings.py を構成します。この 1 つの構成は、ローカル開発、Docker、CI で機能します。

import os

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": os.environ.get("DB_NAME", "mydb"),
        "USER": os.environ.get("DB_USER", ""),
        "PASSWORD": os.environ.get("DB_PASSWORD", ""),
        "HOST": os.environ.get("DB_HOST", "localhost"),
        "PORT": os.environ.get("DB_PORT", "1433"),
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": os.environ.get("DB_EXTRA_PARAMS", "TrustServerCertificate=yes"),
        },
    },
}

ローカル開発用の.env ファイルに資格情報を格納します (.envに.gitignoreを追加します)。

DB_HOST=localhost
DB_NAME=mydb
DB_USER=<user_id>
DB_PASSWORD=<password>

django-environまたはpython-dotenvを使用して環境変数を読み込みます。

pip install django-environ

import environ

env = environ.Env()
environ.Env.read_env()  # Reads .env from the directory holding this settings file

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": env("DB_NAME"),
        "USER": env("DB_USER", default=""),
        "PASSWORD": env("DB_PASSWORD", default=""),
        "HOST": env("DB_HOST", default="localhost"),
        "PORT": env("DB_PORT", default="1433"),
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": env("DB_EXTRA_PARAMS", default="TrustServerCertificate=yes"),
        },
    },
}

注意事項

.envファイルをソース管理にコミットしないでください。 .env ファイルに .gitignore を追加します。

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

症状:	原因	修正
`Can't open lib 'ODBC Driver 18 for SQL Server'`	pyodbc パス用のコンテナに ODBC ドライバーがインストールされていないか、インストール後に `libgssapi-krb5-2`削除`apt-get autoremove` されました。	`msodbcsql18`はDockerfileやPost-createスクリプトにインストールし、その後は`apt-get autoremove`を実行しないでください。
`Can't open lib 'ODBC Driver 17 for SQL Server'` バージョン18をインストールしたとき	バージョン18は登録されていますが読み込みに失敗するため、mssql-djangoはインストールされていないバージョン17にフォールバックします。通常は `libgssapi-krb5-2`が欠けていることが原因です。	`libgssapi-krb5-2`をインストールし、`curl`を消した後は`apt-get autoremove`を実行しないでください。
`Error loading pyodbc module: libodbc.so.2`	コンテナにはunixODBCランタイムはありません。バックエンドはDjangoがpyodbcを読み込むと、mssql-python経路でもpyodbcをインポートします。	`unixodbc`（または`unixodbc-dev`）をインストールしてください。
`DDBC Error: Failed to load the driver`	mssql-pythonのドライバーは独自の依存関係を読み込むことはできません。	`libkrb5-3`と`libgssapi-krb5-2`をインストールします。
ポート 1433 で接続が拒否されました	SQL Server コンテナーの準備ができていません。	正常性チェックを追加するか、サービスが開始されるまで待ちます。
`Login failed for user '<user_id>'`	資格情報が正しくないか、パスワードが複雑さの要件を満たしていません。 mssql-pythonのパス上では、存在しないデータベースでも同じメッセージが表示されます。	コンテナーに適切な SQL ログインを使用し、パスワードが複雑さの要件を満たしていることを確認します。ログインが正しい場合は、 `NAME` のデータベースが存在するか確認してください。
`Cannot open database`	データベースはまだ存在しません。 pyodbcパスはこのケースを報告し、mssql-pythonパスは代わりに `Login failed` を報告します。	`migrate`を実行する前にデータベースを作成するか、初期セットアップに`master`を使用します。
コンテナーでの最初の接続が遅い	DNS 解決または認証情報チェーンの起動。	ローカル SQL Serverの場合は、ホスト名の代わりに `localhost` を使用します。
`SSL Provider: [error:0A000086]`	自己署名証明書による TLS 証明書の検証エラー。	開発専用の`TrustServerCertificate=yes`に`extra_params`を追加します。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-09-29