mssql-djangoの制限事項およびサポートされていない機能

この記事では、SQL Server、Azure SQL Database、Azure SQL Managed Instance、Microsoft FabricのSQLデータベースと組み合わせてmssql-djangoバックエンドが使われる場合の制限を挙げています。

Djangoの機能の制限

以下のDjango機能は mssql-django バックエンドでサポートされていないか、限定的にサポートされています:

特徴 地位 詳細
Avg と DurationField サポートしていません 集約 Avg は DurationFieldでは機能しません。
__regex および __iregex ルックアップ セットアップが必要 SQL ServerまたはAzure SQL Managed InstanceにCLRアセンブリをインストールした後にサポートされます。 Azure SQL DatabaseはCLRアセンブリをサポートしていません。 「 Set up regex lookups(正則式検索)」を参照してください。
DISTINCT ON サポートしていません SQL ServerはDISTINCT ON条項を支持していません。 .values().distinct()やサブクエリを使いましょう。
Subquery の ORDER BY サポートしていません サブクエリ式で並べ替える方法はうまくいかないかもしれません。
データベースレベル CASCADE 制限付き 一部の SET NULL や SET DEFAULT 操作では手動の移行SQLが必要になることがあります。
is_dst インチ Trunc/Extract サポートしていません is_dst パラメータ(サマータイムの移行時に曖昧な時間を解決するために使われる)は Extract() と Trunc() でサポートされていません。 DST対応のクエリには生のSQLで AT TIME ZONE を使いましょう。
浮動小数点注釈 制限付き 浮動小数点Avg集約は、SQL Serverのフロート型挙動のためPostgreSQLに比べて精度が低下することがあります。 例えば、0.1と0.2を平均すると、正確に0.15ではなく0.1500000000000000222になることがあります。 重要な財務計算には DecimalField や Cast(avg_expr, output_field=DecimalField()) を活用しましょう。
注釈/存在 ORDER BY サポートしていません order_byで注釈付きや存在式を使うとうまくいかないかもしれません。
右手の冪と日付時算術 サポートしていません 右手の冪操作(例えば、 F('value') ** 2 は動作しますが 2 ** F('value') は失敗)や timedelta との割り算はサポートされていません。
タイムゾーンとタイムドライタ 制限付き タイムゾーンやタイムデルタは完全にはサポートされていません。 mssql-djangoのタイムゾーンサポートを参照してください。
NthValue ウィンドウ関数 サポートしていません SQL ServerNTH_VALUE()をサポートしていません。 FIRST_VALUE、LAST_VALUE、またはサブクエリを使いましょう。
ignore_conflicts の bulk_create サポートしていません bulk_create(objs, ignore_conflicts=True)はサポートされていません。 SQL ServerにはPostgreSQLのON CONFLICT DO NOTHINGに相当するものはありません。
JSONField contains lookup サポートしていません 代わりにキーパスルックアップ(例: filter(metadata__color="blue"))を使いましょう。 JSONFieldの制限を参照してください。
select_for_update(of=(...)) サポートしていません SQL Serverは特定のテーブルをロックする機能をサポートしていません。 バックエンドは NotSupportedErrorを上げます。 詳細は トランザクション管理を参照してください。

移行の制限

制限事項 詳細
アルター AutoField AutoField(IDENTITY列)へのフィールド変更ができません。 新しいテーブルを作成する必要があります。
外部キーによる名称変更 外部キー制約を持つ列の名前変更は失敗することがあります。 SeparateDatabaseAndState を使用してください。
AddConstraint / RemoveConstraint 対立 一部の制約操作は競合することがあります。 別々の移行で申請してください。
日付抽出操作 ExtractYear、 ExtractMonth、および類似の作戦は tzinfo サポートが限られています。

JSONField limitations

  • mssql-djangoマップはNvarchar(Max)までJSONField。 SQL Server 2025はネイティブのjson型を導入しましたが、MicrosoftのODBCドライバ(SQL Server)ではそれを公開していません。
  • containsの検索はサポートされていません。 代わりにキーパスルックアップ(例: filter(metadata__color="blue"))を使いましょう。
  • 引用符付き文字列の値は追加の引用符付きで返されます(例えば、'value'の代わりに'"value"')。
  • 入れ子状のルックアップはPostgreSQLとは異なる挙動をする場合があります。
  • 詳細については、SQL Server の JSONField を参照してください。

InspectDB の制限

  • コンポジットのプライマリキーは自動的に unique_together 生成されません。
  • 一部のSQL Server固有の列タイプは汎用Djangoフィールドにマッピングされることがあります。
  • 生成されたモデルを手動で確認し調整してください。
  • 詳細については、 inspectdbを用いたリバースエンジニアリングモデルを参照してください。

SQL Serverパラメータ制限

SQL Serverは各クエリのパラメータを最大2,100個に制限しています。 この制限は、大きな値リストを持つパラメータ化されたクエリを生成するDjango操作に影響を与えます:

Operation 限界に到達する方法
filter(field__in=large_list) 各リスト項目はパラメータとなります。 バックエンドは2,048件以上のアイテムを一時テーブルに自動最適化します。
prefetch_related() 各親オブジェクトIDは関連するクエリの WHERE IN 節のパラメータとなります。 2,048ID以上で filter(field__in=...) 自動最適化されました。
bulk_create() 各オブジェクトの各場がパラメータとなります。 10フィールドと250オブジェクトを持つモデルは2,500のパラメータを生成します。
bulk_update() 各フィールドはオブジェクトごとに2つのパラメータ(PKマッチ用、1つが値用)を使用します。
Q() 多くの条件付きで 連鎖された Q オブジェクトの各値はパラメータとなります。

batch_sizeをまとめて、チャンクを大きくINクエリに設定してください。 解決策については パフォーマンスチューニング を参照してください。

バルク作業の制限

  • bulk_create return_rows_bulk_insert=FalseではIDは返されません。 トリガー付きのテーブルには必須です。 mssql-djangoによるバルク操作を参照してください。

テストフレームワークの制限

--keepdb 管理型ID認証(ActiveDirectoryMsi)を使用する場合は、テストランナーがその認証方法でデータベースを作成または破棄できないため、必須です。

詳細については、SQL ServerでのDjangoアプリテストをご覧ください。

バージョンごとの注釈

MSSQL-django バージョン メモ
1.7.3 ActiveDirectoryMsi以外のAuthentication=モードには固定FA001。 サブクラスDatabaseWrapperでKeyErrorを修正しました(1.7.1からの回帰)。
1.7.2 日付時間オフセットとUSE_TZ=TrueとのNow()の固定タイムゾーン処理。 Django 4.0以降の互換性 .explain() 修正済み。
1.7.1 FabricのSQLデータベース(EngineEdition 12)修正。 降下インデックス AlterField 修正。
1.7 ODBCドライバー18がデフォルトです。 Django 6.0、Python 3.14、SQL Server 2025のサポートが追加されました。
1.6 Django 5.1および5.2のサポート。 JSON機能の強化。
1.5 AutoField、パラメータフォーマット、スキーマクエリのバグ修正。
1.4 Django 5.0のサポート。 db_comment のサポート。
1.3 Django 4.2対応。
1.2 Django 4.1対応。 タイムゾーン対応。 return_rows_bulk_insert 選択肢です。 SQL Server 2022のサポート。
1.1 Django 3.2および4.0のサポート。

Djangoバージョン固有の注記

ジャンゴ版 メモ
5.1 inspectdb 複合主キーを持つテーブルは検査できますが、完全なモデル定義は生成できません。
5.2 CompositePrimaryKey 支援は部分的です。 inspectdb それでも手動修正が必要で、サブクエリとのタプル比較にはDjango 5.2.4以降のバージョンが必要で、一部の移行やJSONFieldのbulk/CASE WHEN更新パスにはテスト除外も含まれます。 詳細はGitHubリポジトリをご覧ください。
6.0 Python 3.12以降のバージョンが必要です。 5.2のすべての制限が適用されます。 バックエンドは6.0のすべてのAPI変更を透過的に処理します。

正則式の検索を設定します

mssql-djangoバックエンドはDjangoの__regexと__iregexルックアップをサポートしていますが、一度きりのセットアップステップが必要です。 バックエンドはdbo.REGEXP_LIKE関数を提供するCLRアセンブリ(regex_clr.dll)を出荷SQL Server。

Prerequisites

  • CLR統合をサポートするSQL Serverインスタンスです。 オンプレミスのSQL ServerとAzure SQL Managed InstanceはCLRをサポートしています。 Azure SQL Database CLRアセンブリをサポートしていないため、__regexや__iregexのルックアップはAzure SQL Databaseで利用できません。
  • 接続ユーザーは、 sysadmin または ALTER SETTINGS の許可が必要です。 管理コマンドはCLRを自動的に有効化します。
  • mssqlアプリはINSTALLED_APPSになければなりません。

CLRアセンブリを取り付けてください

管理コマンドを実行し、データベース名を渡します:

python manage.py install_regex_clr <your-database-name>

このコマンドは以下の手順を実行します:

  1. サーバー(sp_configure 'clr enabled', 1)でCLRを有効にすると、まだ有効になっていなければ有効です。
  2. セットclr strict security を 0 に(2017+SQL Server SAFEアセンブリに必要)。
  3. バンドルされたDLLから regex_clr アセンブリを作成します。
  4. dbo.REGEXP_LIKEスカラー関数を作り出します。

注意事項

clr strict securityを0に設定すると、署名のないCLRアセンブリを読み込みます。 これは、束ねられた regex_clr.dll に署名がないため必須です。 この変更については、本番サーバーでコマンドを実行する前にDBAと相談してください。 この設定はデータベースごとではなくサーバー全体に適用されます。

正則表現ルックアップを使います

アセンブリをインストールした後、クエリセットで __regex と __iregex を使いましょう:

# Case-sensitive regex
products = Product.objects.filter(name__regex=r"^Widget \d+$")

# Case-insensitive regex
products = Product.objects.filter(name__iregex=r"^widget \d+$")

バックエンドはこれらの検索を dbo.REGEXP_LIKE(column, pattern, case_flag) = 1に翻訳します。

Note

データベースごとに install_regex_clr コマンドを一度実行する必要があります。 データベースがドロップされて再作成された場合(例えばテスト中)、コマンドを再度実行します。

関連するコンテンツ

  • Last updated on