Gebruik de mssql-odbc driver (Preview)

mssql-python laadt een van de twee native ODBC-providers:

Provider Description Status
msodbcsql18 Microsoft ODBC-stuurprogramma 18 voor SQL Server Default
mssql-odbc Rust-gebaseerde ODBC-driver Preview, opt-in

Het mssql-python-rs0.4.0-pakket bevat de mssql-odbc provider.

Note

Gebruik msodbcsql18 voor productieworkloads. Voordat je je aanmeldt voor de previewprovider mssql-odbc , bekijk de bekende problemen.

Availability

De driver wordt geleverd in het mssql-python-rs pakket als voorgebouwde wheels voor CPython 3.10 en latere versies:

Platform Architectures
Windows x64; ARM64 op CPython 3.11 en latere versies
macOS Universal2 (x86_64 en arm64), macOS 15 en latere versies
Linux (glibc) x86_64 en aarch64 (manylinux_2_28 en manylinux_2_34)
Linux (musl) x86_64 en aarch64 (musllinux_1_2)

Het stuurprogramma inschakelen

Als u mssql-python installeert, wordt ook mssql-python-rs geïnstalleerd, dat het stuurprogramma mssql-odbc bevat:

python -m pip install mssql-python

Als je installeert met --no-deps of vanuit een privé-index, installeer mssql-python-rs dan expliciet ook.

Selecteer de provider voordat je de eerste verbinding opent. Gebruik een van de volgende methoden.

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

Stel de MSSQL_CONNECTION_STRING omgevingsvariabele in op de verbindingsreeks van je applicatie. Houd certificaatvalidatie ingeschakeld (Encrypt=yes;TrustServerCertificate=no). Voor meer informatie, zie Verbindingsstrings en Versleuteling en certificaten.

Voer dit voorbeeld uit met de door je gekozen provider:

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

Het voorbeeld geeft 1 weer.

De keuze van provider volgt deze regels:

  • MSSQL_PYTHON_NATIVE_PROVIDER heeft voorrang op native_provider. Het instellen van het attribuut op een conflicterende provider geeft RuntimeWarning.
  • Voordat de driver laadt, zet je native_provider op None om de Python-instelling te wissen. Dit wist de omgevingsvariabele niet.
  • Een niet-erkende zorgverlenersnaam veroorzaakt ValueError. Het toewijzen van een ongeldige naam aan native_provider geeft meteen een fout; een ongeldige omgevingsvariabele geeft een fout wanneer je verbinding maakt. De driver valt niet terug op de standaardprovider.
  • De provider is vastgelegd wanneer de driver een native verbindingspoging start, zelfs als die poging mislukt. Herstart Python om van provider te wisselen. Wijzigen van native_provider naar een andere provider genereert RuntimeWarning en heeft geen effect.

Fouten in verificatie van verbindingsstrings en ontbrekende providerpakketten komen al vóór dit punt voor. Je kunt deze fouten corrigeren en een andere provider kiezen zonder opnieuw te hoeven starten.

Bel mssql_python.get_native_provider_info() om de naam van de zorgverlener te controleren, hoe deze is geselecteerd en of de keuze vaststaat.

Om terug te keren naar msodbcsql18, verwijder MSSQL_PYTHON_NATIVE_PROVIDER en elke native_provider toewijzing uit je applicatie, start dan Python opnieuw op.

Multi-subnet failover standaardinstellingen

De Rust-provider maakt MultiSubnetFailover standaard mogelijk voor toepasbare Transmission Control Protocol (TCP)-verbindingen. Stel MultiSubnetFailover=no expliciet in om sequentiële verbindingspogingen te verzoeken. Om de deployment-brede standaard te wijzigen, stel MSSQL_RS_MULTISUBNET_FAILOVER_DEFAULT in op true of false voordat de native driver voor het eerst wordt gebruikt. Het sleutelwoord van de connection string overschrijft deze standaard.

Het numerieke SQL_COPT_SS_MULTISUBNET_FAILOVER attribuut (1248) overschrijft ook het trefwoord wanneer het wordt ingesteld vóór het verbinden.

De driver schakelt deze standaard niet in voor niet-TCP transports, databasespiegeling, benoemde instanties die SQL Server Browser-ontdekking vereisen, of lokale Windows-verbindingen die een expliciet protocol en adres weglaten. Het expliciet inschakelen van MultiSubnetFailover bij een niet-TCP-transport, databasespiegeling of SQL Server Browser-ontdekking levert een verbindingsfout op. Voor meer informatie, zie Hoge beschikbaarheid en failover.

Ondersteunde functies

De volgende functies worden ondersteund, onder voorbehoud van bekende problemen.

Area Notes
Levenscyclus van de verbinding Verbinden, close(), with blokken, inlogtimeout, diagnostiek en het wijzigen van de huidige database. Instellingen voor verbindingsstrings zijn onder andere ApplicationIntent, MultiSubnetFailover, IpAddressPreference, PacketSize, KeepAlive, en ConnectRetryCount / ConnectRetryInterval (idle-verbindingsveerkracht). De natieve driver onderhandelt ook over door de server ondersteunde Domain Name System (DNS)-caching en verbeterde routering wanneer de server deze ondersteunt.
Authentication SQL-authenticatie (UID / PWD); Windows-verificatie (Trusted_Connection=Yes, met behulp van Security Support Provider Interface (SSPI) op Windows of Kerberos op Linux en macOS); en Microsoft Entra ID interactief, geïntegreerd, apparaatcode, serviceprincipal, beheerde identiteit, standaardinloggegevens en toegangstoken. Microsoft Entra ID-wachtwoordauthenticatie wordt niet ondersteund. Zie Bekende problemen voor meer informatie.
Transportlaagbeveiliging (TLS) Encrypt, TrustServerCertificate, HostnameInCertificate en ServerCertificate.
Query uitvoeren Directe en voorbereide uitvoering, hergebruik van voorbereide plannen, qmark parameters en de conversie die pyformatmssql-python uitvoert.
ODBC-escape-syntaxis Functie, datum/tijd, outer join, wereldwijd unieke identificatie (GUID), LIKE ... {escape ...}, interval en {encrypt ...} escape-vormen.
opgeslagen procedures Roep ze aan met Transact-SQL (T-SQL) of positionele {call ...} syntaxis via execute(), lees resultaatsets, en ga door met nextset().
Invoerparameters Scalaire parameters, SQL NULL, setinputsizes(), en gemengde reguliere/gestreamde parameters.
Lange parameters Grote tekst-, binaire, Extensible Markup Language (XML)- en door de gebruiker gedefinieerde typen (UDT)-parameters ondersteunen data-at-execution streaming.
executemany() Gebatcht met ODBC-parameterarrays. Rijen met gestreamde waarden vallen terug op rij-voor-rij-uitvoering.
Rij ophalen fetchone(), fetchmany(), fetchall(), iteratie, fetchval(), getypte conversie en grote tekst-/binaire streaming.
Pijl ophalen arrow_batch(), arrow() en arrow_reader(). Vereist pyarrow.
Meerdere resultaatsets nextset(), inclusief resultaten geproduceerd door parameterarrays.
Transactions Autocommit, commit, rollback, en de read-uncommitted, read-committed, repeatable-read, serializable en snapshot isolatieniveaus. Met autocommit uitgeschakeld voert de connection context manager bij een succesvolle exit een commit uit en draait deze bij een uitzondering terug.
Querytime-out Stel Connection.timeout in op seconden voordat je een cursor maakt. Wanneer een statement die time-out overschrijdt, genereert de driver OperationalError. 0 betekent geen time-out. Stel de inlogtime-out apart in met connect(timeout=...).
Groepsgewijze verbindingen De ingebouwde mssql-python pool, inclusief het resetten van de verbinding vóór hergebruik. Voor authenticatie-specifieke poolisolatie, zie Identiteitsisolatie.
Metagegevens-API's tables(), columns(), primaryKeys(), foreignKeys(), statistics(), rowIdColumns(), rowVerColumns(), procedures(), en getTypeInfo().
Encoding en converters Standaard brede-tekencodering, outputconverters en collatiebewuste niet-Unicode-parameters, inclusief UTF-8 en legacy SQL sort-ID-collaties. Aangepaste smalkarakterdecodering moet overeenkomen met de codepagina van de klant. Zie Bekende problemen voor meer informatie.

Microsoft Entra ID geïntegreerde authenticatie gebruikt het ingelogde Windows-account op Windows. Op Linux en macOS gebruikt het een Kerberos-ticket om te authenticeren bij het Active Directory Federation Services (AD FS) eindpunt van de tenant. Voor de vereisten, zie Windows Integrated authentication.

Het sluiten van een arrow_reader() stuurt SQLCancel om een lopende fetch te onderbreken. De bijna-gelukte aanroep wacht tot de annuleringsopschoning is afgerond. Voor meer informatie, zie Apache Arrow-integratie.

Gegevenstypen

De driver retourneert xml-, json- en vectorwaarden als Python str-objecten, waarbij vector wordt weergegeven als een JavaScript Object Notation (JSON) array. Het geeft algemene taalruntime (CLR)-typen zoals geometry, geography en hierarchyid terug als Python-objectenbytes. Voor meer informatie, zie Datatype-mappings en Bekende problemen.

Bekende problemen

Controleer deze verschillen voordat je een werklast verplaatst van msodbcsql18.

Issue Details Workaround
Microsoft Entra ID wachtwoordauthenticatie Authentication=ActiveDirectoryPassword wordt niet ondersteund. Deze methode kan niet worden gebruikt voor multifactorauthenticatie (MFA). SQL-authenticatie (UID / PWD) wordt niet beïnvloed. Gebruik een andere Microsoft Entra ID-methode, zoals een service principal, managed identity of access token.
attrs_before instellingen De Microsoft Entra ID-authenticatiemodus en applicatieintentie kunnen niet worden ingesteld als numerieke verbindingsattributen. Gebruik de verbindingsreeks-trefwoorden Authentication en ApplicationIntent.
Time-out bij verbindingsbewerking SQL_ATTR_CONNECTION_TIMEOUT verzorgt het opschonen na annulering. Het dwingt geen time-out af bij het reseten van de pooled verbinding. Een verbindingsverzoek kan geblokkeerd blijven als de server stopt met reageren tijdens de reset. Er is geen pooled-reset timeout beschikbaar. Stel connect(timeout=...) voor inloggen en Connection.timeout voor statements.
Hosts met meerdere adressen msodbcsql18 schakelt standaard Transparent Network IP Resolution (TNIR) in; mssql-odbc ondersteunt het niet. mssql-python wijst het TransparentNetworkIPResolution-trefwoord in de verbindingsreeks af bij een van beide providers. Gebruik MultiSubnetFailover=yes voor listeners van beschikbaarheidsgroepen en andere multi-adreshosts. Voor standaardinstellingen, zie Multi-subnet failover defaults.
Gegevensclassificatie Metadata voor gevoeligheidsclassificatie is niet beschikbaar en SQL_COPT_SS_DATACLASSIFICATION_VERSION (1400) wordt niet ondersteund. Query sys.sensitivity_classifications.
fork() na het verbinden Op Linux kan een proces dat wordt geforkt nadat het bovenliggende proces verbinding heeft gemaakt vastlopen wanneer het de driver gebruikt, zelfs bij een nieuwe verbinding. Met pooling ingeschakeld kan het bovenliggende proces ook hangen. (#566) Gebruik de spawn startmethode en maak binnen elke worker verbinding.
Native tracing in Linux Met native tracing ingeschakeld kan Python tijdens het opruimen van de driver bij het afsluiten van het proces worden afgebroken. Laat MSSQL_TDS_TRACE niet ingesteld op Linux.
Ongelezen resultaten Het sluiten van een cursor of het uitvoeren van een andere instructie leest en negeert de resterende resultaten in plaats van ze te annuleren, wat traag kan zijn. Prepared-statement cleanup gebruikt de querytimeout van de statement, maar een timeout van nul laat die cleanup onbeperkt. Haal alleen de rijen die je nodig hebt, bijvoorbeeld met TOP, en stel Connection.timeout in voordat je de cursor maakt.
Aangepaste decodering van smalle tekens De native driver gebruikt de Windows ANSI-codepage op Windows en de codepage van de proceslocale op Linux en macOS voor smalle tekst. Een expliciete Python-decodering die niet overeenkomt met die codepagina kan onjuiste tekst of bytes opleveren. Gebruik de standaard decodering van brede tekens: conn.setdecoding(mssql_python.SQL_CHAR).
Connection.getinfo() Sommige capaciteitswaarden en pakketgrootte-gebaseerde limieten verschillen van msodbcsql18. SQL_USER_NAME rapporteert de databaseprincipal in plaats van de verbindingsstring UID. Raadpleeg de specifieke servermetadata wanneer een gerapporteerde mogelijkheid of limiet van belang is voor je applicatie.
Geheugentekortfouten Sommige driverallocatiefouten beëindigen het Python-proces in plaats van MemoryError op te werpen. (#484) Beperk de grootte van de waarden die je stuurt en ophaalt.
Leesprestaties voor grote waarden Gefragmenteerde reads van varchar(max) en nvarchar(max) data kunnen langzamer zijn dan met msodbcsql18. (#473) Meet je werklast.

Meld problemen

Als je een bug tegenkomt, reproduceer deze dan met msodbcsql18 en registreer of het bij beide providers voorkomt. Voor instructies voor het overschakelen, zie De driver inschakelen.

Voeg de output van mssql_python.get_native_provider_info(), je besturingssysteem, Python- en driverversies, en de mislukte T-SQL-batch en foutmelding toe in je rapport:

Op Windows stel je deze variabelen in PowerShell voordat je Python start om native-driver diagnostiek te verzamelen. Reproduceer het probleem met mssql-odbc geselecteerd:

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

MSSQL_TDS_TRACE maakt traceren mogelijk, MSSQL_TDS_TRACE_LEVEL selecteert het logniveau en MSSQL_TDS_TRACE_DIR selecteert de map voor per-proces tracebestanden vanuit de native ODBC-driver in plaats van standaard foutuitvoer. Het Rust companion-pakket maakt ook logbestanden aan onder mssql_python_logs in de huidige map.

Traces kunnen T-SQL-tekst- en parameterwaarden bevatten. Anonimiseer gevoelige gegevens voordat je fragmenten deelt. Verwijder na de diagnose deze variabelen en start Python opnieuw om tracing uit te schakelen.

Verwante onderwerpen

  • Laatst bijgewerkt om