De mssql-odbc-driver gebruiken (Preview)

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

Provider Wat het is Status
msodbcsql18 Microsoft ODBC Driver 18 voor SQL Server, de gevestigde C++-driver Standaard, ongewijzigd
mssql-odbc Een nieuwe ODBC-driver geschreven in Rust Preview, opt-in

Dit artikel behandelt mssql-odbc0.3.0, de versie die momenteel door mssql-python wordt gebruikt, en wat verschilt van msodbcsql18.

Note

mssql-odbc is actief in ontwikkeling en validatie. Het is nog geen volledige vervanging van Microsoft ODBC Driver 18. Houd msodbcsql18 voorlopig als productiestandaard. Het ontwikkelingsteam is van plan de gaps in de preview in aankomende releases te dichten, behalve voor opzettelijke uitsluitingen die expliciet in dit artikel worden genoemd.

Availability

De driver wordt geleverd in het mssql-python-rs pakket als voorgecompileerde wheels voor CPython 3.10 en later:

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

Het inschakelen van het stuurprogramma

Het mssql-python pakket hangt af van mssql-python-rs, dus een normale installatie brengt de Rust-driver mee:

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 vóór de eerste verbinding, of met een omgevingsvariabele:

Powershell:

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

Bash of Zsh:

export MSSQL_PYTHON_NATIVE_PROVIDER=mssql-odbc

of van Python:

import mssql_python

mssql_python.native_provider = "mssql-odbc"

Maak verbinding met de bestaande verbindingsreeks van je applicatie. Houd certificaatvalidatie ingeschakeld (Encrypt=yes;TrustServerCertificate=no). Voor authenticatie en certificaatconfiguratie, zie Verbindingsstrings en Versleuteling en certificaten.

connection = mssql_python.connect(connection_string)

Het stuurprogramma past deze regels toe bij het kiezen van de aanbieder:

  • De MSSQL_PYTHON_NATIVE_PROVIDER omgevingsvariabele heeft voorrang boven native_provider. Een conflicterende attribuuttoewijzing genereert RuntimeWarning.
  • De selectie wordt vastgesteld na validatie van de verbindingsreeks en direct voordat de native verbinding wordt opgebouwd. Een latere verbindingsfout wist de selectie niet. Een eerdere fout bij het parseren van verbindingsreeksen of een ontbrekend providerpakket corrigeert de selectie niet. Nadat de selectie is vastgesteld, heeft het wijzigen van native_provider naar een andere provider geen effect en veroorzaakt dit RuntimeWarning. Start het proces opnieuw om van provider te wisselen.
  • Een niet-erkende providernaam veroorzaakt een fout ValueError; de driver valt niet terug op de standaardprovider. Een onbekende naam toegewezen aan native_provider leidt onmiddellijk tot een fout. Een onbekende naam in de omgevingsvariabele veroorzaakt een fout wanneer je probeert verbinding te maken.
  • Zet native_provider op None om de attribuutselectie te wissen voordat deze vastligt. De omgevingsvariabele heeft nog steeds voorrang.

Bel mssql_python.get_native_provider_info() om de geselecteerde aanbieder, selectiebron en of de selectie vast is te inspecteren. Voordat je verbinding maakt, meldt dit de selectie, niet het bewijs dat de native driver succesvol is geladen.

Om terug te gaan, zet je de variabele op msodbcsql18, of maak je deze oningesteld en verwijder je elke native_provider toewijzing uit je code (of zet je hem op "msodbcsql18"). Start het proces daarna opnieuw.

Wat vandaag werkt

De mssql-odbc driver implementeert elke ODBC-functie die mssql-python aanroept, zodat de meeste applicaties van provider kunnen wisselen zonder codewijzigingen. Raadpleeg Bekende problemen voor de resterende verschillen.

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).
Authentication SQL-authenticatie (UID / PWD); Windows authentication (Trusted_Connection=Yes, met SSPI op Windows of Kerberos op Linux en macOS); en Microsoft Entra interactief, apparaatcode, service principal, beheerde identiteit, standaardinloggegevens en toegangstoken. Geïntegreerde Entra- en wachtwoordauthenticatie worden niet ondersteund; zie Bekende problemen.
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-, GUID-, LIKE ... {escape ...}-interval- en {encrypt ...}-escapereeksen.
opgeslagen procedures Roep ze aan met T-SQL of positionele {call ...} syntaxis via execute(), lees resultaatsets en ga verder met nextset().
Invoerparameters Scalaire parameters, SQL NULL, setinputsizes(), en gemengde reguliere/gestreamde parameters.
Lange parameters Grote tekst- en binaire parameters stromen naar de server via het gewone bindingspad; XML- en UDT-parameterbeperkingen worden hieronder vermeld.
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, de automatische commit (of rollback, als een fout is doorgeglipt) die optreedt wanneer een with connect(...) block eindigt, en de read-uncommitted, read-committed, repeatable-read, serializable en snapshot isolatieniveaus.
Querytime-out Stel Connection.timeout (in seconden) in om statements te begrenzen die door de cursors van die verbinding worden uitgevoerd; het verlopen ervan veroorzaakt OperationalError. 0 betekent geen time-out. Deze instelling staat los van de logintimeout die als connect(timeout=...)wordt doorgegeven.
Groepsgewijze verbindingen De ingebouwde mssql-python pool, inclusief reset van verbindingen bij het ophalen uit de pool en aparte pools per Microsoft Entra-identiteit.
Metagegevens-API's tables(), columns(), primaryKeys(), foreignKeys(), statistics(), rowIdColumns(), rowVerColumns(), procedures(), en getTypeInfo().
Encoding en converters Standaard wide-character-codering en uitvoeromzetters. Aangepaste smalkarakterdecodering en niet-Unicode-parameterconversie hebben beperkingen vermeld in Bekende problemen.

Gegevenstypen

Je kunt alle SQL Server-datatypes lezen, en de driver ondersteunt elk parametertype dat mssql-python bindt. De driver retourneert xml, str en json-waarden als vector (geometry als een JSON-array), en CLR-types zoals geography, hierarchyid en bytes als vector. Voor andere Python-mappings, zie Toewijzingen van gegevenstypen. Zie Bekende problemen voor typespecifieke beperkingen.

Bekende problemen

Controleer deze verschillen voordat je een werklast verplaatst van msodbcsql18.

Issue Details Workaround
Geïntegreerde Microsoft Entra-verificatie Authentication=ActiveDirectoryIntegrated wordt niet ondersteund. Windows authentication (Trusted_Connection=Yes) wordt niet beïnvloed. Gebruik een andere Microsoft Entra-methode, of houd msodbcsql18.
Wachtwoordverificatie voor Microsoft Entra Authentication=ActiveDirectoryPassword wordt niet ondersteund, en ondersteuning is ook niet gepland omdat deze methode niet aan MFA kan voldoen. SQL-authenticatie (UID / PWD) wordt niet beïnvloed. Gebruik een andere Microsoft Entra-methode, zoals een service principal, managed identity of access token.
attrs_before instellingen Authenticatie, applicatieintentie en multi-subnet failover kunnen niet als numerieke attributen worden ingesteld. Statement-attributen anders dan query-timeout worden geweigerd. Gebruik de equivalente trefwoorden voor de verbindingsreeks.
Time-out bij verbindingsbewerking set_attr(SQL_ATTR_CONNECTION_TIMEOUT, ...) accepteert en slaat de waarde op, maar het handhaaft geen timeout in 0.3.0. Gebruik connect(timeout=...) voor login en Connection.timeout voor statements; geen van beide is een algemene deadline voor verbinding-operaties.
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. Zonder MultiSubnetFailover=Yes, worden adressen één voor één geprobeerd, dus een onbereikbaar adres kan de verbinding vertragen. Server-ondersteunde DNS-caching en verbeterde routering worden niet overeengekomen. Stel MultiSubnetFailover=Yes in voor beschikbaarheidsgroepluisteraars en andere hosts met meerdere adressen.
Tijdelijke DNS-storingen Als een DNS-zoekopdracht faalt, valt de driver niet terug naar het laatst succesvolle adres. (#457) Voer de verbinding opnieuw uit.
Gegevensclassificatie Metadata voor gevoeligheidsclassificatie is niet beschikbaar en SQL_COPT_SS_DATACLASSIFICATION_VERSION (1400) wordt niet ondersteund. Query sys.sensitivity_classifications.
Multithreading Gebruik met meerdere threads is nog niet gevalideerd. Gebruik msodbcsql18 voor multithreaded workloads.
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.
Het annuleren van een actieve statement Een lopende query of fetch kan niet worden onderbroken. Bijvoorbeeld, het sluiten van een arrow_reader() stopt een lopende leesbewerking op een andere thread niet. Gebruik Connection.timeout om langlopende statements te beperken.
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. Het sluiten van een cursor die een voorbereide instructie gebruikt, negeert Connection.timeout en kan vastlopen als de server stopt met reageren. (#546) Haal alleen de rijen die je nodig hebt, bijvoorbeeld met TOP.
Large xml en UDT-parameters Waarden die als SQL_SS_XML of SQL_SS_UDT door setinputsizes() worden gebonden, worden in het geheugen gebufferd in plaats van gestreamd. Bind xml waarden als gewone tekenreeksen.
Lege image waarden Een lege, niet-NULL SQL Server-waarde image wordt teruggegeven als None in plaats van b"". Lees CAST(image_column AS varbinary(max)), of gebruik msodbcsql18 wanneer het onderscheid tussen leeg en NULL belangrijk is.
Niet-Unicode-tekenreeksparameters Tekenreeksen die aan char / varchar tot en met setinputsizes() zijn gebonden, kunnen verkeerd worden gecodeerd voor codepagina 437, codepagina 850 en UTF-8-collaties. Gebruik de standaard stringbinding.
Legacy codepagina-decodering op Windows Met setdecoding(SQL_CHAR, encoding="cp1252") of een andere legacy-codepage kan tekst verkeerd worden gedecodeerd of worden teruggegeven als bytes, omdat de driver gegevens char / varchar als UTF-8 teruggeeft. Gebruik de standaard: conn.setdecoding(mssql_python.SQL_CHAR).
Connection.getinfo() SQL_USER_NAME geeft de verbindingsstring UID, niet de databasegebruiker. Het is leeg wanneer geen UID de driver bereikt. Sommige capaciteitswaarden en pakketgrootte-gebaseerde limieten verschillen van msodbcsql18. Gebruik SELECT USER_NAME() voor de databasegebruiker.
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 In één benchmark waren de reads in chunks van varchar(max) / nvarchar(max) data iets langzamer dan met msodbcsql18. (#473) Meet je werklast.

Deze lijst is niet volledig.

Problemen melden

Als je een bug tegenkomt, selecteer msodbcsql18dan , herstart het proces en controleer of het gedrag nog steeds voorkomt. Verwijder ook elke conflicterende provider-toewijzing aan de Python-zijde. De vergelijking helpt het probleem te isoleren; het bewijst op zichzelf de oorzaak niet. Voeg de output van mssql_python.get_native_provider_info(), je platform en de mislukte SQL-query of foutmelding toe:

Voor Rust-driver diagnostiek stel je deze variabelen in voordat je Python start en reproduceer je het probleem met mssql-odbc geselecteerd. Bijvoorbeeld in PowerShell:

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

MSSQL_TDS_TRACE Maakt traceren mogelijk, MSSQL_TDS_TRACE_LEVEL selecteert het logfilter en MSSQL_TDS_TRACE_DIR schrijft per-procesbestanden in plaats van STDERR. Herstart Python nadat je deze instellingen hebt gewijzigd. Traces kunnen SQL-tekst en parameterwaarden bevatten. Beoordeel en lak gevoelige gegevens weg voordat relevante fragmenten worden gedeeld, en schakel tracering uit na de diagnose.

Verwante onderwerpen

  • Laatst bijgewerkt om