Az mssql-odbc illesztőprogram használata (Preview)

mssql-python betölti a két natív ODBC szolgáltató egyikét:

Provider Mi az? Status
msodbcsql18 Microsoft ODBC Driver 18 for SQL Server, a már ismert C++ illesztőprogram Alapértelmezett, változatlan
mssql-odbc Egy új, Rust nyelven írt ODBC illesztőprogram Előnézet, önkéntes részvétel

Ez a cikk a mssql-odbc-s verziót tárgyalja, amelyet jelenleg a(z) mssql-python használ, és miben tér el msodbcsql18-tól.

Note

mssql-odbc aktív fejlesztés és validálás alatt áll. Még nem teljesen helyettesíti a Microsoft ODBC Driver 18-at. Tartsd meg egyelőre a msodbcsql18-t éles alapértelmezettként. A fejlesztőcsapat azt tervezi, hogy a következő kiadásokban pótolja az előzetes verzió hiányosságait, kivéve a szándékos kizárásokat, amelyeket ebben a cikkben kifejezetten megjelöltek.

Availability

A meghajtó a mssql-python-rs csomagban előre lefordított wheel csomagokként érkezik CPython 3.10-hez és későbbi verziókhoz:

Platform Architectures
Windows x64; ARM64 CPython 3.11+-on
macOS Universal2 (x86_64 + arm64), macOS 15 vagy újabb verziók
Linux (glibc) x86_64, aarch64 — manylinux_2_28 és manylinux_2_34
Linux (musl) x86_64, aarch64 — musllinux_1_2

Az illesztőprogram engedélyezése

A mssql-python csomag a(z) mssql-python-rs csomagtól függ, így egy normál telepítés magával hozza a Rust drivert:

pip install mssql-python

Ha --no-deps használatával vagy privát indexből telepítesz, telepítsd kifejezetten a(z) mssql-python-rs csomagot is.

Válaszd ki a szolgáltatót az első csatlakozás előtt, akár környezeti változóval:

Powershell:

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

Bash vagy Zsh:

export MSSQL_PYTHON_NATIVE_PROVIDER=mssql-odbc

vagy Pythonból:

import mssql_python

mssql_python.native_provider = "mssql-odbc"

Csatlakozz az alkalmazásod meglévő kapcsolati karakterlánc-jével. Tartsd a tanúsítvány ellenőrzését engedélyezve (Encrypt=yes;TrustServerCertificate=no). Hitelesítésért és tanúsítványbeállításért lásd: Kapcsolati karakterláncok és Titkosítás és tanúsítványok.

connection = mssql_python.connect(connection_string)

Az illesztőprogram ezeket a szabályokat alkalmazza a szolgáltató kiválasztásakor:

  • A MSSQL_PYTHON_NATIVE_PROVIDER környezeti változó elsőbbséget élvez a native_provider. Egy ellentmondó attribútum-kiosztás RuntimeWarning eredményez.
  • A kiválasztás rögzítetté válik a kapcsolati sztring érvényesítése után, közvetlenül a natív kapcsolat megépítése előtt. Egy későbbi kapcsolati hiba nem törli a kijelölést. Egy korábbi kapcsolati karakterlánc elemzési hiba vagy hiányzó providercsomag nem oldja meg a kiválasztást. Miután a kijelölés rögzült, a native_provider másik szolgáltatóra módosítása kibocsátja a(z) RuntimeWarning eseményt, de nincs hatása. Indítsd újra a műveletet a szolgáltatóváltáshoz.
  • Egy ismeretlen szolgáltatónév hibát vált ki ValueError; az illesztőprogram nem tér vissza az alapértelmezett szolgáltatóhoz. A native_provider-hoz rendelt ismeretlen név azonnal kivételt vált ki. Ha a környezeti változóban ismeretlen név szerepel, az hibát okoz, amikor megpróbálsz csatlakozni.
  • Állítsd a(z) native_provider értékét None értékre, hogy töröld az attribútumválasztást, mielőtt az rögzítetté válna. A környezeti változó továbbra is elsőbbséget élvez.

Hívja meg a(z) mssql_python.get_native_provider_info() elemet a kiválasztott szolgáltató, a kiválasztási forrás és annak megvizsgálásához, hogy a kijelölés rögzített-e. A csatlakozás előtt ez a kijelölést jelzi, nem pedig bizonyítja, hogy a natív meghajtó sikeresen betöltődött.

A visszaállításhoz állítsd a változót msodbcsql18 értékre, vagy töröld a beállítását, és távolítsd el a kódból a native_provider hozzárendelést (vagy állítsd "msodbcsql18" értékre). Ezután indítsd újra a folyamatot.

Ami ma működik

A mssql-odbc meghajtó minden olyan ODBC funkciót megvalósít, amelyet mssql-python hív meg, így a legtöbb alkalmazás kódmódosítás nélkül is szolgáltatót válthat. Nézd meg az Ismert problémák között a többi különbséget.

Area Notes
Kapcsolati életciklus Kapcsolódás, close(), with blokkok, bejelentkezési időkorlát, diagnosztika és az aktuális adatbázis módosítása. A csatlakozási láncok beállításai közé tartozik ApplicationIntent, MultiSubnetFailover, IpAddressPreference, PacketSize, KeepAlive, és ConnectRetryCount / ConnectRetryInterval (tétlen csatlakozási reziliencia).
Authentication SQL-hitelesítés (UID / PWD); Windows-hitelesítés (Trusted_Connection=Yes, Windows rendszeren az SSPI, Linuxon és macOS-en a Kerberos használatával); valamint Microsoft Entra interaktív, eszközkód, szolgáltatásnév, menedzselt identitás, alapértelmezett hitelesítő adatok és hozzáférési token. Az Entra integrált hitelesítés és a jelszavas hitelesítés nem támogatott; lásd: Ismert problémák.
TLS Encrypt, TrustServerCertificate, HostnameInCertificate és ServerCertificate.
Lekérdezés végrehajtása Közvetlen és előkészített végrehajtás, előkészített terv újrafelhasználása, qmark paraméterek és az pyformat által végrehajtott mssql-python átalakítás.
ODBC escape szintaxisa Funkció, dátum/idő, külső összekapcsolás, GUID, LIKE ... {escape ...}, intervallum és {encrypt ...} escape formák.
Tárolt eljárások Hívd meg őket T-SQL-lel vagy pozicionális {call ...} szintaxissal a(z) execute() használatával, olvasd be az eredményhalmazokat, és lépj tovább a(z) nextset() használatával.
Bemeneti paraméterek Skaláris paraméterek, SQL NULL, setinputsizes(), és kevert normál/streamelt paraméterek.
Nagy paraméterek Nagy szöveg és bináris paraméterek a hagyományos kötési útvonalon áramlanak a szerverre; Az XML és UDT paraméterkorlátokat alább soroljuk fel.
executemany() ODBC paramétertömbökkel kötegelve. A streamelt értékeket tartalmazó sorok visszakerülnek soronkénti végrehajtásra.
Sorlekérés fetchone(), fetchmany(), fetchall(), iteráció, fetchval(), gépelt átalakítás és nagy szöveg/bináris streaming.
Arrow lekérése arrow_batch(), arrow(), és arrow_reader(). Szükséges pyarrow.
Több eredményhalmaz nextset(), beleértve a paramétertömbök által előállított eredményeket is.
Tranzakciók Autocommit, commit, rollback, az automatikus commit (vagy rollback, ha hiba történt), amely akkor történik, amikor egy with connect(...) blokk véget ér, valamint a read-uncommitted, read-committed, repeatable-read, serializable és snapshot izolációs szintek.
Lekérdezési időkorlát Állítsa be a(z) Connection.timeout értékét (másodpercben) az adott kapcsolat kurzorai által futtatott utasítások futási idejének korlátozásához; lejáratkor a rendszer a(z) OperationalError kivételt adja. 0 azt jelenti, hogy nincs időkorlát. Ez a beállítás különálló a bejelentkezési időtúllépéstől, amelyet connect(timeout=...) paraméterként adtak át.
Kapcsolatmegosztás A beépített mssql-python pool, beleértve a kapcsolat visszaállítását kivételezéskor, valamint külön poolokat a Microsoft Entra-identitás szerint.
Metaadat API-k tables(), columns(), primaryKeys(), foreignKeys(), statistics()rowIdColumns(), rowVerColumns(), procedures()és getTypeInfo().
Kódolás és átalakítók Alapértelmezett széles karakteres kódolás és kimeneti átalakítók. A testreszabott, szűk karakteres dekódolás és a nem Unicode paraméterátalakítás korlátai fel vannak sorolva a Known issues részben.

Adattípusok

Az összes SQL Server adattípust el tudod olvasni, és az illesztőprogram minden paramétertípust támogat, amelyet a mssql-python köt be. Az illesztőprogram a(z) xml, json és vector értékeket str formában adja vissza (vector JSON-tömbként), valamint a CLR-típusokat, például geometry, geography és hierarchyid típusokat bytes formában. Más Python leképezésekért lásd: Adattípus-leképezések. A típusspecifikus korlátozásokról lásd: Ismert problémák.

Ismert problémák

Ellenőrizd ezeket a különbségeket, mielőtt msodbcsql18 átváltanál egy munkaterhelést.

Issue Details Workaround
Microsoft Entra integrált hitelesítés Authentication=ActiveDirectoryIntegrated nem támogatott. A Windows-hitelesítést (Trusted_Connection=Yes) nem érinti. Használj egy másik Microsoft Entra módszert, vagy tartsd meg msodbcsql18.
Microsoft Entra jelszóhitelesítés Authentication=ActiveDirectoryPassword nem támogatott, és a támogatás sem tervezett, mert ez a módszer nem tudja kielégíteni az MFA-t. SQL hitelesítés (UID / PWD) nem érintett. Használj egy másik Microsoft Entra módszert, például szolgáltatásnevet, kezelt identitást vagy hozzáférési tokent.
attrs_before beállítások Az autentifikáció, alkalmazásszándék és többhálózati failover nem állíthatók be numerikus attribútumokként. A lekérdezési időkorláton kívüli utasításattribútumok elutasításra kerülnek. Használd az egyenértékű kapcsolati karakterlánc kulcsszavakat.
Kapcsolódási művelet időtúllépése set_attr(SQL_ATTR_CONNECTION_TIMEOUT, ...) elfogadja és tárolja az értéket, de nem érvényesít időkorlátot a 0.3.0-ban. A bejelentkezéshez Connection.timeout, a kivonatokhoz pedig connect(timeout=...) használható; egyik sem általános kapcsolatműveleti határidő.
Több címmel rendelkező gazdagépek msodbcsql18 alapértelmezés szerint engedélyezi a Transparent Network IP Resolution-ot (TNIR); mssql-odbc nem támogatja azt. mssql-python mindkét szolgáltatónál elutasítja a TransparentNetworkIPResolution kapcsolati karakterlánc kulcsszót. MultiSubnetFailover=Yes nélkül a címeket egyenként próbálják ki, így egy elérhetetlen cím késleltetheti a kapcsolatot. A szerver-segített DNS gyorsítótárazás és a továbbfejlesztett útválasztás nem kerül egyeztetésre. Állítsd be a(z) MultiSubnetFailover=Yes értéket a rendelkezésre állási csoport figyelői és más többcímes gazdagépek esetében.
Átmeneti DNS-hibák Ha egy DNS-lekérdezés sikertelen, az illesztőprogram nem áll vissza az utolsó sikeres címre. (#457) Próbálkozzon újra a kapcsolattal.
Adatbesorolás Az érzékenységi osztályozás metaadatai nem elérhetők, és SQL_COPT_SS_DATACLASSIFICATION_VERSION (1400) nem támogatott. Lekérdezés sys.sensitivity_classifications.
Többszálas A többszálas használatot még nem ellenőrizték. Tartsd meg a(z) msodbcsql18 beállítást a többszálas munkaterhelésekhez.
fork() Csatlakozás után Linux rendszeren egy folyamat, amelyet a szülő csatlakozása után forkoltak, lefagyhat, amikor az illesztőprogramot használja, még új kapcsolat esetén is. Ha a pooling engedélyezett, a szülőfolyamat is lefagyhat. (#566) Használd a spawn start módszert, és kapcsolódj az egyes workereken belül.
Egy futó utasítás törlése Egy futó lekérdezés vagy adatlekérés nem szakítható meg. Például egy arrow_reader() bezárása nem akadályozza meg a folyamatban lévő olvasást egy másik szálon. Használd a Connection.timeout elemet a hosszan futó utasítások korlátozására.
Olvasatlan eredmények Egy kurzor bezárása vagy egy másik utasítás futtatása a megmaradt eredményeket olvassa és eldobja azok megszakítása helyett, ami lassú lehet. Egy előre elkészített utasítást használó kurzor lezárása figyelmen kívül hagyja a Connection.timeout elemet, és lefagyhat, ha a kiszolgáló nem válaszol. (#546) Csak a szükséges sorokat hozd le, például ezzel TOP.
Large xml és UDT paraméterek A SQL_SS_XML vagy SQL_SS_UDT és setinputsizes() révén kötött értékek a streamelés helyett a memóriában lesznek pufferelve. Kösd meg az értékeket normál stringként.
Üres értékek image Egy üres, nem NULL SQL Server image érték jelenik None meg a b""helyett. Olvasd CAST(image_column AS varbinary(max)), vagy használd msodbcsql18 , ha az üres/NULL megkülönböztetés számít.
Nem Unicode sztringparaméterek A char / varchar és setinputsizes() közé kötött sztringek hibásan kódolhatók a 437-es és 850-es kódlap, valamint az UTF-8-rendezések esetén. Használd az alapértelmezett karakterlánc-kötést.
Régi kódlap-dekódolás Windows-on A(z) setdecoding(SQL_CHAR, encoding="cp1252") vagy egy másik régi kódlap használatával a szöveg hibásan dekódolható, vagy a rendszer bytes formában adhatja vissza, mert az illesztőprogram a char / varchar adatokat UTF-8-ként adja vissza. Használd az alapértelmezettet: conn.setdecoding(mssql_python.SQL_CHAR).
Connection.getinfo() SQL_USER_NAME a UID connection-stringet adja vissza, nem az adatbázis felhasználóját. Üres, amikor semmi sem éri el a sofőrt. Néhány képességérték és csomagméret-alapú korlát eltér a(z) msodbcsql18-tól. Használja a SELECT USER_NAME() elemet az adatbázis-felhasználóhoz.
Memóriahiány miatti hibák Néhány driverallokációs hiba megszakítja a Python-folyamatot ahelyett, hogy a(z) MemoryError kiváltása történne. (#484) Korlátozd az elküldött és lekért értékek méretét.
Nagy értékek olvasási teljesítménye Egy benchmarkban a varchar(max)nvarchar(max) / adatok darabos olvasása kissé lassabb volt, mint a msodbcsql18 használatával. (#473) Hasonlítsd össze a munkaterhelésedet.

Ez a lista nem teljes.

Jelentéskészítési problémák

Ha hibával találkozol, válaszd msodbcsql18, indítsd újra a folyamatot, és nézd meg, hogy a viselkedés még mindig előfordul-e. Távolítsd el az ellentmondásos Python oldali szolgáltató-hozzárendelést. Az összehasonlítás segít elszigetelni a problémát; önmagában nem bizonyítja az okát. Foglald bele mssql_python.get_native_provider_info() kimenetét, a platformodat, valamint a hibás SQL-t vagy a hibaüzenetet:

A Rust-driver diagnosztikájához állítsa be ezeket a változókat a Python indítása előtt, és ismételje meg a problémát a mssql-odbc lehetőséget kiválasztva. Például a PowerShellben:

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

MSSQL_TDS_TRACE Lehetővé teszi a követést, MSSQL_TDS_TRACE_LEVEL kiválasztja a naplószűrőt, és MSSQL_TDS_TRACE_DIR folyamatonként ír fájlokat STDERR helyett. Indítsd újra a Python-t, miután megváltoztatod ezeket a beállításokat. A nyomok tartalmazhatnak SQL szöveget és paraméterértékeket. Vizsgálja át és szerkessze ki az érzékeny adatokat, mielőtt megosztja a releváns részleteket, és a diagnózis után kapcsolja ki a nyomkövetést.

Kapcsolódó tartalom

  • Utolsó frissítés időpontja: