Pertanyaan yang Sering Diajukan mssql-django

Artikel ini menjawab pertanyaan yang sering diajukan tentang backend mssql-django Django untuk SQL Server, Azure SQL Database, Azure SQL Managed Instance, dan database SQL di Microsoft Fabric.

General

Apa itu mssql-django?

Paket ini mssql-django adalah backend database Django yang dikelola Microsoft untuk SQL Server. Ini memungkinkan aplikasi Django terhubung ke SQL Server, Azure SQL Database, Azure SQL Managed Instance, dan database SQL di Microsoft Fabric. Versi 2.0 dan versi yang lebih baru terhubung melalui pyodbc driver, yang merupakan default, atau melalui driver Microsoftmssql-python.

Instal menggunakan pip:

pip install mssql-django

Versi Django apa yang didukung mssql-django?

Versi mssql-django paket 2.0 mendukung Django 5.2, 6.0, dan 6.1. Proyek di Django 3.2 hingga 5.1 tetap pada versi 1.8.0. Periksa siklus hidup dukungan untuk matriks kompatibilitas penuh.

Versi Python apa yang didukung?

Versi mssql-django paket 2.0 mendukung Python 3.10 hingga 3.14. Versi Python spesifik juga harus kompatibel dengan versi Django Anda: Django 5.2 diuji dengan Python 3.10 hingga 3.13, dan Django 6.0 serta 6.1 diuji dengan Python 3.12 hingga 3.14. Lihat Siklus hidup dukungan untuk matriks kompatibilitas penuh.

Driver database Python mana yang digunakan mssql-django?

Versi 2.0 dan versi berikutnya mendukung dua driver, yang dipilih untuk setiap alias database. pyodbcadalah default dan membutuhkan Microsoft ODBC Driver untuk SQL Server yang terpasang secara eksternal. Untuk menggunakan driver Microsoft mssql-python sebagai gantinya, yang tidak memerlukan instalasi driver ODBC terpisah, tambahkan python_driver ke kamus alias OPTIONS tersebut:

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

Alias yang menghilangkan opsi tetap menggunakan pyodbc. Untuk perbedaan perilaku antara kedua jalur, lihat Pilih driver database untuk mssql-django.

Apakah mssql-django dikelola oleh Microsoft?

Yes. Paket mssql-django ini dikelola oleh Microsoft dan tersedia di PyPI dan GitHub.

Konfigurasi

Nilai ENGINE apa yang saya gunakan di settings.py?

Atur ENGINE ke "mssql" dalam konfigurasi Anda DATABASES :

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

Driver ODBC mana yang harus saya gunakan?

Pada jalur defaultpyodbc, gunakan Microsoft ODBC Driver 18 untuk SQL Server. Itu adalah versi default, dan backend secara otomatis kembali ke ODBC Driver 17 jika versi 18 tidak terpasang. Tentukan driver secara eksplisit dalam kamus OPTIONS hanya jika Anda perlu mengunci versi tertentu, yang juga menonaktifkan fallback:

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

Jalur mssql-python mengabaikan opsi driver dan menggunakan ODBC Driver 18 yang diinstal oleh pip bersamanya.

Bagaimana cara menyambungkan ke Azure SQL Database?

Gunakan nama server yang sepenuhnya memenuhi syarat dengan port 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",
        },
    },
}

Bagaimana cara menggunakan autentikasi Microsoft Entra?

Gunakan extra_params di OPTIONS atau di setelan TOKEN. Pengaturan TOKEN ini berfungsi dengan kredensial apa pun azure.identity , termasuk DefaultAzureCredential dan ManagedIdentityCredential.

from azure.identity import DefaultAzureCredential

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

"TOKEN": token,

Lihat autentikasi Microsoft Entra untuk semua metode yang didukung.

Features

Apakah mssql-django mendukung JSONField?

Ya, JSONField didukung pada SQL Server 2016 dan yang lebih baru. Data JSON disimpan sebagai nvarchar(max) dan dikueri menggunakan fungsi JSON SQL Server. Lihat dukungan JSONField untuk pencarian dan batasan yang didukung.

Apakah mssql-django mendukung tanggal dan waktu yang menyertakan informasi zona waktu?

Yes. Ketika USE_TZ=True, Django menggunakan jenis data datetimeoffset dalam SQL Server. Jika Anda memigrasikan database yang sudah ada, Anda perlu mengubah kolom datetime2 yang sudah ada. Lihat Dukungan zona waktu.

Bisakah saya memanggil prosedur tersimpan?

Yes. Gunakan connection.cursor() dengan cursor.execute() untuk memanggil prosedur tersimpan. Lihat Prosedur tersimpan untuk contoh termasuk beberapa parameter dan tataan hasil.

Apakah bulk_create mengembalikan ID?

Secara default, tidak. Opsi return_rows_bulk_insert secara bawaan bernilai False. Atur ke True di database OPTIONS Anda untuk mengaktifkan pengembalian ID setelah penyisipan massal. Opsi ini harus tetap False untuk tabel dengan pemicu. Lihat Operasi massal.

Troubleshooting

Saya mendapatkan "Driver ODBC tidak ditemukan." Bagaimana cara memperbaikinya?

Instal Driver MICROSOFT ODBC untuk SQL Server. Di Linux, tambahkan repositori APT Microsoft terlebih dahulu lalu instal driver:

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

Di Windows, unduh penginstal dari situs web Microsoft. Di macOS, gunakan Homebrew:

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

Lihat Penginstalan untuk instruksi khusus platform lengkap.

Mengapa migrasi saya gagal dengan "Tidak dapat mengubah IDENTITY kolom"?

SQL Server tidak mendukung pengubahan kolom menjadi atau dari kolom IDENTITY (AutoField). Buat model baru dengan jenis bidang yang diinginkan dan migrasikan data secara manual. Lihat Batasan dan fitur yang tidak didukung di mssql-django.

Mengapa bulk_update gagal pada kolom yang dapat bernilai null?

Backend menangani pembaruan yang semua nilainya NULL secara otomatis. Jika Anda perlu mengontrol nilai placeholder, gunakan parameter default di dalam NULL, yang menjaga CASE WHEN ... THEN NULL tetap di luar ekspresi bulk_update yang menyebabkan kesalahan inferensi tipe SQL Server:

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

Lihat Operasi massal untuk detail lebih lanjut.

  • Terakhir diperbarui pada