mssql-odbc sürücüsünü kullanın (Önizleme)

mssql-python iki yerel ODBC sağlayıcısından birini yükler:

Provider Description Durum
msodbcsql18 SQL Server için Microsoft ODBC Sürücüsü 18 Varsayılan
mssql-odbc Rust tabanlı ODBC sürücüsü Önizleme, katılım

mssql-python-rs paketi mssql-odbc sağlayıcıyı içerir.

Note

Üretim iş yükleri için msodbcsql18 kullanın. Önizleme mssql-odbc sağlayıcısını etkinleştirmeden önce, bilinen sorunlarını gözden geçirin.

Availability

Sürücü, mssql-python-rs paketinin içinde CPython 3.10 ve sonraki sürümler için önceden oluşturulmuş wheel paketleri olarak dağıtılır:

Platform Architectures
Windows CPython 3.11 ve sonraki sürümlerde x64; ARM64
macOS Universal2 (x86_64 ve arm64), macOS 15 ve daha sonraki sürümler
Linux (glibc) x86_64 ve aarch64 (manylinux_2_28 ve manylinux_2_34)
Linux (musl) x86_64 ve aarch64 (musllinux_1_2)

Sürücüyü etkinleştirme

mssql-python kurulumu, mssql-python-rs sürücüsünü içeren mssql-odbc öğesini de yükler:

python -m pip install mssql-python

Eğer --no-deps ile veya özel bir indeksten kurarsanız, mssql-python-rs öğesini de ayrıca açıkça kurun.

İlk bağlantıyı açmadan önce sağlayıcıyı seçin. Aşağıdaki yöntemlerden birini kullanın.

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

Ortam değişkenini MSSQL_CONNECTION_STRING uygulamanızın bağlantı dizesi olarak ayarlayın. Sertifika doğrulamasını etkin tutun (Encrypt=yes;TrustServerCertificate=no). Daha fazla bilgi için Bağlantı dizileri ve Şifreleme ile sertifikalar bölümlerine bakınız.

Bu örneği seçtiğiniz sağlayıcıyla çalıştırın:

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])

Örnek 1 yazdırır.

Sağlayıcı seçimi şu kurallara uyar:

  • MSSQL_PYTHON_NATIVE_PROVIDER ' den önceliklidir native_provider. Özniteliği çakışan bir sağlayıcıya ayarlamak, RuntimeWarning yayılmasına neden olur.
  • Sürücü yüklenmeden önce, Python ayarını temizlemek için native_provider öğesini None olarak ayarlayın. Bu ortam değişkenini temizlemez.
  • Tanınmayan bir sağlayıcı adı ValueError oluşturur. native_provider öğesine geçersiz bir ad atamak hemen hata verir; geçersiz bir ortam değişkeni ise bağlandığınızda hata verir. Sürücü varsayılan sağlayıcıya geri dönmez.
  • Sürücü yerel bağlantı girişimi başlattığında, bu deneme başarısız olsa bile, sağlayıcı belirlenir. Sağlayıcıyı değiştirmek için Python'u yeniden başlatın. native_provider öğesini başka bir sağlayıcıyla değiştirmek, RuntimeWarning tetikler ve hiçbir etkisi olmaz.

Bağlantı dizisi doğrulama hataları ve eksik sağlayıcı paketleri bu noktadan önce ortaya çıkar. Bu hataları düzeltebilir ve yeniden başlatmadan başka bir sağlayıcı seçebilirsiniz.

Sağlayıcı adını, nasıl seçildiğini ve seçimin sabit olup olmadığını kontrol etmek için arayın mssql_python.get_native_provider_info() .

msodbcsql18 konumuna geri dönmek için, uygulamanızdan MSSQL_PYTHON_NATIVE_PROVIDER ve herhangi bir native_provider atamasını kaldırın, ardından Python'u yeniden başlatın.

Çoklu alt ağ yük devretme varsayılanları

Rust sağlayıcısı, geçerli İletim Kontrol Protokolü (TCP) bağlantıları için MultiSubnetFailover özelliğini varsayılan olarak etkinleştirir. Ardışık bağlantı denemeleri istemek için MultiSubnetFailover=no öğesini açıkça ayarlayın. Dağıtım genelindeki varsayılanı değiştirmek için, yerel sürücü ilk kez kullanılmadan önce MSSQL_RS_MULTISUBNET_FAILOVER_DEFAULT değerini true veya false olarak ayarlayın. Bağlantı dizisi anahtar kelimesi bu varsayılanı geçersiz kılmaktadır.

Sayısal SQL_COPT_SS_MULTISUBNET_FAILOVER öznitelik (1248) de bağlanmadan önce ayarlandığında anahtar kelimeyi geçersiz kılar.

Sürücü, TCP dışı taşımalar, veritabanı aynalama, SQL Server Browser keşfi gerektiren adlandırılmış örnekler veya açık bir protokol ve adresi atlayan yerel Windows bağlantıları için bu varsayılan özelliği etkinleştirmez. TCP dışı bir taşıma, veritabanı yansıtma veya SQL Server Tarayıcı keşfi için MultiSubnetFailover öğesini açıkça etkinleştirmek bağlantı hatasına neden olur. Daha fazla bilgi için Yüksek erişilebilirlik ve yük devretme bölümüne bakınız.

Desteklenen özellikler

Aşağıdaki özellikler, bilinen sorunlara tabi olarak desteklenmektedir.

Alan Notlar
Bağlantı yaşam döngüsü Bağlantı, close(), with bloklar, oturum açma zaman aşımı, tanılama ve mevcut veritabanını değiştirme. Bağlantı dizesi ayarları KeepAlive, / , ConnectRetryInterval, ConnectRetryCount, ApplicationIntent ve PacketSizeIpAddressPreferenceMultiSubnetFailover'yi (boşta bağlantı dayanıklılığı) içerir. Yerel sürücü ayrıca, sunucu bunları desteklediğinde, sunucu destekli Alan Adı Sistemi (DNS) önbelleğe alma ve gelişmiş yönlendirme üzerinde anlaşır.
Authentication SQL kimlik doğrulama (UID / PWD); Windows kimlik doğrulaması (Trusted_Connection=Yes, Windows'ta Güvenlik Destek Sağlayıcı Arayüzü (SSPI) veya Linux ve macOS'ta Kerberos kullanılarak); ve Microsoft Entra ID etkileşimli, entegre, cihaz kodu, hizmet sorumlusu, yönetilen kimlik, varsayılan kimlik bilgileri ve erişim tokenı. Microsoft Entra ID şifre doğrulaması desteklenmiyor. Daha fazla bilgi için bkz. Bilinen sorunlar.
Aktarım Katmanı Güvenliği (TLS) Encrypt, , TrustServerCertificate, HostnameInCertificate ve ServerCertificate.
Sorgu çalıştırma Doğrudan ve hazırlanmış yürütme, hazırlanmış planın yeniden kullanımı, qmark parametreler ve pyformat gerçekleştirdiği dönüşüm mssql-python.
ODBC kaçış sözdizimi Fonksiyon, tarih/saat, dış birleştirme, genel olarak benzersiz tanımlayıcı (GUID), LIKE ... {escape ...}, aralık ve {encrypt ...} kaçış formları.
Saklanan prosedürler Onları Transact-SQL (T-SQL) veya konumsal {call ...} sözdizimi ile execute() aracılığıyla çağırın, sonuç kümelerini okuyun ve nextset() ile ilerleyin.
Giriş parametreleri Skaler parametreler, SQL NULL, setinputsizes(), ve karışık normal/akışlı parametreler.
Büyük parametreler Büyük metin, ikili, Genişletilebilir İşaretleme Dili (XML) ve kullanıcı tanımlı tür (UDT) parametreleri, yürütme sırasında veri akışını destekler.
executemany() ODBC parametre dizileriyle toplu işlendi. Akışlı değerleri içeren satırlar satır satır yürütmeye geri döner.
Satır getirme fetchone(), fetchmany(), fetchall(), yineleme, fetchval(), tür dönüştürme ve büyük metin/ikili akış işleme.
Ok alma arrow_batch(), arrow() ve arrow_reader(). gerektirir pyarrow.
Birden fazla sonuç kümesi nextset(); parametre dizileri tarafından üretilen sonuçlar dahil.
Transactions Autocommit, commit, rollback ve read-uncommitted, read-committed, repeatable-read, serileştirilebilir ve snapshot izolasyon seviyeleri. Otomatik commit kapalıyken bağlantı bağlam yöneticisi başarılı çıkışta commit yapar ve istisna durumunda geri alır.
Sorgu zaman aşımı İmleç oluşturmadan önce Connection.timeout değerini saniye cinsinden ayarlayın. Bir ifade bu zaman aşımını aşarsa, sürücü OperationalError fırlatır. 0, zaman aşımı olmadığı anlamına gelir. Oturum açma zaman aşımını connect(timeout=...) ile ayrı olarak ayarlayın.
Bağlantı havuzlama Yerleşik mssql-python havuzu, yeniden kullanımdan önce bağlantı sıfırlamayı içerir. Kimlik doğrulamaya özgü havuz izolasyonu için bkz. Kimlik izolasyonu.
Meta veri API'leri tables(), columns(), primaryKeys(), foreignKeys(), statistics(), rowIdColumns(), rowVerColumns(), procedures() ve getTypeInfo().
Kodlama ve dönüştürücüler Varsayılan geniş karakter kodlaması, çıktı dönüştürücüler ve UTF-8 ile eski SQL sort-ID karşılaştırma düzenleri dahil olmak üzere karşılaştırma düzenine duyarlı Unicode olmayan parametreler. Özel dar karakterli kod çözümleme, istemcinin kod sayfasıyla eşleşmelidir. Daha fazla bilgi için bkz. Bilinen sorunlar.

Microsoft Entra ID entegre kimlik doğrulaması, Windows'ta oturum açılmış Windows hesabını kullanır. Linux ve macOS'ta, kiracının Active Directory Federasyon Hizmetleri (AD FS) (AD FS) uç noktasında kimlik doğrulamak için Kerberos bileti kullanır. Ön koşullar için bkz. Windows Entegre kimlik doğrulaması.

arrow_reader() öğesini kapatmak, devam eden bir getirme işlemini kesintiye uğratmak için SQLCancel gönderir. Yakın çağrı, iptal temizliğinin bitmesini bekliyor. Daha fazla bilgi için Apache Arrow entegrasyonuna bakınız.

Veri türleri

Sürücü, xml, json ve vektör değerlerini Python str nesneleri olarak döndürür; vektör ise JavaScript Nesne Gösterimi (JSON) dizisi olarak temsil edilir. geometry, geography ve hierarchyid gibi yaygın dil çalışma zamanı (CLR) türlerini Python bytes nesneleri olarak döndürür. Daha fazla bilgi için Veri tipi eşlemeleri ve Bilinen sorunlar bölümlerine bakınız.

Bilinen sorunlar

msodbcsql18 konumundan bir iş yükünü değiştirmeden önce bu farkları kontrol edin.

Issue Details Workaround
Microsoft Entra ID şifre doğrulaması Authentication=ActiveDirectoryPassword desteklenmez. Bu yöntem çok faktörlü kimlik doğrulama (MFA) gereksinimini karşılamaz. SQL kimlik doğrulaması (UID / PWD) etkilenmeden kalır. Hizmet sorumlusu, yönetilen kimlik veya erişim tokenı gibi başka bir Microsoft Entra ID yöntemi kullanın.
attrs_before ayarları Microsoft Entra ID kimlik doğrulama modu ve uygulama amacı sayısal bağlantı özellikleri olarak ayarlanamaz. ApplicationIntent ve Authentication bağlantı dizesi anahtar sözcüklerini kullanın.
Bağlantı işlemi zaman aşımı SQL_ATTR_CONNECTION_TIMEOUT iptal temizliğini denetler. Havuzlu bağlantı sıfırlamasında zaman aşımını zorunlu kılmaz. Sunucu sıfırlama sırasında yanıt vermeyi durdurursa bağlantı talebi engellenmiş olarak kalabilir. Birleştirilmiş sıfırlama zaman aşımı mevcut değil. Giriş için Connection.timeout ve ekstreler için connect(timeout=...) ayarlayın.
Çok adresli hostlar msodbcsql18 Varsayılan olarak Şeffaf Ağ IP Çözümlemesini (TNIR) etkinleştiriyor; mssql-odbc bunu desteklemiyor. mssql-python her iki sağlayıcıda da TransparentNetworkIPResolution bağlantı dizisi anahtar kelimesini reddeder. Kullanılabilirlik grubu dinleyicileri ve diğer çok adresli ana bilgisayarlar için MultiSubnetFailover=yes kullanın. Varsayılan ayarlar için bkz. Multi-subnet failover defaults.
Veri sınıflandırma Duyarlılık sınıflandırma meta verileri mevcut değildir ve SQL_COPT_SS_DATACLASSIFICATION_VERSION (1400) desteklenmez. Sorgu sys.sensitivity_classifications.
fork() Bağlandıktan sonra Linux'ta, ebeveyn işlem bağlantı kurduktan sonra çatallanan bir süreç, sürücüyü kullandığında yeni bir bağlantıyla bile takılabilir. Havuzlama etkinleştirildiğinde, üst süreç de takılabilir. (#566) spawn başlatma yöntemini kullanın ve her çalışanın içinde bağlantı kurun.
Linux'ta yerel izleme Yerel izleme etkinleştirildiğinde, Python süreç çıkışında sürücü temizleme sırasında sonlanabilir. Linux'ta MSSQL_TDS_TRACE ayarlamayın.
Okunmamış sonuçlar Bir imleci kapatmak veya başka bir komutu çalıştırmak, kalan sonuçları iptal etmek yerine okuyor ve atıyor, bu da yavaş olabilir. Prepared-statement temizliği, ifadenin sorgu zaman aşımını kullanır, ancak sıfır zaman aşımı bu temizlemeyi sınırsız bırakır. Sadece ihtiyacınız olan satırları getirin, örneğin TOP ile, ve imleci oluşturmadan önce Connection.timeout ayarlayın.
Özel dar karakter kod çözme Yerel sürücü, dar metin için Windows'ta Windows ANSI kod sayfasını ve Linux ile macOS'ta işlem yerel ayarının kod sayfasını kullanır. O kod sayfasıyla eşleşmeyen açık bir Python kod çözme işlemi yanlış metin veya bytes üretebilir. Varsayılan geniş karakter çözme yöntemini kullanın: conn.setdecoding(mssql_python.SQL_CHAR).
Connection.getinfo() Bazı yetenek değerleri ve paket boyutuna dayalı sınırlar msodbcsql18 öğesinden farklıdır. SQL_USER_NAME bağlantı dizisi UID yerine veritabanı sorumlusunu bildirir. Rapor edilen bir yetenek veya sınırlama uygulamanız için önemli olduğunda, belirli sunucu meta verilerini sorgulayın.
Bellek yetersizliği hataları Bazı sürücü tahsisi hataları, MemoryError oluşturmak yerine Python sürecini sona erdirir. (#484) Gönderdiğiniz ve çektiğiniz değerlerin boyutunu sınırlayın.
Büyük değer okuma performansı varchar(max) ve nvarchar(max) verilerinin parçalı okunması, msodbcsql18 ile olandan daha yavaş olabilir. (#473) İş yükünüzü kıyaslayın.

Sorunları bildir

Bir hatayla karşılaşırsanız, msodbcsql18 ile yeniden oluşturun ve bunun her iki sağlayıcıda da gerçekleşip gerçekleşmediğini kaydedin. Anahtarlama talimatları için bkz. Sürücüyü etkinleştir.

Raporunuza mssql_python.get_native_provider_info() çıktısını, işletim sisteminizi, Python ve sürücü sürümlerinizi, başarısız olan T-SQL toplu işini ve hata mesajını ekleyin:

Windows'ta, Python'u başlatmadan önce PowerShell'de bu değişkenleri ayarlayarak yerel sürücü tanılamasını toplayın. mssql-odbc seçiliyken sorunu yeniden oluşturun:

$env:MSSQL_TDS_TRACE = "true"
$env:MSSQL_TDS_TRACE_LEVEL = "debug"
$env:MSSQL_TDS_TRACE_DIR = ".\traces"

MSSQL_TDS_TRACE takip etmeyi etkinleştirir, MSSQL_TDS_TRACE_LEVEL log seviyesini seçer ve MSSQL_TDS_TRACE_DIR standart hata çıkışı yerine yerel ODBC sürücüsünden işlem başına iz dosyaları için dizini seçer. Rust eşlik paketi ayrıca geçerli dizinde mssql_python_logs altında log dosyaları oluşturur.

İzlemeler, T-SQL metni ve parametre değerlerini içerebilir. Alıntıları paylaşmadan önce hassas verileri gizleyin. Tanılamadan sonra bu değişkenleri kaldırın ve Python'u yeniden başlatarak izlemeyi devre dışı bırakın.

İlgili içerik

  • Son güncelleştirme: