Verwenden Sie den mssql-odbc-Treiber (Vorschau)

mssql-python lädt einen von zwei nativen ODBC-Anbietern:

Provider Description Status
msodbcsql18 Microsoft ODBC-Treiber 18 für SQL Server Standard
mssql-odbc Rust-basierter ODBC-Treiber Vorschau, Opt-in

Das mssql-python-rs0.4.0-Paket beinhaltet den mssql-odbc Provider.

Note

Verwenden Sie msodbcsql18 für Produktionsworkloads. Bevor Sie dem Vorschauanbieter mssql-odbc zustimmen, überprüfen Sie die bekannten Probleme.

Availability

Der Treiber wird im Paket mssql-python-rs als vorgefertigte Wheels für CPython 3.10 und spätere Versionen geliefert:

Platform Architekturen
Windows x64; ARM64 auf CPython 3.11 und späteren Versionen
macOS Universal2 (x86_64 und arm64), macOS 15 und spätere Versionen
Linux (glibc) x86_64 und aarch64 (manylinux_2_28 und manylinux_2_34)
Linux (musl) x86_64 und aarch64 (musllinux_1_2)

Treiber aktivieren

Die Installation von mssql-python installiert auch mssql-python-rs, das den Treiber mssql-odbc enthält:

python -m pip install mssql-python

Wenn du mit --no-deps oder von einem privaten Index installierst, installiere auch mssql-python-rs explizit.

Wählen Sie den Anbieter aus, bevor Sie die erste Verbindung öffnen. Verwenden Sie eine der folgenden Methoden.

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

Legen Sie die MSSQL_CONNECTION_STRING Umgebungsvariable auf die Verbindungszeichenfolge Ihrer Anwendung fest. Zertifikatsvalidierung aktiviert lassen (Encrypt=yes;TrustServerCertificate=no). Weitere Informationen finden Sie unter Verbindungszeichenfolge und Verschlüsselung und Zertifikate.

Führe dieses Beispiel mit deinem ausgewählten Anbieter durch:

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

Das Beispiel druckt 1.

Die Auswahl des Anbieters folgt folgenden Regeln:

  • MSSQL_PYTHON_NATIVE_PROVIDER hat Vorrang vor native_provider. Das Setzen des Attributs auf einen widersprüchlichen Anbieter erzeugt RuntimeWarning.
  • Bevor der Treiber geladen wird, setzen Sie native_provider auf None, um die Python-Einstellung zu löschen. Dadurch wird die Umgebungsvariable nicht gelöscht.
  • Ein nicht anerkannter Anbietername löst ValueError aus. Die Zuweisung eines ungültigen Namens für native_provider löst sofort einen Fehler aus; eine ungültige Umgebungsvariable führt beim Verbinden zu einem Fehler. Der Treiber greift nicht auf den Standardanbieter zurück.
  • Der Anbieter ist festgelegt, wenn der Treiber einen nativen Verbindungsversuch startet, selbst wenn dieser Versuch fehlschlägt. Starte Python neu, um den Provider zu wechseln. Der Wechsel von native_provider zu einem anderen Anbieter gibt RuntimeWarning aus und hat keine Wirkung.

Fehler bei der Validierung von Verbindungsstrings und fehlende Provider-Pakete treten bereits vor diesem Punkt auf. Sie können diese Fehler korrigieren und einen anderen Anbieter wählen, ohne neu starten zu müssen.

Rufen Sie mssql_python.get_native_provider_info() an, um den Namen des Anbieters zu überprüfen, wie dieser ausgewählt wurde und ob die Auswahl festgelegt ist.

Um zu msodbcsql18 zurückzukehren, entfernen Sie MSSQL_PYTHON_NATIVE_PROVIDER und jede beliebige native_provider Zuweisung aus Ihrer Anwendung, und starten Sie dann Python neu.

Multi-Subnet-Failover-Standardeinstellungen

Der Rust-Anbieter aktiviert MultiSubnetFailover standardmäßig für entsprechende Transmission Control Protocol (TCP)-Verbindungen. Setzen Sie MultiSubnetFailover=no explizit, um sequentielle Verbindungsversuche anzufordern. Um den deployment-weiten Standard zu ändern, setzen MSSQL_RS_MULTISUBNET_FAILOVER_DEFAULT Sie auf true oder false bevor der native Treiber erstmals verwendet wird. Das Schlüsselwort der Verbindungszeichenfolge überschreibt diesen Standard.

Das numerische SQL_COPT_SS_MULTISUBNET_FAILOVER Attribut (1248) überschreibt ebenfalls das Keyword, wenn es vor der Verbindung gesetzt wird.

Der Treiber aktiviert diesen Standard nicht für Nicht-TCP-Transporte, Datenbankspiegelung, benannte Instanzen, die eine SQL Server Browser-Entdeckung erfordern, oder lokale Windows-Verbindungen, die ein explizites Protokoll und eine Adresse weglassen. Das explizite Aktivieren von MultiSubnetFailover für einen Nicht-TCP-Transport, die Datenbankspiegelung oder die Erkennung durch SQL Server Browser führt zu einem Verbindungsfehler. Weitere Informationen finden Sie unter Hohe Verfügbarkeit und Failover.

Unterstützte Funktionen

Die folgenden Funktionen werden unterstützt, vorbehaltlich der bekannten Probleme.

Area Notes
Verbindungslebenszyklus Verbinden, close(), with Blocks, Anmelde-Timeout, Diagnostik und Änderung der aktuellen Datenbank. Verbindungszeichenfolgeeinstellungen umfassen ApplicationIntent, MultiSubnetFailover, IpAddressPreference, PacketSize, KeepAlive und ConnectRetryCount / ConnectRetryInterval (Leerlaufverbindungsresilienz). Der native Treiber verhandelt außerdem serverunterstütztes Domain Name System (DNS)-Caching und verbessertes Routing, wenn der Server dies unterstützt.
Authentication SQL-Authentifizierung (UID / PWD); Windows-Authentifizierung (Trusted_Connection=Yes, unter Verwendung von Security Support Provider Interface (SSPI) unter Windows oder Kerberos unter Linux und macOS); und Microsoft Entra ID interaktive, integrierte, Gerätecode-, Dienstprinzipal-, verwaltete Identitäts-, Standardanmeldeinformations- und Zugriffstoken-Authentifizierung. Die Passwortauthentifizierung mit Microsoft Entra ID wird nicht unterstützt. Weitere Informationen finden Sie unter Bekannte Probleme.
Transport Layer Security (TLS) (Transportschichtsicherheit) Encrypt, TrustServerCertificate, HostnameInCertificate und ServerCertificate.
Abfrageausführung Direkte und vorbereitete Ausführung, Wiederverwendung von vorbereiteten Plänen, qmark-Parameter und die pyformat-Konvertierung, die mssql-python durchführt.
ODBC-Escapesyntax Funktions-, Datum-/Uhrzeit-, Outer-Join, global eindeutige Kennung (GUID), LIKE ... {escape ...}, Intervall- und {encrypt ...} Escape-Formen.
Gespeicherte Prozeduren Rufen Sie sie mit Transact-SQL (T-SQL) oder positionsbezogener {call ...} Syntax über execute(), lesen Sie Ergebnismengen und fahren Sie mit nextset()fort.
Eingabeparameter Skalare Parameter, SQL NULL, setinputsizes(), und gemischte reguläre/gestreamte Parameter.
Große Parameter Die Parameter großer Text, binär, Extensible Markup Language (XML) und benutzerdefinierte Typen (UDT) unterstützen Data-at-Execution-Streaming.
executemany() Gebündelt mit ODBC-Parameterarrays. Zeilen, die gestreamte Werte enthalten, greifen auf Zeilen-für-Zeilen-Ausführung zurück.
Zeilenabruf fetchone(), fetchmany(), fetchall(), Iteration, fetchval(), typisierte Konvertierung und großes Text-/Binär-Streaming.
Pfeil abrufen arrow_batch(), arrow()und arrow_reader(). Erfordert pyarrow.
Mehrere Ergebnismengen nextset(), einschließlich Ergebnissen, die von Parameterarrays erzeugt werden.
Transactions Autocommit, Commit, Rollback sowie die Read-Uncommitted, read-Committed, Repeatable-Read, Serializable und Snapshot Isolation-Level. Ohne Autocommit führt der Verbindungskontextmanager bei erfolgreichem Beenden ein Commit aus und rollt bei einer Ausnahme zurück.
Zeitüberschreitung bei der Abfrage Setze Connection.timeout in Sekunden vor dem Erstellen eines Cursors. Wenn eine Anweisung diese Zeitbegrenzung überschreitet, löst der Treiber OperationalError aus. 0 bedeutet kein Timeout. Setze den Login-Timeout separat mit connect(timeout=...) fest.
Verbindungspooling Der integrierte mssql-python-Pool, einschließlich Verbindungszurücksetzung vor der Wiederverwendung. Für authentifizierungsspezifische Pool-Isolation siehe Identitätsisolation.
Metadaten-APIs tables(), columns(), primaryKeys(), foreignKeys(), statistics(), rowIdColumns(), , rowVerColumns(), procedures()und getTypeInfo().
Kodierung und Konverter Standardmäßiges Wide-Character-Encoding, Ausgabekonverter und Nicht-Unicode-Parameter mit Sortierungserkennung, einschließlich UTF-8 und älterer SQL-Sort-ID-Sortierungen. Die benutzerdefinierte Schmalzeichendekodierung muss mit der Codepage des Client übereinstimmen. Weitere Informationen finden Sie unter Bekannte Probleme.

Die integrierte Authentifizierung von Microsoft Entra ID verwendet das angemeldete Windows-Konto auf Windows. Unter Linux und macOS verwendet es ein Kerberos-Ticket, um sich beim Active Directory-Verbunddienste (AD FS) (AD FS)-Endpunkt des Mandanten zu authentifizieren. Voraussetzungen finden Sie unter Windows-integrierte Authentifizierung.

Das Schließen von arrow_reader() sendet SQLCancel, um einen laufenden Abruf zu unterbrechen. Der Schließaufruf wartet, bis die Bereinigung nach dem Abbruch abgeschlossen ist. Weitere Informationen finden Sie unter Apache Arrow Integration.

Datentypen

Der Treiber liefert XML-, JSON- und Vektorwerte als Python-Objektestr, wobei der Vektor als JavaScript Object Notation (JSON)-Array dargestellt wird. Es gibt Common Language Runtime (CLR)-Typen wie geometry, geography und hierarchyid als Python-Objekte bytes zurück. Weitere Informationen finden Sie unter Datentypabbildungen und bekannte Probleme.

Bekannte Probleme

Sehen Sie sich diese Unterschiede an, bevor Sie eine Workload von msodbcsql18 wechseln.

Issue Details Workaround
Microsoft Entra ID Passwortauthentifizierung Authentication=ActiveDirectoryPassword wird nicht unterstützt. Diese Methode kann keine Multi-Factor Authentication erfüllen. SQL-Authentifizierung (UID / PWD) bleibt unbeeinträchtigt. Verwenden Sie eine weitere Microsoft Entra ID-Methode, wie einen Service Principal, eine verwaltete Identität oder ein Zugriffstoken.
attrs_before Einstellungen Der Authentifizierungsmodus und die Anwendungsabsicht von Microsoft Entra ID können nicht als numerische Verbindungsattribute festgelegt werden. Verwenden Sie die Verbindungszeichenfolgen-Schlüsselwörter Authentication und ApplicationIntent.
Zeitüberschreitung beim Verbindungsvorgang SQL_ATTR_CONNECTION_TIMEOUT steuert die Bereinigung bei Abbruch. Es erzwingt keinen Timeout beim Zurücksetzen der Pool-Verbindung. Eine Verbindungsanfrage kann blockiert bleiben, wenn der Server während des Zurücksetzens nicht mehr reagiert. Es ist kein Pool-Reset-Timeout verfügbar. Für Login Connection.timeout und für Statements connect(timeout=...) festlegen.
Mehradress-Hosts msodbcsql18 aktiviert standardmäßig Transparent Network IP Resolution (TNIR); mssql-odbc unterstützt sie nicht. mssql-python lehnt das TransparentNetworkIPResolution connection-string-Schlüsselwort bei beiden Anbietern ab. Verwenden Sie MultiSubnetFailover=yes für Verfügbarkeitsgruppen-Listener und andere Hosts mit mehreren Adressen. Für Standardwerte, siehe Standardwerte für Multi-Subnet-Failover.
Datenklassifizierung Metadaten zur Sensitivitätsklassifikation sind nicht verfügbar, und SQL_COPT_SS_DATACLASSIFICATION_VERSION (1400) wird nicht unterstützt. Abfrage sys.sensitivity_classifications.
fork() nach dem Anschließen Unter Linux kann ein Prozess, der geforkt wird, nachdem sich der übergeordnete Prozess verbunden hat, hängen bleiben, wenn er den Treiber verwendet, selbst bei einer neuen Verbindung. Mit aktiviertem Pooling kann auch der übergeordnete Prozess hängen bleiben. (#566) Verwenden Sie die spawn Startmethode und stellen Sie in jedem Worker die Verbindung her.
Native Ablaufverfolgung unter Linux Mit aktiviertem native Tracing kann Python während der Treiberreinigung beim Prozessende abbrechen. Lassen Sie MSSQL_TDS_TRACE unter Linux nicht festgelegt.
Ungelesene Ergebnisse Das Schließen eines Cursors oder das Ausführen einer anderen Anweisung liest und verwirft die verbleibenden Ergebnisse, anstatt sie abzubrechen, was langsam sein kann. Prepared-Statement-Cleanup nutzt das Abfrage-Timeout des Statements, aber ein Timeout von null lässt diese Cleanup unbeschränkt. Hol nur die benötigten Zeilen, zum Beispiel mit TOP, und lege Connection.timeout fest, bevor du den Cursor erstellst.
Benutzerdefinierte Schmalzeichendekodierung Der native Treiber verwendet die Windows-ANSI-Codepage unter Windows und die Codepage des Prozessgebietsschemas unter Linux und macOS für Schmaltext. Eine explizite Python-Dekodierung, die nicht mit dieser Codepage übereinstimmt, kann falschen Text oder bytes erzeugen. Verwenden Sie die Standard-Breitzeichen-Dekodierung: conn.setdecoding(mssql_python.SQL_CHAR).
Connection.getinfo() Einige Fähigkeitswerte und paketgrößenbasierte Grenzen unterscheiden sich von msodbcsql18. SQL_USER_NAME meldet den Datenbankprinzipal statt der Verbindungszeichenfolge UID. Abfragen Sie die spezifischen Servermetadaten, wenn eine gemeldete Fähigkeit oder ein Limit für Ihre Anwendung relevant ist.
Speichermangelfehler Einige Fehler bei der Treiberallokation beenden den Python-Prozess, anstatt MemoryError auszulösen. (#484) Begrenze die Größe der Werte, die du sendst und abrufst.
Leseleistung bei großen Werten Chunked Reads von varchar(max) und nvarchar(max) -Daten können langsamer sein als mit msodbcsql18. (#473) Bewerten Sie Ihre Workload.

Probleme melden

Wenn Sie auf einen Fehler stoßen, reproduzieren Sie ihn mit msodbcsql18 und notieren Sie, ob er bei beiden Anbietern auftritt. Für Anweisungen zum Wechseln, siehe Treiber aktivieren.

Fügen Sie die Ausgabe von mssql_python.get_native_provider_info(), Ihr Betriebssystem, Python- und Treiberversionen sowie das fehlerhafte T-SQL-Batch und die Fehlermeldung in Ihren Bericht ein:

Unter Windows setzen Sie diese Variablen in PowerShell, bevor Sie Python starten, um native-Treiber-Diagnosen zu sammeln. Reproduzieren Sie das Problem bei ausgewähltem mssql-odbc:

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

MSSQL_TDS_TRACE ermöglicht das Nachverfolgen, MSSQL_TDS_TRACE_LEVEL wählt die Log-Ebene aus, und MSSQL_TDS_TRACE_DIR wählt das Verzeichnis für prozessbezogene Trace-Dateien des nativen ODBC-Treibers anstelle der Standardfehlerausgabe aus. Das Rust-Begleitpaket erstellt außerdem Logdateien unter mssql_python_logs im aktuellen Verzeichnis.

Traces können T-SQL-Text- und Parameterwerte enthalten. Schwärzen Sie sensible Daten vor dem Teilen von Auszügen. Nach der Diagnose entfernen Sie diese Variablen und starten Sie Python neu, um das Tracing zu deaktivieren.

Verwandte Inhalte

  • Zuletzt aktualisiert um