Pilih driver database untuk mssql-django

Mulai dari versi 2.0, mssql-django terhubung melalui salah satu dari dua driver database Python:

  • pyodbc dengan Microsoft ODBC Driver untuk SQL Server yang terpasang secara eksternal. Driver ini adalah driver bawaan.
  • mssql-python, driver Python dari Microsoft, yang tidak memerlukan driver ODBC yang terpasang secara terpisah.

Anda memilih driver untuk setiap alias database. Satu alias dapat menggunakan mssql-python, sementara bagian proyek lainnya tetap menggunakan pyodbc. Nilai ENGINE tetap "mssql" dalam kedua kasus.

Pilih alias ke mssql-python

Atur opsi python_driver dalam kamus OPTIONS milik alias tersebut:

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

Backend menerima "mssql_python", "mssql-python", dan "python", dan perbandingan mengabaikan kasus. Hilangkan python_driver, biarkan kosong, atau atur agar "pyodbc" driver default tetap ada. Karena pengaturan ini diterapkan per alias, Anda mengembalikan satu database satu per satu dengan menghapus opsi tersebut.

Modul mssql-python hanya diimpor ketika alias memilihnya. Jika versi yang terpasang lebih rendah dari 1.15.0, backend akan memunculkan ImproperlyConfigured beserta versi yang diperlukan.

Persyaratan penginstalan

pip install mssql-django menginstal kedua driver. mssql-python Jalur ini tidak memerlukan instalasi terpisah untuk driver ODBC. Instalasi --no-deps , atau indeks privat yang tidak mencerminkan mssql-python, membuat paket hilang dan alias gagal saat impor.

Instal prasyarat platform untuk mssql-python, termasuk OpenSSL di macOS dan pustaka yang diperlukan di Linux.

Karena mssql-python merupakan dependensi wajib, mssql-django 2.0 hanya diinstal pada platform yang memiliki distribusi kompatibel mssql-python . Untuk daftar platform, lihat dukungan dan siklus hidup mssql-django.

Perbedaan perilaku

Kedua driver membangun string koneksi yang berbeda dan menampilkan kata kunci koneksi yang berbeda. Tinjau bagian ini sebelum Anda mengganti alias.

Pengaturan koneksi

Setting pyodbc mssql-python
HOST dan PORT Dipancarkan sebagai SERVER, SERVERNAME, atau SERVER plus PORT, tergantung pada driver dan host_is_server. Selalu dipancarkan sebagai SERVER=<host>,<port>. Bagian kosong HOST menjadi localhost.
driver Memilih driver ODBC. Secara default menggunakan Microsoft ODBC Driver 18 for SQL Server, dengan beralih otomatis ke Driver 17. Diabaikan. Tidak ada opsi cadangan Driver 17.
dsn Supported. Diabaikan.
host_is_server Didukung untuk FreeTDS. Diabaikan.
unicode_results Supported. Diabaikan.
TOKEN Supported. Supported. Pasokan TOKEN tanpa USER, PASSWORD, atau kata Authentication kunci. Aplikasi Anda memperoleh dan memperbarui token.
DATABASE_CONNECTION_POOLING Berlaku. Berlaku.

Timeout, percobaan ulang, tingkat isolasi, kolasi, dan return_rows_bulk_insert berperilaku sama pada kedua jalur.

Parameter koneksi tambahan

mssql-python 1.15 memvalidasi extra_params terhadap daftar izin dan menolak apa pun di luar daftar tersebut. Kata kunci yang didukung meliputi Authentication, Encrypt, TrustServerCertificate, HostnameInCertificate, ServerCertificate, ServerSPN, ConnectRetryInterval, ApplicationIntent, MultiSubnetFailover, KeepAlive, KeepAliveInterval, ConnectRetryCount, IpAddressPreference, dan PacketSize.

Driver menolak MARS_Connection, APP, LongAsMax, dan ColumnEncryption, serta kata kunci khusus pyodbc seperti WSID, AnsiNPW, QuotedId, Current Language, Description, Network Library, Regional, UseFMTONLY, Connect Timeout, SERVERNAME, DSN, dan DRIVER. Hapus kata kunci tersebut sebelum Anda mengganti alias, dan gunakan opsi sebagai connection_timeout pengganti Connect Timeout.

Ketika extra_params menetapkan kata kunci yang juga dihasilkan backend, nilai eksplisit yang menang.

Beberapa Set Hasil Aktif

Pada jalur pyodbc, backend menambahkan MARS_Connection=yes saat alias menggunakan driver Microsoft ODBC di Windows. Nilai eksplisit MARS_Connection dalam extra_params dihormati sebagai gantinya, dan kecocokan mengabaikan kasus.

mssql-python Path tidak pernah mengaktifkan MARS, dan MARS_Connection menolak kata kunci, jadi Anda tidak bisa mengaktifkan MARS untuk alias tersebut.

Tanpa MARS, QuerySet.iterator() membaca seluruh hasil ke dalam memori sebelum mengembalikan baris-baris hasil sehingga kueri bersarang dapat menggunakan kembali koneksi, dan chunk_size tidak mengubah hal tersebut. Perhitungkan biaya memori untuk kumpulan kueri berukuran besar.

Untuk endpoint yang menolak MARS, seperti Microsoft Fabric Warehouse, lihat Nonaktifkan MARS.

Konfigurasi pengkodean

Kedua driver menerima setencoding dan setdecoding, dan setiap entri menuju metode koneksi dari driver yang dipilih. Setiap entri setdecoding memerlukan kunci sqltype pada kedua jalur, dan entri yang sama dapat digunakan pada salah satu driver. Satu perbedaan: mssql-python menerima -99 untuk SQL_WMETADATA, dan pyodbc menolaknya.

Pilih salah satu driver

Untuk pengembangan baru, gunakan mssql-python. Menghilangkan langkah instalasi driver ODBC dari citra kontainer dan penerapan layanan aplikasi.

Gunakan pyodbc ketika penerapan Anda bergantung pada DSN bernama, FreeTDS, Always Encrypted melalui kata kunci ColumnEncryption, versi driver ODBC yang Anda kelola sendiri, atau MARS. Untuk apa yang dibutuhkan MARS pada setiap jalur, lihat Multiple Active Result Sets.

Proyek yang sudah ada dapat tetap menggunakan pyodbc. Tetap menjadi default dan didukung sepenuhnya. Saat Anda mulai memindahkan, ganti satu alias pada satu waktu dan jalankan rangkaian pengujian Anda terhadapnya sebelum memindahkan yang lainnya.

Konten terkait

  • Terakhir diperbarui pada