Gunakan driver mssql-odbc (Pratinjau)

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

Provider Description Status
msodbcsql18 Microsoft ODBC Driver 18 untuk SQL Server Default
mssql-odbc Driver ODBC berbasis Rust Pratinjau, opt-in

Artikel ini membahas penyedia mssql-odbc yang disertakan dalam mssql-python-rs 0.5.0 dan apa yang berbeda dari msodbcsql18.

Note

Gunakan msodbcsql18 untuk beban kerja produksi. Sebelum Anda ikut serta dalam penyedia pratinjau mssql-odbc, tinjau masalah yang sudah diketahui.

Availability

Driver dikirim di dalam paket mssql-python-rs sebagai wheel bawaan untuk CPython 3.10 dan versi berikutnya:

Platform Architectures
Windows x64; ARM64 pada CPython 3.11 dan versi setelahnya
macOS universal2 (x86_64 dan arm64), macOS 15 dan versi setelahnya
Linux (glibc) x86_64 dan aarch64 (manylinux_2_28 dan manylinux_2_34)
Linux (musl) x86_64 dan aarch64 (musllinux_1_2)

Aktifkan driver

Instalasi mssql-python juga menginstal mssql-python-rs, yang berisi mssql-odbc driver:

python -m pip install mssql-python

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

Pilih penyedia sebelum membuka koneksi pertama. Gunakan salah satu metode berikut.

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

Atur variabel lingkungan MSSQL_CONNECTION_STRING ke string koneksi aplikasi Anda. Aktifkan validasi sertifikat (Encrypt=yes;TrustServerCertificate=no). Untuk informasi lebih lanjut, lihat String koneksi dan Enkripsi serta sertifikat.

Jalankan contoh ini dengan penyedia yang Anda pilih:

import os
import mssql_python

with mssql_python.connect(os.environ["MSSQL_CONNECTION_STRING"], timeout=45) as connection:
    with connection.cursor() as cursor:
        cursor.execute("SELECT 1")
        print(cursor.fetchone()[0])

Contoh menampilkan 1.

Pemilihan penyedia mengikuti aturan berikut:

  • MSSQL_PYTHON_NATIVE_PROVIDER memiliki prioritas atas native_provider. Mengatur atribut ke penyedia yang bertentangan akan menghasilkan RuntimeWarning.
  • Sebelum driver dimuat, atur native_provider ke None untuk mereset setelan Python. Ini tidak menghilangkan variabel lingkungan.
  • Nama penyedia yang tidak dikenali menyebabkan ValueError. Menetapkan nama tidak valid untuk native_provider segera menimbulkan error; variabel lingkungan tidak valid menimbulkan error saat Anda terhubung. Driver tidak beralih ke penyedia default.
  • Penyedia ditetapkan ketika driver memulai upaya koneksi native, meskipun upaya tersebut gagal. Mulai ulang Python untuk mengganti penyedia. Beralih native_provider ke penyedia lain memunculkan RuntimeWarning dan tidak berpengaruh.

Kesalahan validasi string koneksi dan paket penyedia yang hilang terjadi sebelum titik ini. Anda dapat memperbaiki kesalahan ini dan memilih penyedia lain tanpa harus memulai ulang.

Hubungi mssql_python.get_native_provider_info() untuk memeriksa nama penyedia, bagaimana pilihan itu dipilih, dan apakah pilihan tersebut tetap.

Untuk kembali ke msodbcsql18, hapus MSSQL_PYTHON_NATIVE_PROVIDER dan penetapan native_provider apa pun dari aplikasi Anda, lalu restart Python.

Default failover multi-subnet

Penyedia Rust secara default menggunakan MultiSubnetFailover=yes untuk koneksi TCP yang memenuhi syarat. Atur MultiSubnetFailover=no untuk percobaan berurutan. Untuk mengubah default deployment, atur MSSQL_RS_MULTISUBNET_FAILOVER_DEFAULT ke true atau false (tidak sensitif huruf besar/kecil) sebelum penggunaan driver pertama. Nilai lain menyebabkan error kecuali ditimpa untuk koneksi.

Kata kunci connection-string menggantikan default lingkungan. Atribut pre-connect SQL_COPT_SS_MULTISUBNET_FAILOVER (1248) menimpa keduanya.

Default tidak termasuk transport non-TCP, pencerminan database, dan instance bernama yang memerlukan penemuan SQL Server Browser. Ini juga menolak MultiSubnetFailover=yes secara eksplisit.

Di Windows, default juga dinonaktifkan untuk target lokal tanpa awalan seperti localhost. Awalan atau port TCP eksplisit, seperti tcp:localhost atau localhost,1433, menghindari pengecualian target lokal ini. Eksplisit MultiSubnetFailover=yes juga menggantinya. Lihat Ketersediaan tinggi dan failover.

Fitur yang didukung

Fitur-fitur berikut didukung, dengan pengecualian masalah yang diketahui.

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).
Ketahanan jaringan Koneksi TCP yang memenuhi syarat secara default menggunakan upaya alamat paralel. Mode paralel tidak memprioritaskan alamat berdasarkan IpAddressPreference dan menolak lebih dari 64 alamat hasil resolusi. Untuk percobaan berurutan dan pengurutan keluarga-alamat, lihat Default failover Multi-subnet. Algoritma Transparent Network IP Resolution (TNIR) terpisah belum diimplementasikan. Caching Domain Name System (DNS) yang dibantu server memungkinkan cadangan alamat cache jika terjadi kegagalan DNS setelah login yang berhasil di mana server mengizinkan caching. Routing yang ditingkatkan digunakan saat dinegosiasikan dengan server.
Authentication autentikasi SQL (UID / PWD); autentikasi Windows (Trusted_Connection=Yes, menggunakan Security Support Provider Interface (SSPI) di Windows atau Kerberos di Linux dan macOS); dan Microsoft Entra ID interaktif, terintegrasi, kode perangkat, prinsipal layanan, identitas terkelola, kredensial default, dan token akses. Otentikasi kata sandi Microsoft Entra ID tidak didukung. Untuk informasi selengkapnya, lihat Masalah yang diketahui.
Keamanan Lapisan Transportasi (TLS) Encrypt, TrustServerCertificate, HostnameInCertificate, dan ServerCertificate. Di macOS, Encrypt=Strict koneksi TCP dapat menegosiasikan TLS 1.3 dengan server yang kompatibel.
Pelaksanaan kueri Eksekusi langsung dan yang disiapkan, penggunaan ulang rencana yang sudah disiapkan, qmark parameter, dan konversi pyformatmssql-python lakukan.
Sintaks escape ODBC Fungsi, tanggal/waktu, outer-join, identifier unik global (GUID), LIKE ... {escape ...}, interval, dan {encrypt ...} bentuk escape.
Prosedur yang disimpan Panggil mereka dengan Transact-SQL (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 Teks besar dan parameter biner mengalir ke server melalui jalur binding biasa. Eksplisit SQL_SS_XML dan SQL_SS_UDT binding juga mengalir setinputsizes() saat Python memilih data-at-execution: ukuran yang dinyatakan harus melebihi 4000 untuk str atau 8000 untuk bytes atau bytearray. User-defined type (UDT) binding mengharuskan server untuk mendeskripsikan tipe parameter tersebut. Beberapa binding kustom dan campuran masih menggunakan buffering. Untuk informasi selengkapnya, lihat Masalah yang diketahui.
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, serta tingkat isolasi read-uncommitted, read-committed, repeatable-read, serializable, dan snapshot. Dengan autocommit dimatikan, connection context manager melakukan commit pada exit yang berhasil dan melakukan rollback pada pengecualian.
Waktu kueri habis Atur Connection.timeout dalam detik sebelum membuat kursor. Ketika pernyataan melebihi timeout tersebut, driver memunculkan OperationalError. 0 Artinya tidak ada timeout. Atur timeout login secara terpisah dengan connect(timeout=...).
Timeout operasi koneksi conn.set_attr(mssql_python.SQL_ATTR_CONNECTION_TIMEOUT, seconds) berlaku untuk permintaan jaringan milik koneksi, termasuk commit, rollback, serta perubahan katalog dan isolasi. Reset gabungan menunda reset server ke permintaan pengaturan isolasi berikut; baik permintaan tersebut maupun rollback sebelumnya menggunakan timeout ini. 0 membuat permintaan tersebut tidak dibatasi. Timeout ini terpisah dari timeout login dan query dan bukan batas waktu total untuk checkout pool resource. Pembersihan pembatalan dapat menambah durasi total panggilan.
Pembersihan kursor Menutup kursor membatalkan pekerjaan server yang tertunda saat diperlukan, alih-alih membaca semua hasil yang tersisa. Pembersihan prepared statement mematuhi batas waktu kueri. Pembersihan pembatalan memiliki anggaran tunggu tambahan yang sama dengan timeout koneksi, atau 120 detik saat timeout tersebut adalah 0.
Pemanfaatan koneksi Pool bawaan mssql-python, termasuk reset koneksi sebelum digunakan kembali. Untuk isolasi pool khusus autentikasi, lihat Isolasi identitas.
Pemrosesan Multibenang Koneksi dan kueri bersamaan dengan koneksi dan kursor terpisah per pekerja. Jangan berbagi kursor antar thread.
API Metadata tables(), rowVerColumns(), getTypeInfo(), procedures(), getinfo(), rowIdColumns(), statistics(), foreignKeys(), primaryKeys(), dan columns(). SQL_USER_NAME melaporkan pengguna basis data, bukan connection-string UID. Nilai kapabilitas dan batas berdasarkan ukuran paket dapat berbeda dari msodbcsql18: SQL_NEED_LONG_DATA_LEN laporan "N" karena input panjang tidak memerlukan panjang total yang dideklarasikan. Gunakan kemampuan dan batasan yang dikembalikan.
Pengkodean dan konverter Pengkodean karakter lebar default, konverter output, parameter non-Unicode yang memperhatikan kolasi, dan hasil karakter sempit dalam pengkodean klien platform. Decoding karakter sempit khusus harus sesuai dengan pengkodean tersebut; ketidakcocokan dapat menghasilkan teks yang salah atau bytes. Gunakan conn.setdecoding(mssql_python.SQL_CHAR) untuk mengembalikan dekode karakter lebar default. Untuk substitusi parameter non-Unicode, lihat Masalah yang Diketahui.

Autentikasi terintegrasi Microsoft Entra ID menggunakan akun Windows tempat pengguna masuk di Windows. Di Linux dan macOS, ini menggunakan tiket Kerberos untuk mengautentikasi ke endpoint Layanan Federasi Direktori Aktif (AD FS) milik tenant. Untuk prasyarat, lihat Autentikasi Terintegrasi Windows.

Jika fetch berjalan saat Anda menutup arrow_reader(), close() membatalkan fetch dan kembali setelah berhenti. Menutup pembaca dari kueri sebelumnya tidak memengaruhi kueri berikutnya pada kursor yang sama. Untuk informasi lebih lanjut, lihat integrasi Apache Arrow.

Jenis data

Driver mengembalikan nilai xml, json, dan vektor sebagai objek Pythonstr, dengan vektor direpresentasikan sebagai array JavaScript Object Notation (JSON). Ini mengembalikan tipe runtime bahasa umum (CLR) seperti geometry, geography, dan hierarchyid sebagai objek Pythonbytes. Untuk informasi lebih lanjut, lihat Pemetaan tipe data dan Masalah yang diketahui.

Masalah yang diketahui

Periksa keterbatasan ini sebelum mengalihkan beban kerja dari msodbcsql18. Tabel berikut menandai pengecualian yang disengaja.

Issue Details Workaround
Autentikasi kata sandi Microsoft Entra ID (pengecualian sengaja) Authentication=ActiveDirectoryPassword tidak didukung, dan dukungan tidak direncanakan karena metode ini tidak dapat memenuhi persyaratan autentikasi multifaktor (MFA). Autentikasi SQL (UID / PWD) tidak terpengaruh. Gunakan metode Microsoft Entra ID lain, seperti service principal, managed identity, atau access token.
attrs_before Pengaturan Selector otentikasi numerik (SQL_COPT_SS_AUTHENTICATION) dan atribut application-intent tetap tidak didukung. Atribut failover multi-subnet dan integrated-security diimplementasikan. Pencocokan pengenal metadata (SQL_ATTR_METADATA_ID) juga tidak didukung. Gunakan kata kunci connection-string Authentication dan ApplicationIntent jika berlaku.
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.
Pelacakan asli di Linux Dengan pelacakan native diaktifkan, Python dapat terhenti mendadak saat pembersihan driver ketika proses keluar. Biarkan MSSQL_TDS_TRACE tidak disetel di Linux.
Penggunaan memori dengan binding parameter besar kustom Nilai data-at-execution yang diikat sebagai fixed-width SQL_CHAR, SQL_WCHAR, atau SQL_BINARY dibuffer untuk konversi. Mencampur parameter yang di-buffer dan yang di-stream juga dapat membuffer nilai besar sebelumnya sambil menunggu nilai berikutnya yang di-buffer. Pilih binding default dengan panjang variabel. Hindari override lebar tetap yang besar melalui setinputsizes() saat penggunaan memori penting.
Substitusi karakter non-Unicode Untuk karakter di luar halaman kode target parameter non-Unicode, driver dapat mengganti ? di mana msodbcsql18 menggunakan karakter yang paling sesuai. Pilih tipe SQL Unicode dan binding string Python default saat teks harus dipertahankan.
Perubahan isolasi setelah SQL mentah Setelah raw SET TRANSACTION ISOLATION LEVEL, pengaturan atribut koneksi ke level cache driver dapat berhasil tanpa memulihkan level tersebut di server. (#798) Hindari mencampur SQL mentah dan perubahan isolasi berbasis atribut. Gunakan SET TRANSACTION ISOLATION LEVEL yang eksplisit saat mengembalikan level.
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 Pembacaan bertahap dari data varchar(max) dan nvarchar(max) bisa lebih lambat dibandingkan dengan msodbcsql18. Hasil tergantung pada platform dan beban kerja. (#473) Bandingkan tolok ukur beban kerja Anda.

Daftar ini tidak lengkap.

Laporkan masalah

Jika Anda menemui bug, reproduksi bug tersebut dengan msodbcsql18 dan catat apakah bug tersebut terjadi pada kedua penyedia. Untuk petunjuk switching, lihat Aktifkan driver.

Sertakan output dari mssql_python.get_native_provider_info(), sistem operasi Anda, versi Python dan driver, serta batch T-SQL yang gagal dan pesan kesalahan dalam laporan Anda:

Di Windows, atur variabel-variabel ini di PowerShell sebelum memulai Python untuk mengumpulkan diagnostik driver native. Reproduksi masalah dengan mssql-odbc yang dipilih. Di Linux, biarkan MSSQL_TDS_TRACE tidak diatur karena kegagalan keluar proses yang dijelaskan di Masalah yang Diketahui.

$env:MSSQL_TDS_TRACE = "true"
$env:MSSQL_TDS_TRACE_LEVEL = "debug"
$env:MSSQL_TDS_TRACE_DIR = "./traces"
$env:MSSQL_TDS_TRACE_MAX_FILE_SIZE_MB = "100"

MSSQL_TDS_TRACE mengaktifkan pelacakan, MSSQL_TDS_TRACE_LEVEL memilih filter log, dan MSSQL_TDS_TRACE_DIR memilih direktori untuk file jejak per proses dari driver ODBC asli, bukan output kesalahan standar. MSSQL_TDS_TRACE_MAX_FILE_SIZE_MB mengatur ambang batas rollover per file (100 MiB secara default; menerima 1-1024). Ini bukan batas total ruang disk: file individual bisa melebihi ambang batas, dan file lama tidak akan dihapus. Paket pendamping Rust juga membuat file log di bawah mssql_python_logs di direktori saat ini. Restart Python setelah mengubah pengaturan ini.

Jejak dapat berisi teks T-SQL dan nilai parameter. Sunting data sensitif sebelum membagikan kutipan. Setelah diagnosis, hapus variabel-variabel ini dan restart Python untuk menonaktifkan pelacakan.