Použijte ovladač mssql-odbc (Náhled)

mssql-python načítá jeden ze dvou nativních ODBC poskytovatelů:

Provider Description Status
msodbcsql18 Ovladač Microsoft ODBC 18 pro SQL Server Výchozí
mssql-odbc Ovladač ODBC založený na Rustu Náhled, opt-in

Balíček mssql-python-rs0.4.0 zahrnuje mssql-odbc provider.

Note

Použijte msodbcsql18 pro produkční pracovní zátěže. Než se přihlásíte k poskytovateli verze Preview mssql-odbc, projděte si jeho známé problémy.

Availability

Ovladač je uvnitř balíčku mssql-python-rs dodáván jako předem sestavené wheel balíčky pro CPython 3.10 a novější verze:

Platform Architektury
Windows x64; ARM64 na CPython 3.11 a novějších verzích
macOS universal2 (x86_64 a arm64), verze macOS 15 a novější
Linux (glibc) x86_64 a aarch64 (manylinux_2_28 a manylinux_2_34)
Linux (musl) x86_64 a aarch64 (musllinux_1_2)

Povolte ovladač

Při instalaci mssql-python se také nainstaluje mssql-python-rs, který obsahuje ovladač mssql-odbc:

python -m pip install mssql-python

Pokud instalujete s --no-deps nebo z privátního indexu, instalujte mssql-python-rs také explicitně.

Vyberte poskytovatele před otevřením prvního připojení. Použijte jednu z následujících metod.

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

Nastavte proměnnou MSSQL_CONNECTION_STRING prostředí na připojovací řetězec vaší aplikace. Nechte validaci certifikátů zapnutou (Encrypt=yes;TrustServerCertificate=no). Pro více informací viz Připojovací řetězce a Šifrování a certifikáty.

Použijte tento příklad s vaším vybraným poskytovatelem:

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

Příklad uvádí 1.

Výběr poskytovatele se řídí těmito pravidly:

  • MSSQL_PYTHON_NATIVE_PROVIDER má přednost před native_provider. Nastavení atributu na poskytovatele v konfliktu vygeneruje RuntimeWarning.
  • Před načtením ovladače nastavte native_provider na None, aby se vymazalo nastavení Pythonu. To však proměnnou prostředí nevymaže.
  • Neznámé jméno poskytovatele způsobí chybu ValueError. Přiřazení neplatného jména native_provider okamžitě vyvolá chybu; neplatná proměnná prostředí vyvolá chybu při připojení. Ovladač se nevrací k výchozímu zprostředkovateli.
  • Poskytovatel je fixován, když ovladač zahájí nativní pokus o připojení, i když tento pokus selže. Restartujte Python, chcete-li přepnout poskytovatele. Přechod native_provider k jinému poskytovateli vyvolá RuntimeWarning a nemá žádný efekt.

Chyby při ověřování spojovacích řetězců a chybějící balíčky poskytovatelů se vyskytují před tímto bodem. Tyto chyby můžete opravit a vybrat jiného poskytovatele, aniž byste museli restartovat.

Zavolejte mssql_python.get_native_provider_info() a zkontrolujte jméno poskytovatele, jak byl vybrán a zda je výběr pevně daný.

Pro návrat do msodbcsql18 odstraňte MSSQL_PYTHON_NATIVE_PROVIDER a veškerá přiřazení native_provider z aplikace a pak restartujte Python.

Výchozí nastavení pro failover více podsítí

Poskytovatel Rust ve výchozím nastavení povoluje MultiSubnetFailover pro příslušná připojení Transmission Control Protocol (TCP). Výslovně nastavte MultiSubnetFailover=no, aby se vyžádaly postupné pokusy o připojení. Pro změnu výchozího nastavení pro celé nasazení nastavte MSSQL_RS_MULTISUBNET_FAILOVER_DEFAULT na true nebo false před prvním použitím nativního ovladače. Klíčové slovo řetězce připojení přepíše toto výchozí nastavení.

Číselný atribut SQL_COPT_SS_MULTISUBNET_FAILOVER (1248) také přepisuje klíč, když je nastaven před připojením.

Ovladač tuto výchozí možnost neumožňuje pro transporty jiné než TCP, zrcadlení databáze, pojmenované instance vyžadující objevování SQL Server Browser nebo místní připojení systému Windows, u nichž není uveden explicitní protokol a adresa. Explicitní povolení MultiSubnetFailover pro ne-TCP transport, zrcadlení databáze nebo zjišťování přes SQL Server Browser vyvolává chybu připojení. Pro více informací viz Vysoká dostupnost a převzetí služeb při selhání.

Podporované funkce

Podporovány jsou následující funkce, s ohledem na známé problémy.

Area Notes
Životní cyklus spojení Připojení, close(), with bloky, časový limit přihlášení, diagnostika a změna aktuální databáze. Nastavení spojovacího řetězce zahrnují ConnectRetryCount, ConnectRetryInterval, / , KeepAlive, PacketSize a IpAddressPreferenceMultiSubnetFailoverApplicationIntent (odolnost neaktivního připojení). Nativní ovladač také vyjednává serverem podporované cache systému doménových jmen (DNS) a rozšířené směrování, pokud je server podporuje.
Authentication autentizace SQL (UID / PWD); ověřování systému Windows (Trusted_Connection=Yes, využívající Security Support Provider Interface (SSPI) v systému Windows nebo Kerberos v Linuxu a macOS); a Microsoft Entra ID interaktivní, integrované, kód zařízení pro ověření, instanční objekt služby, spravovaná identita, výchozí přihlašovací údaje a přístupový token. Autentizace heslem Microsoft Entra ID není podporována. Další informace najdete v tématu Známé problémy.
Protokol TLS (Transport Layer Security) Encrypt, TrustServerCertificate, HostnameInCertificate a ServerCertificate.
Provedení dotazu Přímé a připravené spuštění, opakované použití připraveného plánu, parametry qmark a konverze, kterou provádí mssql-pythonpyformat.
Úniková syntaxe ODBC Funkce, datum/čas, OUTER JOIN, globálně jedinečný identifikátor (GUID), LIKE ... {escape ...}, interval a únikové formy {encrypt ...}.
Uložené procedury Volejte je pomocí Transact-SQL (T-SQL) nebo poziční {call ...} syntaxe přes execute(), čtěte sady výsledků a přejděte pomocí nextset().
Vstupní parametry Skalární parametry, SQL NULL, setinputsizes(), a smíšené regulární/streamované parametry.
Rozsáhlé parametry Rozsáhlé textové, binární, rozšiřitelný značkovací jazyk (XML) a uživatelsky definované typy (UDT) podporují streamování dat za běhu.
executemany() Dávkováno pomocí polí parametrů ODBC. Řádky obsahující streamované hodnoty se přepnou na provádění řádek po řádku.
Načítání po řádcích fetchone(), fetchmany(), fetchall(), iterace, fetchval(), převod typu a streamování velkého textu/binárních dat.
Načítání šípů arrow_batch(), arrow() a arrow_reader(). Vyžaduje pyarrow.
Více výsledkových sad nextset(), včetně výsledků získaných poli parametrů.
Transakce Autocommit, commit, rollback a úrovně izolace read-uncommitted, read-committed, repeatable-read, serializable a snapshot isolation. Když je automatické potvrzování vypnuté, správce kontextu spojení potvrdí při úspěšném ukončení a provede rollback při výjimce.
Časový limit dotazu vypršel Nastavte Connection.timeout v sekundách před vytvořením kurzoru. Když příkaz překročí tento časový limit, ovladač vyvolá OperationalError. 0 znamená, že není nastaven žádný časový limit. Nastavte časový limit přihlášení zvlášť pomocí connect(timeout=...).
Sdílení připojení Vestavěný pool zahrnuje resetování připojení před opětovným použitím, včetně mssql-python. Pro izolaci specifickou pro ověřování ve fondu viz Izolace identity.
Rozhraní API metadat tables(), columns(), primaryKeys(), foreignKeys(), statistics(), rowIdColumns(), rowVerColumns(), procedures(), a getTypeInfo().
Kódování a převodníky Výchozí kódování širokých znaků, výstupní převodníky a parametry bez Unicode zohledňující kolaci, včetně kolací UTF-8 a starších kolací SQL sort-ID. Vlastní úzkoznakové dekódování musí odpovídat kódové stránce klienta. Další informace najdete v tématu Známé problémy.

Integrovaná autentizace Microsoft Entra ID využívá ve Windows aktuálně přihlášený účet Windows. V Linuxu a macOS používá lístek Kerberos k ověření ke koncovému bodu služby Služby Active Directory Federation (AD FS) klienta. Předpoklady najdete v tématu Integrované ověřování systému Windows.

Zavření arrow_reader() odešle SQLCancel, aby přerušilo probíhající načítání. Volání close čeká na dokončení úklidu po zrušení. Pro více informací viz integrace Apache Arrow.

Datové typy

Ovladač vrací hodnoty xml, json a vektor jako objekty Pythonu str, přičemž vektor je reprezentován jako pole JavaScript Object Notation (JSON). Vrací typy modulu Common Language Runtime (CLR), jako jsou geometrie, geografie a hierarchyid, jako objekty Python bytes. Pro více informací viz Mapování datových typů a Známé problémy.

Známé problémy

Zkontrolujte tyto rozdíly před přepnutím pracovní zátěže z msodbcsql18.

Issue Details Workaround
Autentizace hesla Microsoft Entra ID Authentication=ActiveDirectoryPassword není podporováno. Tato metoda nesplňuje multifaktorovou autentizaci (MFA). SQL autentizace (UID / PWD) není ovlivněna. Použijte jinou metodu Microsoft Entra ID, například instanční objekt služby, spravovanou identitu nebo přístupový token.
attrs_before nastavení Režim autentizace Microsoft Entra ID a záměr aplikace nelze nastavit jako číselné atributy připojení. Použijte klíčová slova připojovacího řetězce Authentication a ApplicationIntent.
Časový limit operace připojení SQL_ATTR_CONNECTION_TIMEOUT řídí úklid při zrušení. Nevynucuje to časový limit při resetu pooled připojení. Požadavek na spojení může zůstat blokován, pokud server přestane během resetu reagovat. Není k dispozici žádný časový limit pooled-reset. Nastavte connect(timeout=...) pro přihlášení a Connection.timeout pro výpisy.
Víceadresní hostitelé msodbcsql18 ve výchozím nastavení umožňuje transparentní síťové IP rozlišení (TNIR); mssql-odbc nepodporuje ji. mssql-python odmítá TransparentNetworkIPResolution klíčové slovo spojovacího řetězce u kteréhokoli poskytovatele. Použijte MultiSubnetFailover=yes pro naslouchací procesy skupiny dostupnosti a další hostitele s více adresami. Pro výchozí nastavení viz výchozí nastavení převzetí služeb při selhání pro více podsítí.
Klasifikace dat Metadata klasifikace citlivosti nejsou k dispozici a SQL_COPT_SS_DATACLASSIFICATION_VERSION (1400) není podporováno. Dotaz sys.sensitivity_classifications.
fork() po připojení V Linuxu se může proces vytvořený funkcí fork poté, co se nadřazený proces připojí, při použití ovladače zaseknout, i při novém připojení. Je-li pooling povolen, nadřazený proces se může také zaseknout. (#566) Použijte startovací metodu spawn a připojte se uvnitř každého pracovního procesu.
Nativní trasování na Linuxu S aktivovaným nativním trasováním může Python během čištění ovladače při ukončení procesu selhat. Nechte MSSQL_TDS_TRACE v systému Linux nenastavené.
Nepřečtené výsledky Zavření kurzoru nebo spuštění jiného příkazu přečte a zahodí zbývající výsledky namísto jejich stornování, což může být pomalé. Čištění připravených příkazů využívá časový limit dotazu příkazu, ale nulový časový limit nechává toto čištění neomezené. Načítej pouze ty řádky, které potřebuješ, například s TOP, a nastav Connection.timeout před vytvořením kurzoru.
Vlastní úzkoznakové dekódování Nativní ovladač používá ve Windows kódovou stránku Windows ANSI a v Linuxu a macOS kódovou stránku národního prostředí procesu pro text v úzkém formátu. Explicitní dekódování v Python, které neodpovídá dané kódové stránce, může vytvořit nesprávný text nebo bytes. Použijte výchozí dekódování širokých znaků: conn.setdecoding(mssql_python.SQL_CHAR).
Connection.getinfo() Některé hodnoty možností a limity založené na velikosti paketů se liší od msodbcsql18. SQL_USER_NAME hlásí objekt zabezpečení databáze místo připojovacího řetězce UID. Dotazujte se na konkrétní metadata serveru, když je pro vaši aplikaci důležitá nahlášená schopnost nebo omezení.
Selhání při nedostatku paměti Některá selhání při alokaci ovladačů ukončí proces Python místo vyvolání MemoryError. (#484) Omezte velikost hodnot, které posíláte a načítáte.
Výkon čtení velkých hodnot Fragmentovaná čtení dat varchar(max) a nvarchar(max) mohou být pomalejší než čtení pomocí msodbcsql18. (#473) Porovnejte svou pracovní zátěž.

Nahlásit problémy

Pokud narazíte na chybu, reprodukujte ji msodbcsql18 a zaznamenejte, zda se vyskytuje u obou poskytovatelů. Pokyny k přepnutí najdete v části Povolit ovladač.

Zahrňte do své zprávy výstup mssql_python.get_native_provider_info(), verze vašeho operačního systému, Pythonu a ovladače a selhávající dávku T-SQL a chybovou zprávu:

Ve Windows nastavte tyto proměnné v PowerShellu před spuštěním Pythonu, aby se shromažďovala diagnostika nativních ovladačů. Reprodukujte problém, když je vybráno mssql-odbc:

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

MSSQL_TDS_TRACE umožňuje trasování, MSSQL_TDS_TRACE_LEVEL vybírá úroveň protokolování a MSSQL_TDS_TRACE_DIR vybírá adresář pro trasovací soubory pro jednotlivé procesy z nativního ovladače ODBC místo standardního chybového výstupu. Doprovodný balíček Rust také vytváří logovací soubory pod mssql_python_logs v aktuálním adresáři.

Traces mohou obsahovat T-SQL text a hodnoty parametrů. Před sdílením úryvků začerňte citlivé údaje. Po diagnostice tyto proměnné odstraňte a restartujte Python, abyste deaktivovali trasování.

Související obsah

  • Poslední aktualizace v