Menggunakan driver mssql-odbc (Pratinjau)

mssql-python memuat salah satu dari dua penyedia ODBC asli:

Provider Apa fungsinya Status
msodbcsql18 Microsoft ODBC Driver 18 untuk SQL Server, driver C++ yang sudah mapan Default, tidak berubah
mssql-odbc Driver ODBC baru yang ditulis dalam Rust Pratinjau, opt-in

Artikel ini membahas mssql-odbc0.3.0, versi yang saat ini digunakan oleh mssql-python, dan apa yang berbeda dari msodbcsql18.

Note

mssql-odbc sedang dalam pengembangan dan validasi aktif. Ini belum sepenuhnya menjadi pengganti untuk Microsoft ODBC Driver 18. Pertahankan msodbcsql18 sebagai standar produksi Anda untuk saat ini. Tim pengembang berencana menutup kesenjangan dalam pratinjau di rilis mendatang, kecuali untuk pengecualian yang disengaja yang secara eksplisit disebutkan dalam artikel ini.

Availability

Driver dikirim di dalam paket mssql-python-rs sebagai prebuilt wheel untuk CPython 3.10 dan versi lebih baru:

Platform Architectures
Windows x64; ARM64 di CPython 3.11+
macOS universal2 (x86_64 + arm64), macOS 15 atau lebih baru
Linux (glibc) x86_64, aarch64 — manylinux_2_28 dan manylinux_2_34
Linux (musl) x86_64, Aarch64 — musllinux_1_2

Mengaktifkan driver

Paket mssql-python tergantung pada mssql-python-rs, jadi instalasi normal membawa driver Rust bersamanya:

pip install mssql-python

Jika Anda menginstal dengan --no-deps atau dari indeks privat, instal mssql-python-rs juga secara eksplisit.

Pilih penyedia sebelum koneksi pertama, baik dengan variabel lingkungan:

PowerShell:

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

Bash atau Zsh:

export MSSQL_PYTHON_NATIVE_PROVIDER=mssql-odbc

atau dari Python:

import mssql_python

mssql_python.native_provider = "mssql-odbc"

Terhubung dengan menggunakan string koneksi aplikasi Anda yang sudah ada. Aktifkan validasi sertifikat (Encrypt=yes;TrustServerCertificate=no). Untuk autentikasi dan pengaturan sertifikat, lihat Connection strings dan Enkripsi serta sertifikat.

connection = mssql_python.connect(connection_string)

Driver menerapkan aturan berikut saat memilih penyedia:

  • Variabel MSSQL_PYTHON_NATIVE_PROVIDER lingkungan memiliki prioritas atas native_provider. Penetapan atribut yang bertentangan menghasilkan RuntimeWarning.
  • Seleksi dikunci setelah validasi string koneksi dan segera sebelum koneksi asli dibangun. Kegagalan koneksi berikutnya tidak menghapus seleksi. Kesalahan parsing string koneksi sebelumnya atau paket penyedia yang hilang tidak memengaruhi pilihan. Setelah seleksi ditetapkan, beralih native_provider ke penyedia lain akan memicu RuntimeWarning dan tidak berpengaruh. Mulai ulang proses untuk mengganti penyedia.
  • Nama penyedia yang tidak dikenali menyebabkan ValueError; driver tidak beralih ke penyedia default. Nama yang tidak dikenal yang ditetapkan ke native_provider segera memunculkan error. Nama yang tidak dikenal dalam variabel lingkungan memunculkan kesalahan saat Anda mencoba menghubungkan.
  • Atur native_provider ke None untuk menghapus pilihan atribut sebelum menjadi tetap. Variabel lingkungan tetap menjadi prioritas.

Hubungi mssql_python.get_native_provider_info() untuk memeriksa penyedia yang dipilih, sumber seleksi, dan apakah seleksi bersifat tetap. Sebelum terhubung, ini hanya menunjukkan pilihan yang dipilih, bukan bukti bahwa driver native telah berhasil dimuat.

Untuk kembali, atur variabel ke msodbcsql18, atau biarkan tidak disetel dan hapus semua penetapan native_provider dari kode Anda (atau atur ke "msodbcsql18"). Kemudian mulai ulang prosesnya.

Yang berfungsi saat ini

Driver mssql-odbc mengimplementasikan setiap fungsi ODBC yang dipanggil oleh mssql-python, sehingga sebagian besar aplikasi dapat berganti penyedia tanpa perubahan kode. Periksa Masalah yang Diketahui untuk perbedaan yang tersisa.

Area Notes
Siklus hidup koneksi Connect, close(), with blok, batas waktu login, diagnostik, dan mengubah database saat ini. Pengaturan connection-string meliputi ConnectRetryInterval, ConnectRetryCount, / , KeepAlive, PacketSize, dan IpAddressPreferenceMultiSubnetFailoverApplicationIntent (ketahanan koneksi idle).
Authentication autentikasi SQL (UID / PWD); autentikasi Windows (Trusted_Connection=Yes, menggunakan SSPI di Windows atau Kerberos di Linux dan macOS); serta interaktif Microsoft Entra, kode perangkat, prinsipal layanan, identitas terkelola, kredensial default, dan token akses. Autentikasi terintegrasi Entra dan autentikasi kata sandi tidak didukung; lihat Masalah yang diketahui.
TLS Encrypt, TrustServerCertificate, HostnameInCertificate, dan ServerCertificate.
Pelaksanaan kueri Eksekusi langsung dan yang disiapkan, penggunaan ulang rencana yang sudah disiapkan, qmark parameter, dan konversi pyformatmssql-python lakukan.
Sintaks escape ODBC Bentuk fungsi, tanggal/waktu, outer-join, GUID, LIKE ... {escape ...}, interval, dan {encrypt ...} escape.
Prosedur yang disimpan Panggil mereka dengan T-SQL atau sintaks posisional {call ...} melalui execute(), baca set hasil, dan lanjutkan dengan nextset().
Parameter masukan Parameter skalar, SQL NULL, setinputsizes(), dan parameter reguler/streaming campuran.
Parameter berukuran besar Parameter teks dan biner besar mengalir ke server melalui jalur binding biasa; Batasan parameter XML dan UDT tercantum di bawah ini.
executemany() Diproses secara batch dengan array parameter ODBC. Baris yang berisi nilai streaming beralih ke eksekusi baris demi baris.
Pengambilan baris fetchone(), fetchmany(), fetchall(), iterasi, fetchval(), konversi bertipe, dan streaming teks/biner besar.
Mengambil Arrow arrow_batch(), arrow(), dan arrow_reader(). Membutuhkan pyarrow.
Beberapa kumpulan hasil nextset(), termasuk hasil yang dihasilkan oleh array parameter.
Transactions Autocommit, commit, rollback, commit otomatis (atau rollback, jika error keluar) yang terjadi saat blok with connect(...) berakhir, serta level isolasi read-uncommitted, read-committed, repeatable-read, serializable, dan snapshot isolation.
Waktu kueri habis Atur Connection.timeout (dalam detik) untuk membatasi pernyataan yang dijalankan oleh kursor koneksi tersebut; kedaluwarsa memicu OperationalError. 0 Artinya tidak ada timeout. Pengaturan ini terpisah dari timeout login yang diberikan sebagai connect(timeout=...).
Pemanfaatan koneksi Pool bawaanmssql-python, termasuk reset koneksi saat checkout dan pool terpisah per identitas Microsoft Entra.
API Metadata tables(), columns(), primaryKeys(), foreignKeys(), statistics(), rowIdColumns(), rowVerColumns(), procedures(), dan getTypeInfo().
Pengkodean dan konverter Pengkodean karakter lebar dan konverter output default. Decoding narrow-character khusus dan konversi parameter non-Unicode memiliki keterbatasan yang tercantum di Isu yang diketahui.

Jenis data

Anda dapat membaca semua tipe data SQL Server, dan driver mendukung setiap tipe parameter yang diikat oleh mssql-python. Driver mengembalikan nilai xml, vector, dan str sebagai vector (geometry sebagai array JSON), serta tipe CLR seperti geography, hierarchyid, dan bytes sebagai json. Untuk pemetaan Python lainnya, lihat Pemetaan tipe data. Untuk batasan spesifik tipe, lihat Masalah yang diketahui.

Masalah yang diketahui

Periksa perbedaan ini sebelum mengalihkan beban kerja dari msodbcsql18.

Issue Details Workaround
Autentikasi terintegrasi Microsoft Entra Authentication=ActiveDirectoryIntegrated tidak didukung. Windows authentication (Trusted_Connection=Yes) tidak terpengaruh. Gunakan metode Microsoft Entra lain, atau biarkan msodbcsql18 tetap ada.
Autentikasi kata sandi Microsoft Entra Authentication=ActiveDirectoryPassword tidak didukung, dan dukungan tidak direncanakan karena metode ini tidak dapat memenuhi persyaratan MFA. Autentikasi SQL (UID / PWD) tidak terpengaruh. Gunakan metode Microsoft Entra lain, seperti service principal, managed identity, atau access token.
attrs_before Pengaturan Autentikasi, application intent, dan failover multi-subnet tidak dapat diatur sebagai atribut numerik. Atribut pernyataan selain timeout kueri ditolak. Gunakan kata kunci connection-string yang setara.
Timeout operasi koneksi set_attr(SQL_ATTR_CONNECTION_TIMEOUT, ...) menerima dan menyimpan nilai, tetapi tidak menerapkan timeout di 0.3.0. Gunakan connect(timeout=...) untuk login dan Connection.timeout untuk statement; keduanya tidak satu pun merupakan tenggat waktu operasi koneksi umum.
Host dengan banyak alamat msodbcsql18 mengaktifkan Resolusi IP Jaringan Transparan (TNIR) secara default; mssql-odbc tidak mendukungnya. mssql-python menolak TransparentNetworkIPResolution kata kunci connection-string dengan kedua penyedia. Tanpa MultiSubnetFailover=Yes, alamat dicoba satu per satu, sehingga alamat yang tidak dapat dijangkau dapat menunda koneksi. Caching DNS berbantuan server dan routing yang ditingkatkan tidak dinegosiasikan. Atur MultiSubnetFailover=Yes untuk availability group listener dan host multi-alamat lainnya.
Kegagalan DNS sementara Jika pencarian DNS gagal, driver tidak beralih ke alamat terakhir yang berhasil. (#457) Coba lagi koneksi.
Klasifikasi data Metadata klasifikasi sensitivitas tidak tersedia, dan SQL_COPT_SS_DATACLASSIFICATION_VERSION (1400) tidak didukung. Query sys.sensitivity_classifications.
Multithreading Penggunaan multithreaded belum divalidasi. Pertahankan msodbcsql18 untuk beban kerja multithreaded.
fork() setelah terhubung Di Linux, proses yang di-fork setelah induk terhubung dapat macet saat menggunakan driver, bahkan dengan koneksi baru. Dengan pooling diaktifkan, induk juga bisa macet. (#566) Gunakan metode start spawn dan lakukan koneksi di dalam setiap pekerja.
Membatalkan statemen yang sedang berjalan Kueri atau pengambilan yang sedang berjalan tidak dapat diinterupsi. Misalnya, menutup an arrow_reader() tidak menghentikan pembacaan yang sedang berlangsung pada thread lain. Gunakan Connection.timeout untuk membatasi statement yang berjalan lama.
Hasil yang belum dibaca Menutup kursor atau menjalankan pernyataan lain akan membaca dan membuang hasil yang tersisa alih-alih membatalkannya, yang bisa lambat. Menutup kursor yang menggunakan pernyataan prepared mengabaikan Connection.timeout dan dapat terhenti jika server berhenti merespons. (#546) Ambil hanya baris yang Anda butuhkan, misalnya dengan TOP.
Parameter besar xml dan UDT Nilai yang terikat sebagai SQL_SS_XML atau SQL_SS_UDT hingga setinputsizes() dibuffer di memori, bukan di-stream. Ikat nilai xml sebagai string biasa.
Nilai kosong image Nilai SQL Server image kosong yang bukan NULL dikembalikan sebagai None pengganti b"". Baca CAST(image_column AS varbinary(max)), atau gunakan msodbcsql18 ketika perbedaan antara kosong dan NULL penting.
Parameter non-Unicode string String yang diikat sebagai char / varchar hingga setinputsizes() dapat dikodekan secara salah untuk kolasi halaman kode 437, halaman kode 850, dan UTF-8. Gunakan binding string default.
Dekode code page warisan di Windows Dengan setdecoding(SQL_CHAR, encoding="cp1252") atau halaman kode warisan lainnya, teks dapat didekode secara salah atau dikembalikan sebagai bytes, karena driver mengembalikan char / varchar data sebagai UTF-8. Gunakan default: conn.setdecoding(mssql_python.SQL_CHAR).
Connection.getinfo() SQL_USER_NAME mengembalikan connection-string UID, bukan pengguna database. Kosong saat tidak ada UID yang sampai ke driver. Beberapa nilai kapabilitas dan batas ukuran paket berbeda dari msodbcsql18. Gunakan SELECT USER_NAME() untuk pengguna basis data.
Kegagalan akibat kehabisan memori Beberapa kegagalan alokasi driver mengakhiri proses Python alih-alih memunculkan MemoryError. (#484) Batasi ukuran nilai yang Anda kirim dan ambil kembali.
Performa pembacaan nilai besar Dalam satu benchmark, pembacaan data varchar(max)nvarchar(max) / per chunk sedikit lebih lambat dibandingkan dengan msodbcsql18. (#473) Bandingkan tolok ukur beban kerja Anda.

Daftar ini tidak lengkap.

Melaporkan masalah

Jika Anda menemui bug, pilih msodbcsql18, restart proses, dan periksa apakah perilaku tersebut masih terjadi. Juga hapus penugasan penyedia sisi Python yang bertentangan. Perbandingan ini membantu mengisolasi masalah; itu sendiri tidak membuktikan penyebabnya. Sertakan output dari mssql_python.get_native_provider_info(), platform Anda, dan kueri SQL yang gagal atau pesan kesalahan:

Untuk diagnostik driver Rust, atur variabel-variabel ini sebelum memulai Python dan ulangi masalah tersebut dengan mssql-odbc dipilih. Misalnya, di PowerShell:

$env:MSSQL_TDS_TRACE = "true"
$env:MSSQL_TDS_TRACE_LEVEL = "warn,mssqlodbc=debug"
$env:MSSQL_TDS_TRACE_DIR = "./traces"

MSSQL_TDS_TRACE Mengaktifkan pelacakan, MSSQL_TDS_TRACE_LEVEL memilih filter log, dan MSSQL_TDS_TRACE_DIR menulis file per proses alih-alih ke stderr. Restart Python setelah mengubah pengaturan ini. Jejak dapat berisi teks SQL dan nilai parameter. Tinjau dan samarkan data sensitif sebelum membagikan kutipan yang relevan, serta nonaktifkan pelacakan setelah diagnosis.

Konten terkait

  • Terakhir diperbarui pada