Használd a mssql-odbc illesztőprogramot (Előzetes verzió)

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

Provider Description Status
msodbcsql18 Microsoft ODBC Driver 18 for SQL Server Alapértelmezett
mssql-odbc Rust-alapú ODBC-illesztőprogram Előnézet, részvétel

A mssql-python-rs0.4.0 csomag tartalmazza a mssql-odbc provider-t.

Note

Használja a(z) msodbcsql18 elemet éles üzemi számítási feladatokhoz. Mielőtt feliratkozol az előnézeti mssql-odbc szolgáltatóra, nézd át az ismert problémáit.

Availability

Az illesztőprogram a mssql-python-rs csomagban előre elkészített wheelként érkezik CPython 3.10-hez és újabb verziókhoz:

Platform Architectures
Windows x64; ARM64 a CPython 3.11-en és későbbi verziókon
macOS Universal2 (x86_64 és arm64), macOS 15 és újabb verziók
Linux (glibc) x86_64 és aarch64 (manylinux_2_28 és manylinux_2_34)
Linux (musl) x86_64 és aarch64 (musllinux_1_2)

Az illesztőprogram engedélyezése

A mssql-python telepítése a mssql-python-rs összetevőt is telepíti, amely tartalmazza a mssql-odbc illesztőprogramot:

python -m 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óprogramot, mielőtt megnyitod az első kapcsolatot. Használja az alábbi módszerek egyikét.

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

Állítsd be a MSSQL_CONNECTION_STRING környezeti változót az alkalmazásod kapcsolati karakterláncára. Tartsd a tanúsítvány ellenőrzését engedélyezve (Encrypt=yes;TrustServerCertificate=no). További információért lásd: kapcsolati karakterláncok és Titkosítás és tanúsítványok.

Futtatja le ezt a példát a kiválasztott szolgáltatóval:

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

A példa kiírja 1.

A szolgáltató kiválasztása az alábbi szabályokat követi:

  • MSSQL_PYTHON_NATIVE_PROVIDER elsőbbséget élvez a native_provider. Az attribútumot ellentmondó szolgáltatóhoz állítva RuntimeWarning vált ki.
  • Mielőtt a driver betöltődik, állítsd native_providerNone értékre a Python beállítás törléséhez. Ez nem törli a környezeti változót.
  • Egy ismeretlen szolgáltatónév ValueError vált ki. Ha érvénytelen nevet rendelsz hozzá a native_provider elemhez, az azonnal kivételt dob; egy érvénytelen környezeti változó kapcsolódáskor kivételt dob. Az illesztőprogram nem áll vissza az alapértelmezett szolgáltatóra.
  • A szolgáltató rögzül, amikor a meghajtó natív kapcsolati kísérletet indít, még akkor is, ha az a próbálkozás sikertelen. Indítsd újra a Pythont a szolgáltatóváltáshoz. Más szolgáltatóra váltás RuntimeWarning kibocsátást okoz, és nincs hatása.

A kapcsolati karakterlánc validációs hibák és hiányzó szolgáltatócsomagok már e pont előtt fordulnak elő. Ezeket a hibákat javíthatod, és választhatsz másik szolgáltatót anélkül, hogy újrakezdenéd.

Hívd mssql_python.get_native_provider_info() fel, hogy megnézd a szolgáltató nevét, hogyan választották ki, és hogy a választás nem módosítható-e.

Az msodbcsql18 elemhez való visszatéréshez távolítsd el az alkalmazásodból a(z) MSSQL_PYTHON_NATIVE_PROVIDER elemet és az összes native_provider hozzárendelést, majd indítsd újra a Pythont.

A több-alhálózatos feladatátvétel alapértelmezett beállításai

A Rust szolgáltató alapértelmezés szerint engedélyezi a MultiSubnetFailover használatát az alkalmazható Transmission Control Protocol (TCP) kapcsolatokhoz. Állítsa be kifejezetten a(z) MultiSubnetFailover=no elemet, hogy sorrendi csatlakozási kísérleteket kérjen. A telepítésre érvényes alapértelmezés módosításához állítsa a MSSQL_RS_MULTISUBNET_FAILOVER_DEFAULT értékét true-re vagy false-re, mielőtt a natív illesztőprogramot először használná. A connection-string kulcsszó felülírja ezt az alapértelmezet.

A numerikus SQL_COPT_SS_MULTISUBNET_FAILOVER attribútum (1248) is felülírja a kulcsszót, ha a csatlakozás előtt állítják be.

Az illesztőprogram nem engedélyezi ezt az alapértelmezést nem TCP-alapú kapcsolatokhoz, adatbázis-tükrözéshez, olyan elnevezett példányokhoz, amelyek felderítéséhez a SQL Server Browser szükséges, illetve olyan helyi Windows-kapcsolatokhoz, amelyekben nincs kifejezetten megadva protokoll és cím. A(z) MultiSubnetFailover nem TCP-átvitelhez, adatbázis-tükrözéshez vagy az SQL Server Browser felderítéséhez való kifejezett engedélyezése kapcsolódási hibát okoz. További információért lásd: Magas rendelkezésre állás és feladatátvétel.

Támogatott funkciók

Az alábbi funkciók támogatottak, az ismert problémák figyelembevételével.

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). A natív illesztőprogram emellett a szerver-segített Domain Name System (DNS) gyorsítótárazást és a továbbfejlesztett útvonalválasztást is egyezteti, ha a szerver támogatja azokat.
Authentication SQL hitelesítés (UID / PWD); Windows-hitelesítés (Trusted_Connection=Yes, Security Support Provider Interface (SSPI) használatával Windows-on vagy Kerberos Linuxon és macOS-en); valamint Microsoft Entra ID interaktív, integrált eszközkód, szolgáltatásnév, menedzselt identitás, alapértelmezett hitelesítő adat és hozzáférési token. Microsoft Entra ID jelszóazonosítás nem támogatott. További információ: Ismert problémák.
Szállítási réteg biztonság (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 Függvény, dátum/idő, külső összekapcsolás, globálisan egyedi azonosító (GUID), LIKE ... {escape ...}, intervallum és {encrypt ...} escape formák.
Tárolt eljárások Hívd őket Transact-SQL (T-SQL) vagy pozíciós {call ...} szintaxissal execute(), olvasd el az eredményhalmazokat, és haladj tovább nextset().
Bemeneti paraméterek Skaláris paraméterek, SQL NULL, setinputsizes(), és kevert normál/streamelt paraméterek.
Nagy paraméterek A nagy szöveg-, bináris, Extensible Markup Language (XML)- és felhasználó által definiált típusú (UDT) paraméterek támogatják a végrehajtáskor megadott adatok streamelését.
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, valamint a read-uncommitted, read-committed, repeatable-read, serializable és snapshot izolációs szintek. Kikapcsolt autocommit esetén a kapcsolati kontextuskezelő sikeres kilépéskor véglegesíti a tranzakciót, kivétel esetén pedig visszagörgeti azt.
Lekérdezési időkorlát Állítsa be a Connection.timeout értékét másodpercben a kurzor létrehozása előtt. Ha egy utasítás meghaladja ezt az időkorlátot, az illesztőprogram kiváltja a(z) OperationalError kivételt. 0 azt jelenti, hogy nincs időkorlát. Állítsd be külön a bejelentkezési időkorlátot connect(timeout=...).
Kapcsolatmegosztás A beépített kapcsolatkészlet, beleértve a kapcsolat mssql-python alaphelyzetbe állítását az újrahasználat előtt. A hitelesítés-specifikus poolizolációval kapcsolatban lásd: Identitás-izoláció.
Metaadat API-k tables(), columns(), primaryKeys(), foreignKeys(), statistics()rowIdColumns(), rowVerColumns(), procedures()és getTypeInfo().
Kódolás és átalakítók Alapértelmezett széles karakterkódolás, kimeneti átalakítók és a kollációérzékeny, nem Unicode paraméterek, beleértve az UTF-8-at és a régi SQL sort-ID kollációkat. Az egyedi keskeny karakteres dekódolásnak meg kell egyeznie az ügyfél kódlapjával. További információ: Ismert problémák.

Microsoft Entra ID integrált hitelesítése a Windows-ban bejelentkezett Windows fiókot használja. Linuxon és macOS-en Kerberos jegyet használ a bérlő Active Directory összevonási szolgáltatások (AD FS) (AD FS) végpontjához való hitelesítéshez. Az előfeltételekkel kapcsolatban lásd a Windows integrált hitelesítés.

A(z) arrow_reader() bezárása elküldi a(z) SQLCancel elemet a folyamatban lévő lekérés megszakításához. A lezárási hívás megvárja, amíg a megszakítási tisztítás befejeződik. További információért lásd: Apache Arrow integráció.

Adattípusok

Az illesztőprogram xml, json és vector értékeket Python str objektumként ad vissza, és a vector JavaScript Object Notation (JSON) tömbként van ábrázolva. A közös nyelvi futtatókörnyezet (CLR) típusokat, mint például a geometry, geography és hierarchyid típusokat Python bytes objektumként adja vissza. További információért lásd: Adattípus-leképezések és 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 ID jelszavas hitelesítés Authentication=ActiveDirectoryPassword nem támogatott. Ez a módszer nem képes megfelelni a többtényezős hitelesítés (MFA) követelményeinek. SQL hitelesítés (UID / PWD) nem érintett. Használj egy másik Microsoft Entra ID-módszert, például szolgáltatásnevet, kezelt identitást vagy hozzáférési tokent.
attrs_before beállítások A Microsoft Entra ID hitelesítési mód és az alkalmazási szándék nem állítható be numerikus kapcsolati attribútumként. Használd az Authentication és ApplicationIntent kapcsolati karakterlánc kulcsszavakat.
Kapcsolódási művelet időtúllépése SQL_ATTR_CONNECTION_TIMEOUT a megszakításkori takarítást vezérli. Nem alkalmaz időkorlátot a pooled-connection visszaállításnál. A kapcsolatkérés blokkolva maradhat, ha a szerver nem válaszol az alaphelyzetbe állítás során. Nem érhető el készletalaphelyzetbe állítási időkorlát. Állítsa be a connect(timeout=...) elemet bejelentkezéshez, a Connection.timeout elemet pedig számlakivonatokhoz.
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. Használja a(z) MultiSubnetFailover=yes elemet az elérhetőségi csoport figyelői és más többcímes gazdagépek számára. Az alapértelmezett beállításokat lásd itt: Több alhálózatos feladatátvétel alapértelmezett beállításai.
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.
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.
Natív követés Linuxon Ha a natív követés be van kapcsolva, a Python megszakíthatja az illesztőprogram tisztítása során a folyamat kilépésekor. Hagyd a MSSQL_TDS_TRACE értékét beállítatlanul Linuxon.
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. Az előkészített utasítás tisztítása az utasítás lekérdezési időkorlátját használja, de egy nulla időkorlát korlátlanul hagyja ezt a tisztítást. Csak azokat a sorokat hozd le, amelyekre szükséged van, például a(z) TOP használatával, és állítsd be a(z) Connection.timeout értéket a kurzor létrehozása előtt.
Szűk karakterek egyéni dekódolása A natív illesztőprogram a Windows ANSI kódlapját használja Windowson, valamint Linuxon és macOS-en a folyamat területi beállításának kódlapját keskeny karakteres szöveghez. Egy explicit Python dekódolás, amely nem egyezik meg azzal a kódlappal, hibás szöveget vagy bytes eredményezhet. Használd az alapértelmezett széles karakteres dekódolást: conn.setdecoding(mssql_python.SQL_CHAR).
Connection.getinfo() Néhány képességérték és csomagméret-alapú korlát eltér a(z) msodbcsql18-tól. SQL_USER_NAME az adatbázis-rendszerbiztonsági tagot jelenti, nem pedig a kapcsolati sztringet UID. Kérdezd le a konkrét szerver metaadatait, amikor egy jelentett képesség vagy korlátozás számít az alkalmazásod számára.
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 A varchar(max) és nvarchar(max) adatok darabos olvasásai lassabbak lehetnek, mint a(z) msodbcsql18 esetén. (#473) Hasonlítsd össze a munkaterhelésedet.

Probléma bejelentése

Ha hibával találkozol, ismételd meg azt msodbcsql18 , és jegyezd fel, hogy mindkét szolgáltatónál előfordul-e. A váltási útmutatóért lásd: Az illesztőprogram engedélyezése.

Tartalmazza a jelentésedben a(z) mssql_python.get_native_provider_info() kimenetét, az operációs rendszeredet, a Python és a driver verzióit, valamint a hibás T-SQL batch-et és a hibaüzenetet:

Windows-on állítsd be ezeket a változókat a PowerShell-ben, mielőtt elindítod a Pythont, hogy natív illesztőprogram-diagnosztikákat gyűjts. Ismételd meg a problémát úgy, hogy a(z) mssql-odbc ki van jelölve:

$env:MSSQL_TDS_TRACE = "true"
$env:MSSQL_TDS_TRACE_LEVEL = "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ózási szintet, és MSSQL_TDS_TRACE_DIR kiválasztja a natív ODBC illesztőprogram folyamatonkénti nyomkövetési fájljainak könyvtárát a szabványos hibakimenet helyett. A Rust kísérőcsomag naplófájlokat is létrehoz a jelenlegi könyvtárban, a mssql_python_logs alatt.

A nyomok tartalmazhatnak T-SQL szöveget és paraméterértékeket. Szerkeszd ki az érzékeny adatokat, mielőtt megosztod a részleteket. A diagnózis után távolítsd el ezeket a környezeti változókat, és indítsd újra a Pythont, hogy letiltsd a követést.

Kapcsolódó tartalom

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