Använd mssql-odbc-drivrutinen (Förhandsvisning)

mssql-python laddar en av två interna ODBC-leverantörer:

Provider Description Status
msodbcsql18 Microsoft ODBC Driver 18 för SQL Server Standardvärde
mssql-odbc Rust-baserad ODBC-drivrutin Förhandsgranskning, opt-in

Paketet mssql-python-rs inkluderar mssql-odbcprovidern.

Note

Använd msodbcsql18 för produktionsarbetsbelastningar. Innan du väljer att gå med i förhandsvisningsleverantören mssql-odbc , granska dess kända problem.

Availability

Drivrutinen levereras i paketet mssql-python-rs som förbyggda wheels för CPython 3.10 och senare versioner:

Platform Architectures
Windows x64; ARM64 på CPython 3.11 och senare versioner
macOS Universal2 (x86_64 och arm64), macOS 15 och senare versioner
Linux (glibc) x86_64 och aarch64 (manylinux_2_28 och manylinux_2_34)
Linux (musl) x86_64 och aarch64 (musllinux_1_2)

Aktivera drivrutinen

När du installerar mssql-python installeras också mssql-python-rs, som innehåller drivrutinen mssql-odbc:

python -m pip install mssql-python

Om du installerar med --no-deps eller från ett privat index, installera mssql-python-rs explicit också.

Välj providern innan du öppnar den första anslutningen. Använd någon av följande metoder.

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

Ställ in miljövariabeln MSSQL_CONNECTION_STRING till applikationens anslutningssträng. Ha certifikatvalidering aktiverad (Encrypt=yes;TrustServerCertificate=no). För mer information, se Anslutningssträngar och Kryptering och certifikat.

Kör detta exempel med din valda leverantör:

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

Exemplet skriver ut 1.

Val av vårdgivare följer följande regler:

  • MSSQL_PYTHON_NATIVE_PROVIDER har företräde framför native_provider. Att sätta attributet till en leverantör som står i konflikt ger RuntimeWarning.
  • Innan drivrutinen laddas, ställ in native_provider på None för att rensa Python-inställningen. Detta rensar inte miljövariabeln.
  • Ett okänt leverantörsnamn genererar ValueError. Att tilldela native_provider ett ogiltigt namn ger omedelbart ett fel; en ogiltig miljövariabel ger ett fel när du ansluter. Drivrutinen återgår inte till standardleverantören.
  • Leverantören är fixad när drivrutinen påbörjar ett försök till nativ anslutning, även om det försöket misslyckas. Starta om Python för att byta leverantörer. Att byta native_provider till en annan leverantör ger RuntimeWarning och har ingen effekt.

Verifieringsfel i anslutningssträngar och saknade leverantörspaket uppstår före denna punkt. Du kan rätta till dessa fel och välja en annan leverantör utan att behöva starta om.

Ring mssql_python.get_native_provider_info() för att kontrollera leverantörens namn, hur det valdes och om valet är låst.

För att återgå till msodbcsql18, ta bort MSSQL_PYTHON_NATIVE_PROVIDER och alla native_provider-tilldelningar från din applikation, starta sedan om Python.

Standardinställningar för Multi-subnet failover

Rust-leverantören möjliggör MultiSubnetFailover som standard för tillämpliga Transmission Control Protocol (TCP)-anslutningar. Ange MultiSubnetFailover=no uttryckligen för att begära sekventiella anslutningsförsök. För att ändra standardinställningen för hela distributionen, ställ in MSSQL_RS_MULTISUBNET_FAILOVER_DEFAULT till true eller false innan den inbyggda drivrutinen används första gången. Nyckelordet connection-string åsidosätter det här standardvärdet.

Det numeriska attributet SQL_COPT_SS_MULTISUBNET_FAILOVER (1248) åsidosätter också nyckelordet när det anges innan anslutning upprättas.

Drivrutinen aktiverar inte denna standard för icke-TCP-transporter, databasspegling, namngivna instanser som kräver SQL Server Browser-upptäckt eller lokala Windows-anslutningar som utelämnar ett explicit protokoll och adress. Att explicit aktivera MultiSubnetFailover för en icke-TCP-transport, databasspegling eller SQL Server-webbläsarupptäckt ger ett anslutningsfel. För mer information, se Hög tillgänglighet och failover.

Funktioner som stöds

Följande funktioner stöds, med förbehåll för kända problem.

Area Notes
Anslutningslivscykel Anslutning, close(), with-block, inloggningstidsavbrott, diagnostik och ändring av den aktuella databasen. Anslutningssträngsinställningar inkluderar ApplicationIntent, MultiSubnetFailover, IpAddressPreference, PacketSize, KeepAlive och ConnectRetryCount / ConnectRetryInterval (resiliens för inaktiva anslutningar). Den inbyggda drivrutinen förhandlar också serverassisterad Domain Name System (DNS)-cachelagring och förbättrad routning när servern stödjer dem.
Authentication SQL-autentisering (UID / PWD); Windows-autentisering (Trusted_Connection=Yes, med Security Support Provider Interface (SSPI) på Windows eller Kerberos på Linux och macOS); samt Microsoft Entra ID interaktiv, integrerad, enhetskod, tjänstens huvudnamn, hanterad identitet, standardautentiseringsuppgift och åtkomsttoken. Microsoft Entra ID-lösenordsautentisering stöds inte. Mer information finns i Kända problem.
Transportskiktsäkerhet (TLS) Encrypt, TrustServerCertificate, HostnameInCertificate och ServerCertificate.
Frågekörning Direkt och förberedd körning, återanvändning av förberedda planer, qmark parametrar och konverteringen pyformatmssql-python utför.
ODBC-escape-syntax Funktion, datum/tid, yttre koppling, globalt unik identifierare (GUID), LIKE ... {escape ...}, intervall, och {encrypt ...} escape-formulär.
Lagrade procedurer Anropa dem med Transact-SQL (T-SQL) eller positionssyntax {call ...} genom execute(), läs resultatmängder och gå vidare med nextset().
Indataparametrar Skalärparametrar, SQL NULL, setinputsizes(), och blandade vanliga/strömmade parametrar.
Stora parametrar Stora textparametrar, binära parametrar, Extensible Markup Language (XML)-parametrar och användardefinierade typparametrar (UDT) stöder strömning av data vid körning.
executemany() Batchkörs med ODBC-parameterarrayer. Rader som innehåller strömmade värden faller tillbaka på rad-för-rad-exekvering.
radhämtning fetchone(), fetchmany(), fetchall(), iterering, fetchval(), typad konvertering och stor text-/binärströmning.
Hämtning av pilar arrow_batch(), arrow() och arrow_reader(). Kräver pyarrow.
Flera resultatuppsättningar nextset(), inklusive resultat som produceras av parameterarrayer.
Transaktioner Autocommit, commit, rollback samt read-uncommitted, read-committed, repeatable-read, serializable och snapshot isolation-nivåerna. Med autocommit avstängt commitar anslutningskontexthanteraren vid lyckad avslutning och rullar tillbaka vid ett undantag.
Tidsgräns för fråga Ställ in Connection.timeout i sekunder innan du skapar en markör. När en sats överskrider den timeouten utlöser drivern OperationalError. 0 betyder ingen timeout. Ställ in timeout för inloggning separat med connect(timeout=...).
Anslutningspoolning Den inbyggda mssql-python poolen, inklusive återställning av anslutningen före återanvändning. För autentiseringsspecifik poolisolering, se Identitetsisolering.
API:er för metadata tables(), columns(), primaryKeys(), foreignKeys(), statistics(), rowIdColumns(), rowVerColumns(), och procedures()getTypeInfo().
Kodning och konverterare Standardbredteckenkodning, utkonverterare och kollationsmedvetna icke-Unicode-parametrar, inklusive UTF-8 och äldre SQL-sort-ID-kollationer. Anpassad avkodning av smaltecken måste matcha klientens kodsida. Mer information finns i Kända problem.

Integrerad autentisering i Microsoft Entra ID använder det inloggade Windows-kontot på Windows. På Linux och macOS använder den en Kerberos-biljett för att autentisera sig mot tenantens Active Directory Federation Services (ADFS)-slutpunkt (AD FS). För förkunskapskrav, se Windows Integrated authentication.

Att stänga en arrow_reader() gör att SQLCancel skickas för att avbryta en pågående hämtning. Nära ögat väntar på att avbokningsrensningen ska bli klar. För mer information, se Apache Arrow-integration.

Datatyper

Drivrutinen returnerar xml-, json- och vektorvärden som Python strobjekt, där vektor representeras som en JavaScript Object Notation (JSON)-array. Den returnerar vanliga språk-runtime (CLR)-typer såsom geometri, geografi och hierarchyid som Python-bytesobjekt. För mer information, se Datatypmappningar och Kända problem.

Kända problem

Kontrollera dessa skillnader innan du flyttar en arbetsbelastning från msodbcsql18.

Issue Details Workaround
Microsoft Entra ID-lösenordsautentisering Authentication=ActiveDirectoryPassword stöds inte. Denna metod kan inte användas för multifaktorautentisering (MFA). SQL-autentisering (UID / PWD) påverkas inte. Använd en annan Microsoft Entra ID-metod, såsom en service principal, hanterad identitet eller åtkomsttoken.
attrs_before inställningar Microsoft Entra ID-autentiseringsläge och applikationsintention kan inte ställas in som numeriska anslutningsattribut. Använd nyckelorden ApplicationIntent och Authentication för anslutningssträngen.
Tidsgräns för anslutningsåtgärd SQL_ATTR_CONNECTION_TIMEOUT-kontroller för rensning vid avbrytning. Den tillämpar inte någon timeout vid återställning av poolad anslutning. En anslutningsförfrågan kan förbli blockerad om servern slutar svara under återställningen. Ingen timeout för poolåterställning är tillgänglig. Ange connect(timeout=...) för inloggning och Connection.timeout för kontoutdrag.
Värdar med flera adresser msodbcsql18 aktiverar Transparent Network IP Resolution (TNIR) som standard; mssql-odbc stöder det inte. mssql-python avvisar TransparentNetworkIPResolution nyckelordet connection-string med endera leverantören. Använd MultiSubnetFailover=yes för availability group listeners och andra värdar med flera adresser. För standardinställningar, se Standardinställningar för redundansväxling i flera undernät.
Dataklassificering Metadata för känslighetsklassificering är inte tillgänglig, och SQL_COPT_SS_DATACLASSIFICATION_VERSION (1400) stöds inte. Fråga sys.sensitivity_classifications.
fork() efter att du har anslutit På Linux kan en process som förgrenas efter att föräldern ansluter hänga sig när den använder drivrutinen, även med en ny anslutning. Med pooling aktiverat kan den överordnade processen också hänga. (#566) Använd spawn startmetoden och anslut inuti varje worker.
Inbyggd spårning på Linux Med inbyggd spårning aktiverad kan Python avbryta under drivrutinsrensning vid processavslutning. Lämna MSSQL_TDS_TRACE oinställt på Linux.
Olästa resultat Att stänga en markör eller köra en annan instruktion läser och kasserar återstående resultat istället för att avbryta dem, vilket kan gå långsamt. Rensning av prepared statements använder statementets frågetimeout, men en timeout på noll lämnar den rensningen obegränsad. Hämta bara de rader du behöver, till exempel med TOP, och sätt Connection.timeout innan du skapar markören.
Anpassad avkodning av narrow characters Den inbyggda drivrutinen använder Windows ANSI-kodsida på Windows och processlokalkodsidan på Linux och macOS för smala teckensträngar. En explicit Python-avkodning som inte matchar den kodsidan kan ge felaktig text eller bytes. Använd standardavkodningen för breda tecken: conn.setdecoding(mssql_python.SQL_CHAR).
Connection.getinfo() Vissa kapabilitetsvärden och paketstorleksbaserade gränser skiljer sig från msodbcsql18. SQL_USER_NAME rapporterar databasprincipal snarare än anslutningssträngen UID. Hämta den specifika serverns metadata när en rapporterad kapacitet eller gräns är relevant för din applikation.
Slut på minne-fel Vissa misslyckanden med drivrutinsallokering avslutar Python-processen istället för att utlösa MemoryError. (#484) Begränsa storleken på värden du skickar och hämtar.
Läsprestanda för stora värden Chunkade läsningar av varchar(max) och nvarchar(max) -data kan vara långsammare än med msodbcsql18. (#473) Utvärdera din arbetsbelastning.

Rapportera ett problem

Om du stöter på en bugg, återskapa den med msodbcsql18 och notera om den uppstår hos båda leverantörerna. Anvisningar för att byta finns i Aktivera drivrutinen.

Inkludera utdata från mssql_python.get_native_provider_info(), ditt operativsystem, Python- och drivrutinsversioner, samt den misslyckade T-SQL-batchen och felmeddelandet i din rapport:

På Windows, ställ in dessa variabler i PowerShell innan du startar Python för att samla in diagnostik från native-drivers. Återskapa problemet med mssql-odbc valt:

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

MSSQL_TDS_TRACE möjliggör spårning, MSSQL_TDS_TRACE_LEVEL väljer loggnivån och MSSQL_TDS_TRACE_DIR väljer katalogen för spårningsfiler per process från den inbyggda ODBC-drivrutinen istället för standardfelutdata. Rust-tilläggspaketet skapar också loggfiler under mssql_python_logs i den aktuella katalogen.

Spår kan innehålla T-SQL-text och parametervärden. Maskera känsliga data innan du delar utdrag. Efter diagnosen, ta bort dessa variabler och starta om Python för att inaktivera spårning.

Relaterat innehåll

  • Uppdaterades senast