Batasan dan fitur yang tidak didukung di mssql-django

Artikel ini mencantumkan batasan mssql-django backend saat digunakan dengan SQL Server, Azure SQL Database, Azure SQL Managed Instance, dan database SQL di Microsoft Fabric.

Keterbatasan fitur Django

Fitur Django berikut tidak didukung atau memiliki dukungan terbatas dengan mssql-django backend:

Fitur Status Detail lebih lanjut
Avg dengan DurationField Tidak didukung Agregat Avg tidak berfungsi pada DurationField.
__regex dan __iregex pencarian Memerlukan penyiapan Didukung setelah menginstal rakitan CLR di SQL Server atau Azure SQL Managed Instance. Azure SQL Database tidak mendukung rakitan CLR. Lihat Menyiapkan pencarian ekspresi reguler.
DISTINCT ON Tidak didukung SQL Server tidak mendukung DISTINCT ON klausa. Gunakan .values().distinct() atau subkueri.
Subquery In ORDER BY Tidak didukung Mengurutkan berdasarkan ekspresi subkueri mungkin tidak berfungsi.
Tingkat database CASCADE Limited Beberapa SET NULL dan SET DEFAULT operasi dapat memerlukan SQL migrasi manual.
is_dst dalam Trunc/Extract Tidak didukung is_dst (digunakan untuk menyelesaikan waktu ambigu selama transisi musim panas) dan Extract()Trunc() tidak didukung. Gunakan AT TIME ZONE dalam SQL mentah untuk kueri sadar DST.
Anotasi titik mengambang Limited Agregat floating point Avg dapat kehilangan presisi dibandingkan dengan PostgreSQL karena perilaku tipe float SQL Server. Misalnya, rata-rata 0,1 dan 0,2 mungkin menghasilkan 0,150000000000000000000222, bukan tepat 0,15. Gunakan DecimalField atau Cast(avg_expr, output_field=DecimalField()) untuk perhitungan keuangan kritis.
Anotasi/ada di ORDER BY Tidak didukung Menggunakan ekspresi anotasi atau ada di order_by mungkin tidak berfungsi.
Aritmatika pangkat kanan dan tanggalwaktu Tidak didukung Operasi daya kanan (misalnya, F('value') ** 2 berfungsi tetapi 2 ** F('value') gagal) dan pembagian dengan timedelta tidak didukung.
Zona waktu dan delta waktu Limited Zona waktu dan timedelta tidak didukung sepenuhnya. Lihat Dukungan zona waktu di mssql-django.
NthValue fungsi jendela Tidak didukung SQL Server tidak mendukung NTH_VALUE(). Gunakan FIRST_VALUE, LAST_VALUE, atau subkueri.
ignore_conflicts In bulk_create Tidak didukung bulk_create(objs, ignore_conflicts=True) tidak didukung. SQL Server tidak memiliki padanan dengan PostgreSQLON CONFLICT DO NOTHING.
JSONField contains pencarian Tidak didukung Gunakan pencarian jalur kunci sebagai gantinya (misalnya, filter(metadata__color="blue")). Lihat JSONField pembatasan.
select_for_update(of=(...)) Tidak didukung SQL Server tidak mendukung penguncian tabel tertentu. Backend menaikkan NotSupportedError. Lihat Manajemen transaksi.

Batasan migrasi

Batasan Detail lebih lanjut
Mengubah AutoField Tidak dapat mengubah bidang ke atau dari AutoField (IDENTITY kolom). Memerlukan pembuatan tabel baru.
Ganti nama dengan kunci asing Mengganti nama kolom yang memiliki batasan kunci asing dapat gagal. Gunakan SeparateDatabaseAndState.
AddConstraint / RemoveConstraint Konflik Beberapa operasi batasan dapat bertentangan. Terapkan dalam migrasi terpisah.
Operasi ekstrak tanggal ExtractYear, ExtractMonth, dan operasi serupa memiliki dukungan terbatas tzinfo .

Batasan JSONField

  • mssql-django memetakan JSONField ke nvarchar(maks). SQL Server 2025 memperkenalkan jenis json asli, tetapi Microsoft ODBC Driver for SQL Server tidak mengeksposnya.
  • contains Pencarian tidak didukung. Gunakan pencarian jalur kunci sebagai gantinya (misalnya, filter(metadata__color="blue")).
  • Nilai string yang dikutip dikembalikan dengan tanda kutip tambahan (misalnya, '"value"' bukan 'value').
  • Beberapa pencarian berlapis mungkin berperilaku berbeda dari PostgreSQL.
  • Untuk informasi selengkapnya, lihat JSONField dengan SQL Server.

Batasan InspectDB

  • Kunci primer komposit tidak dibuat secara unique_together otomatis.
  • Beberapa jenis kolom khusus SQL Server mungkin dipetakan ke bidang Django generik.
  • Tinjau dan sesuaikan model yang dihasilkan secara manual.
  • Untuk informasi selengkapnya, lihat Model merekayasa balik dengan inspectdb.

Batas parameter SQL Server

SQL Server membatasi setiap kueri hingga maksimum 2.100 parameter. Batas ini mempengaruhi operasi Django yang menghasilkan kueri berparameter dengan daftar nilai besar:

Pengoperasian Bagaimana itu mencapai batas
filter(field__in=large_list) Setiap item daftar menjadi parameter. Backend mengoptimalkan otomatis mencantumkan lebih dari 2.048 item ke dalam tabel sementara.
prefetch_related() Setiap ID objek induk menjadi parameter dalam klausa kueri WHERE IN terkait. Dioptimalkan secara otomatis seperti filter(field__in=...) saat lebih dari 2.048 ID.
bulk_create() Setiap bidang dari setiap objek menjadi parameter. Model dengan 10 bidang dan 250 objek menghasilkan 2.500 parameter.
bulk_update() Setiap bidang menggunakan dua parameter per objek (satu untuk pencocokan PK, satu untuk nilai).
Q() dengan banyak kondisi Setiap nilai dalam objek yang dirantai Q menjadi parameter.

Atur batch_size operasi massal dan potongan kueri besar IN . Lihat Penyetelan performa untuk solusi.

Batasan operasi massal

Batasan kerangka kerja pengujian

--keepdb diperlukan saat menggunakan autentikasi identitas terkelola (ActiveDirectoryMsi) karena pelari pengujian tidak dapat membuat atau menghancurkan database dengan metode autentikasi tersebut.

Untuk informasi lebih lanjut, lihat Uji aplikasi Django dengan SQL Server.

Catatan khusus versi

mssql-django versi Notes
1.7.3 Diperbaiki FA001 untuk Authentication= mode selain ActiveDirectoryMsi. Diperbaiki KeyError pada subkelas DatabaseWrapper (regresi dari 1.7.1).
1.7.2 Penanganan zona waktu tetap untuk datetimeoffset dan Now() dengan USE_TZ=True. Memperbaiki .explain() kompatibilitas untuk Django 4.0 dan yang lebih baru.
1.7.1 Database SQL di Fabric (EngineEdition 12) memperbaiki. Perbaikan indeks AlterField menurun.
1.7 Driver ODBC 18 adalah default. Django 6.0, Python 3.14, SQL Server 2025 dukungan ditambahkan.
1.6 Dukungan Django 5.1 dan 5.2. Fungsionalitas JSON yang ditingkatkan.
1.5 Perbaikan bug untuk AutoField, pemformatan parameter, dan kueri skema.
1.4 Dukungan Django 5.0. db_comment dukung.
1.3 Dukungan Django 4.2.
1.2 Dukungan Django 4.1. Dukungan zona waktu. return_rows_bulk_insert opsi. Dukungan SQL Server 2022.
1.1 Dukungan Django 3.2 dan 4.0.

Catatan khusus versi Django

Versi Django Notes
5.1 inspectdb dapat memeriksa tabel dengan kunci primer komposit, tetapi tidak menghasilkan definisi model lengkap untuk mereka.
5.2 CompositePrimaryKey Dukungan bersifat parsial. inspectdb masih memerlukan perbaikan manual, perbandingan tuple terhadap subquery membutuhkan Django 5.2.4 dan versi yang lebih baru, dan beberapa migrasi ditambah JSONField massal/CASE WHEN jalur pembaruan masih memiliki pengecualian uji. Untuk informasi selengkapnya, lihat repositori GitHub.
6.0 Membutuhkan Python 3.12 dan versi yang lebih baru. Semua batasan 5.2 berlaku. Backend menangani semua perubahan API 6.0 secara transparan.

Menyiapkan pencarian ekspresi bebas

mssql-django Backend mendukung Django __regex dan __iregex pencarian, tetapi mereka memerlukan langkah pengaturan satu kali. Backend mengirimkan rakitan CLR (regex_clr.dll) yang menyediakan dbo.REGEXP_LIKE fungsi ke SQL Server.

Prasyarat

  • Instans SQL Server yang mendukung integrasi CLR. SQL Server lokal dan Azure SQL Managed Instance mendukung CLR. Azure SQL Database tidak mendukung rakitan CLR, jadi __regex pencarian __iregex tidak tersedia di Azure SQL Database.
  • Pengguna yang menghubungkan harus memiliki sysadmin atau ALTER SETTINGS izin. Perintah manajemen mengaktifkan CLR secara otomatis.
  • mssql Aplikasi harus berada di INSTALLED_APPS.

Instal rakitan CLR

Jalankan perintah manajemen, teruskan nama database Anda:

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

Perintah ini melakukan langkah-langkah berikut:

  1. Mengaktifkan CLR di server (sp_configure 'clr enabled', 1) jika belum diaktifkan.
  2. Diatur clr strict security ke 0 (diperlukan untuk SAFE rakitan di SQL Server 2017+).
  3. Membuat regex_clr rakitan dari DLL yang dibundel.
  4. Membuat dbo.REGEXP_LIKE fungsi skalar.

Perhatian

Pengaturan clr strict security untuk 0 mengizinkan rakitan CLR yang tidak ditandatangani untuk dimuat. Ini diperlukan karena bundel regex_clr.dll tidak ditandatangani. Diskusikan perubahan ini dengan DBA Anda sebelum menjalankan perintah di server produksi. Pengaturan ini berlaku di seluruh server, bukan per database.

Menggunakan pencarian ekspresi bebas

Setelah menginstal rakitan, gunakan __regex dan __iregex dalam queryset:

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

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

Backend menerjemahkan pencarian ini menjadi dbo.REGEXP_LIKE(column, pattern, case_flag) = 1.

Note

Anda harus menjalankan install_regex_clr perintah sekali per database. Jika database dihilangkan dan dibuat ulang (misalnya, selama pengujian), jalankan perintah lagi.

Konten terkait

  • Last updated on