mssql-django についてよく寄せられる質問

この記事では、Microsoft Fabric の SQL Server、Azure SQL Database、Azure SQL Managed Instance、SQL データベースの mssql-django Django バックエンドに関してよく寄せられる質問に回答します。

General

mssql-django とは

mssql-django パッケージは、SQL Server用のMicrosoft管理された Django データベース バックエンドです。 これにより、DjangoアプリケーションはSQL Server、Azure SQL Database、Azure SQL Managed Instance、およびMicrosoft Fabric内のSQLデータベースに接続できます。 バージョン2.0以降は、デフォルトであるpyodbcドライバーか、Microsoftのmssql-pythonドライバーのいずれかで接続されます。

pip を使用してインストールします。

pip install mssql-django

mssql-django はどのバージョンの Django をサポートしていますか?

mssql-djangoパッケージバージョン2.0はDjango 5.2、6.0、6.1をサポートしています。 Django 3.2から5.1のプロジェクトはバージョン1.8.0のままです。 完全な互換性マトリックスについては、 サポート ライフサイクル を確認してください。

サポートされているPythonのバージョンは何ですか?

mssql-djangoパッケージバージョン2.0は3.10 Python 3.14までをサポートしています。 特定のPythonバージョンはあなたのDjangoバージョンとも互換性がある必要があります。Django 5.2はPython 3.10から3.13でテストされ、Django 6.0と6.1はPython 3.12から3.14でテストされます。 完全な互換性マトリックスについては、 サポート ライフサイクル を参照してください。

mssql-djangoはどのPythonデータベースドライバーを使っていますか?

バージョン2.0以降のバージョンでは、各データベースエイリアスごとに選択される2つのドライバーをサポートしています。 pyodbcはデフォルトであり、外部にインストールされたMicrosoft ODBCドライバー for SQL Serverが必要です。 代わりにMicrosoftのmssql-pythonドライバーを使うには、別途ODBCドライバーをインストールする必要がないため、そのエイリアスのOPTIONS辞書にpython_driverを追加します:

"OPTIONS": {
    "python_driver": "mssql_python",
},

オプションを省略した別名は引き続き pyodbcを使い続けます。 2つのパス間の挙動の違いについては、 mssql-djangoのデータベースドライバー選択を参照してください。

mssql-django はMicrosoftによって維持されますか?

Yes. mssql-django パッケージはMicrosoftによって管理され、PyPI および GitHub で使用できます。

コンフィギュレーション

settings.py ではどの ENGINE 値を使用しますか？

ENGINEを"mssql"構成でDATABASESに設定します。

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "HOST": "<your-server>",
    },
}

どの ODBC ドライバーを使用する必要がありますか?

デフォルトのpyodbcパスでは、SQL Server Microsoft ODBCドライバー18を使用します。 それがデフォルトで、バージョン18がインストールされていないとバックエンドは自動的にODBCドライバー17にフォールバックします。 特定のバージョンをピン留めする必要がある場合のみ、 OPTIONS 辞書でドライバーを明示的に指定してください。この場合はフォールバックもオフになります:

"OPTIONS": {
    "driver": "ODBC Driver 18 for SQL Server",
},

mssql-python パスは driver オプションを無視し、pip によって一緒にインストールされる ODBC Driver 18 を使用します。

Azure SQL Databaseに接続するにはどうすればよいですか?

ポート 1433 を付けた完全修飾サーバー名を使用してください:

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",
        },
    },
}

Microsoft Entra認証を使用する方法

extra_paramsまたはOPTIONS設定でTOKENを使用します。 TOKEN設定は、azure.identityやDefaultAzureCredentialなど、任意のManagedIdentityCredential資格情報で動作します。

from azure.identity import DefaultAzureCredential

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

"TOKEN": token,

サポートされているすべての方法については、Microsoft Entra認証を参照してください。

特徴

mssql-django は JSONField をサポートしていますか?

はい。JSONFieldは、SQL Server 2016 以降でサポートされています。 JSON データは nvarchar(max) として格納され、SQL Serverの JSON 関数を使用してクエリされます。 サポートされている参照と制限については、 JSONField のサポート を参照してください。

mssql-django はタイム ゾーン対応の datetimes をサポートしていますか?

Yes. USE_TZ=Trueすると、Django はSQL Serverの datetimeoffset データ型を使用します。 既存のデータベースを移行する場合は、既存の datetime2 列を変更する必要があります。 タイム ゾーンのサポートを参照してください。

ストアド プロシージャを呼び出すことができますか?

Yes. ストアド プロシージャを呼び出すには、connection.cursor()でcursor.execute()を使用します。 複数のパラメーターと結果セットを含む例については、 ストアド プロシージャを 参照してください。

BULK_CREATEは ID を返しますか?

既定では、いいえ。 return_rows_bulk_insert オプションの既定値は False です。 一括挿入後に ID を返せるように、データベース TrueでOPTIONSに設定します。 このオプションは、トリガーを含むテーブルに対して False のままにする必要があります。 一括操作を参照してください。

Troubleshooting

"ODBC ドライバーが見つかりません" というエラーが表示されます。 これを解決するにはどうすればいいですか?

Microsoft ODBC Driver for SQL Serverをインストールします。 Linux では、最初に Microsoft APT リポジトリを追加してから、ドライバーをインストールします。

curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | sudo gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg
curl -fsSL https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/prod.list | sudo tee /etc/apt/sources.list.d/mssql-release.list
sudo apt-get update
ACCEPT_EULA=Y sudo apt-get install -y msodbcsql18

Windowsで、Microsoft Web サイトからインストーラーをダウンロードします。 macOS では、Homebrew を使用します。

brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18

プラットフォーム固有の完全な手順については、「 インストール 」を参照してください。

" IDENTITY 列を変更できません" で移行が失敗する理由

SQL Server では、列を IDENTITY（AutoField）列に変更したり、IDENTITY（AutoField）列から変更したりすることはサポートされていません。 目的のフィールド型を使用して新しいモデルを作成し、データを手動で移行します。 mssql-django の制限事項とサポートされていない機能を参照してください。

bulk_update はなぜ NULL 許容フィールドで失敗するのですか？

バックエンドはすべてのNULL更新を自動的に処理します。 プレースホルダーの値を制御する必要がある場合は、default 内の bulk_update パラメーターを使用します。これにより、SQL Server の型推論エラーの原因となる CASE WHEN ... THEN NULL 式に NULL が含まれないようにできます。

Product.objects.bulk_update(products, ["description"], default="")

詳細については、 一括操作 を参照してください。

  • Last updated on