mssql-django の接続オプション

この記事では、Django OPTIONS構成のDATABASESディクショナリ設定について説明します。これらの設定は、ODBC ドライバーmssql-django経由でSQL Serverに接続する方法を制御します。

ODBC ドライバーの選択

mssql-django 1.7 の時点では、SQL Serverのバックエンドの既定値は ODBC Driver 18 です。 ODBC Driver 18 がインストールされていない場合、バックエンドは自動的に ODBC Driver 17 にフォールバックします。

Note

ODBC Driver 18 では、既定で Encrypt=yes が有効になり、サーバー証明書が検証されます。ドライバー 17 で動作していた接続は、SSL/TLS 信頼エラーで失敗する可能性があります。エラーを解決するには:

オンプレミスのSQL Serverの場合は、クライアントが既に信頼している証明機関からサーバー証明書をインストールするか、既存のサーバー証明書を各クライアント信頼ストアにインポートします。手順については、「接続を暗号化するためのSQL Server データベースエンジンの構成」を参照してください。
IP アドレスまたは証明書のサブジェクトまたはサブジェクトの別名 (SAN) と一致しないエイリアスで接続する場合は、 HostNameInCertificate=<name-from-certificate> を extra_paramsに追加します。

自己署名証明書に対するローカル開発については、「TrustServerCertificateの」を参照してください。

ドライバーを明示的に指定できます。

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 17 for SQL Server",
        },
    },
}

Linux では、ドライバーライブラリへの完全なパスを指定することもできます。

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "/opt/microsoft/msodbcsql18/lib64/libmsodbcsql-18.0.so.1.1",
        },
    },
}

DSN と HOST

HOST名または名前付き DSN (データソース名) を使用して接続できます。

HOST を使用して接続する

ほとんどの構成では、 HOST 設定が直接使用されます。

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
        },
    },
}

DSN を使用して接続する

ODBC データソースで構成された名前付き DSN を使用します。

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "OPTIONS": {
            "dsn": "MyDataSourceName",
        },
    },
}

FreeTDS のサポート

Odbc ドライバーとして FreeTDS を使用するには、 host_is_server を True に設定します。これにより、HOSTでデータサーバー名を調べるのではなく、PORTとfreetds.confを直接使用するようにバックエンドに指示されます。

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "FreeTDS",
            "host_is_server": True,
        },
    },
}

FreeTDS を使用した DSN レス接続の詳細については、 FreeTDS ユーザーガイドを参照してください。

その他の ODBC パラメーター

extra_paramsを使用して、追加の ODBC 接続文字列パラメーターを渡します。値は、セミコロンで区切られた文字列で、接続文字列に追加されます。

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "TrustServerCertificate=yes;ApplicationIntent=ReadOnly",
        },
    },
}

この設定は、Microsoft Entra認証キーワードにも使用されます。

注意事項

TrustServerCertificate=yesは、自己署名証明書を使用したローカル開発にのみ使用します。運用環境では使用しないでください。証明書チェーンの検証が無効になり、敵対者の中間リスクが増加します。信頼された証明書をサーバーにインストールし、 TrustServerCertificate=noで接続します。

接続のタイムアウトと再試行

タイムアウトと再試行の設定を使用して接続の回復性を構成します。

オプション	デフォルト	説明
`connection_timeout`	`0` (無効)	接続を待機する最大秒数。
`connection_retries`	`5`	接続エラー時の再試行回数。
`connection_retry_backoff_time`	`5`	再試行の間に待機する秒数。
`query_timeout`	`0` (無効)	クエリが完了するまで待機する最大秒数。

例：

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "connection_timeout": 30,
            "connection_retries": 3,
            "connection_retry_backoff_time": 10,
            "query_timeout": 120,
        },
    },
}

Collation

テキストフィールド参照のカスタム照合順序を設定します。

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "collation": "Chinese_PRC_CI_AS",
        },
    },
}

複数のデータベース接続

Django では、複数のデータベースへの同時接続がサポートされています。これは、読み取りレプリカ、データベース間クエリ、または分離レベルによるワークロードの分離に役立ちます。

複数のデータベースを構成する

DATABASES設定で各接続を定義します。

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "app_db",
        "HOST": "<your-primary-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
        },
    },
    "readonly": {
        "ENGINE": "mssql",
        "NAME": "app_db",
        "HOST": "<your-readonly-replica>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "Encrypt=yes;ApplicationIntent=ReadOnly",
        },
    },
    "analytics": {
        "ENGINE": "mssql",
        "NAME": "analytics_db",
        "HOST": "<your-analytics-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "isolation_level": "READ UNCOMMITTED",
        },
    },
}

注意事項

READ UNCOMMITTED はダーティリードを許可します。この分離レベルは、絶対精度が必要ないレポートまたは分析クエリにのみ使用します。詳細については、「トランザクション管理」を参照してください。

データベースルーターを使用してクエリをルーティングする

読み取りと書き込みの操作を適切な接続に転送するデータベースルーターを作成します。

class ReadReplicaRouter:
    """Route read queries to the readonly replica, writes to the primary."""

    def db_for_read(self, model, **hints):
        return "readonly"

    def db_for_write(self, model, **hints):
        return "default"

    def allow_relation(self, obj1, obj2, **hints):
        return True

    def allow_migrate(self, db, app_label, model_name=None, **hints):
        return db == "default"

settings.pyにルーターを登録します。

DATABASE_ROUTERS = ["myproject.routers.ReadReplicaRouter"]

ルータークラスを myproject/routers.py などのファイルに保存します。

特定のデータベースに直接クエリを実行する

using()メソッドを使用して、特定のデータベースエイリアスに対してクエリを実行します。

# Explicit read from analytics database
reports = AnalyticsReport.objects.using("analytics").filter(date__gte="2025-01-01")

# Write to default
Product.objects.create(name="Widget", price=9.99)

接続ごとのデータベースの分離レベルの詳細については、「ブロックせずにデータを読み取る」を参照してください。

フィードバック

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

Last updated on 2026-07-01