Referensi konfigurasi mssql-django

Artikel ini adalah referensi konfigurasi lengkap settings.py untuk backend basis mssql-django data Django. Konfigurasikan konektivitas SQL Server dengan mengedit DATABASES kamus dalam file proyek settings.py Django anda.

Konfigurasi minimal

Contoh berikut menunjukkan konfigurasi minimum yang diperlukan untuk jalur default pyodbc :

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

Untuk menjalankan alias sebagai mssql-python gantinya, atur python_driver dan hilangkan driver. Jalur mengabaikan mssql-pythondriver:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<database>",
        "USER": "<user_id>",
        "PASSWORD": "<password>",
        "HOST": "<server>",
        "PORT": "1433",
        "OPTIONS": {
            "python_driver": "mssql_python",
        },
    },
}

ENGINE Tetap di "mssql" kedua jalur. Alias dalam proyek yang sama dapat menggunakan driver yang berbeda. Untuk daftar lengkap perbedaan perilaku, lihat Pilih driver database untuk mssql-django.

Kecuali disebutkan, contoh di sisa artikel ini menunjukkan jalur default pyodbc .

Pengaturan koneksi database

Pengaturan ini mengonfigurasi koneksi Anda DATABASES . Sebagian besar adalah pengaturan Django standar; Pengecualian dicatat:

Pengaturan	Tipe	Description
`ENGINE`	String	Harus berupa `"mssql"` .
`NAME`	String	Nama database. Dibutuhkan.
`HOST`	String	Nama host server atau alamat IP. Gunakan `"server\\instance"` format untuk instans bernama.
`PORT`	String	Port instans server. String kosong berarti port default.
`USER`	String	Nama pengguna database. Jika tidak diberikan, Keamanan Terintegrasi Windows digunakan.
`PASSWORD`	String	Kata sandi pengguna database.
`AUTOCOMMIT`	Boolean	Atur ke `False` untuk menonaktifkan manajemen transaksi Django. Defaultnya adalah `True`.
`Trusted_Connection`	String	Atur ke `"yes"` (default) untuk menggunakan Keamanan Terintegrasi Windows saat `USER` tidak disediakan. Ketika `USER` dan `PASSWORD` keduanya ditetapkan, kredensial tersebut diutamakan dan `Trusted_Connection` diabaikan. Atur ke `"no"` untuk menonaktifkan Windows authentication secara eksplisit. Ini adalah ekstensi `mssql-django` , bukan pengaturan Django standar.
`TOKEN`	String	Token akses untuk autentikasi Microsoft Entra (misalnya, melalui `azure.identity`). Ini adalah ekstensi `mssql-django` , bukan pengaturan Django standar.

Pengaturan TEST

Pengaturan ini mengontrol database uji yang digunakan oleh pelari uji Django:

Pengaturan	Tipe	Description
`NAME`	String	Uji nama database. Standar: `"test_" + NAME`.
`COLLATION`	String	Kolase untuk database pengujian. Default: default instans.
`DEPENDENCIES`	List	Dependensi urutan pembuatan database.
`MIRROR`	String	Alias database untuk dicerminkan selama pengujian.

Contoh:

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",
        },
        "TEST": {
            "NAME": "test_mydb",
            "COLLATION": "SQL_Latin1_General_CP1_CI_AS",
        },
    },
}

OPSI

Kamus OPTIONS menyediakan konfigurasi khusus backend. Tempatkan pengaturan ini di dalam DATABASES["default"]["OPTIONS"] kamus:

Option	Tipe	Default	Description
`python_driver`	String	Belum diatur	Atur ke untuk `"mssql_python"` menghubungkan alias ini melalui `mssql-python` driver. Tidak mengatur atau `"pyodbc"` mempertahankan driver default `pyodbc` . Lihat Pilih driver database untuk mssql-django.
`driver`	String	`"ODBC Driver 18 for SQL Server"`	Driver ODBC untuk digunakan. Secara otomatis kembali ke Driver 17 jika 18 tidak diinstal. Diabaikan di `mssql-python` jalan.
`isolation_level`	String	`None`	Tingkat isolasi transaksi: `READ UNCOMMITTED`, , `READ COMMITTED`, `REPEATABLE READSNAPSHOT`, atau `SERIALIZABLE`.
`dsn`	String	`None`	Bernama DSN. Dapat digunakan sebagai pengganti `HOST`. Diabaikan di `mssql-python` jalan.
`host_is_server`	Boolean	`False`	Atur ke `True` untuk digunakan`HOST`/`PORT`langsung dengan FreeTDS, bukan `freetds.conf` nama server data. Diabaikan di `mssql-python` jalan.
`unicode_results`	Boolean	`False`	Aktifkan fitur pyodbc `unicode_results` . Diabaikan di `mssql-python` jalan.
`extra_params`	String	`None`	Parameter string koneksi tambahan dalam format`"param=value;param=value"`. Digunakan untuk autentikasi Microsoft Entra. Path memvalidasi `mssql-python` ini terhadap daftar izin.
`collation`	String	`None`	Penyusunan untuk pencarian bidang teks (misalnya, `"Chinese_PRC_CI_AS"`).
`connection_timeout`	Integer	`0`	Batas waktu koneksi dalam hitungan detik (`0` = dinonaktifkan). Gunakan setidaknya 60 untuk Azure SQL Database serverless dengan auto-pause diaktifkan. Basis data yang dijeda secara otomatis akan dilanjutkan kembali saat percobaan koneksi pertama, dan percobaan tersebut dapat gagal dengan kesalahan 40613 selama basis data dilanjutkan kembali, sehingga aplikasi harus mencoba lagi. Untuk informasi lebih lanjut, lihat Auto-pause dan auto-resume.
`connection_retries`	Integer	`5`	Jumlah upaya percobaan ulang koneksi.
`connection_retry_backoff_time`	Integer	`5`	Waktu mundur dalam hitungan detik di antara percobaan ulang.
`query_timeout`	Integer	`0`	Batas waktu kueri dalam hitungan detik (`0` = dinonaktifkan).
`setencoding` / `setdecoding`	List	`None`	Konfigurasi pengkodean dan dekoding diteruskan ke metode koneksi driver yang dipilih. Setiap `setdecoding` entri membutuhkan `sqltype` kunci di kedua jalur, dan entri yang sama berlaku di kedua driver. `mssql-python` menerima `-99` untuk `SQL_WMETADATA`, dan `pyodbc` menolaknya. Lihat referensi pengkodean dan dekoding pyodbc.
`return_rows_bulk_insert`	Boolean	`False`	Izinkan baris yang ditampilkan dari sisipan massal. Harus jika `False` tabel memiliki pemicu.
`datefirst`	Integer	`7`	Hari pertama dalam seminggu untuk `SET DATEFIRST`. `7`adalah hari Minggu (default SQL Server), `1` adalah Senin.
`driver_needs_utf8`	Opsi hanya kehadiran	Belum diatur	Aktifkan pengkodean UTF-8 untuk driver ODBC. Opsi ini diaktifkan ketika kunci hadir di `OPTIONS`; nilai itu sendiri diabaikan. Biasanya diperlukan dengan FreeTDS atau konfigurasi unixODBC yang lebih lama yang default ke Latin-1.
`driver_charset`	String	`None`	Kumpulan karakter eksplisit untuk driver ODBC (misalnya, `"UTF-8"`). Gunakan dengan `driver_needs_utf8` saat driver tidak mendeteksi pengkodean secara otomatis.
`connection_recovery_interval_msec`	Float	`0.0`	Milidetik untuk menunggu di antara upaya coba lagi di loop pemulihan koneksi backend setelah kesalahan jaringan. Tingkatkan nilai ini untuk tautan jaringan yang tidak stabil.

Contoh dengan opsi umum:

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": "Encrypt=yes",
            "isolation_level": "READ COMMITTED",
            "connection_timeout": 30,
            "connection_retries": 3,
            "connection_retry_backoff_time": 5,
            "query_timeout": 60,
        },
    },
}

Pengaturan khusus backend

Pengaturan ini ditempatkan di tingkat modul di settings.py, di luar DATABASES kamus:

Pengaturan	Tipe	Default	Description
`DATABASE_CONNECTION_POOLING`	Boolean	`True`	Atur ke untuk `False` menonaktifkan pooling koneksi tingkat driver. Berlaku untuk kedua dan `pyodbcmssql-python`.

Contoh:

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

# Set this to False to disable driver-level connection pooling
DATABASE_CONNECTION_POOLING = False

Saran dan Komentar

Apakah halaman ini membantu?

Terakhir diperbarui pada 2026-10-17