Verwendung des mssql-odbc-Treibers (Vorschau)

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

Provider Was es ist Status
msodbcsql18 Microsoft ODBC Driver 18 für SQL Server, der etablierte C++-Treiber Standard, unverändert
mssql-odbc Ein neuer ODBC-Treiber, geschrieben in Rust Vorschau, Opt-in

Dieser Artikel behandelt mssql-odbc0.3.0, die derzeit von mssql-python, verwendete Version, und was sich von msodbcsql18unterscheidet.

Note

mssql-odbc befindet sich in aktiver Entwicklung und Validierung. Es ist noch kein vollständiger Ersatz für Microsoft ODBC Driver 18. Behalte msodbcsql18 vorerst als Produktionsstandard bei. Das Entwicklungsteam plant, die Vorschaulücken in kommenden Veröffentlichungen zu schließen, abgesehen von absichtlich in diesem Artikel explizit genannten Ausnahmen.

Availability

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

Platform Architekturen
Windows x64; ARM64 auf CPython 3.11+
macOS Universal2 (x86_64 + arm64), macOS 15 oder neuer
Linux (glibc) x86_64, aarch64 – manylinux_2_28 und manylinux_2_34
Linux (musl) x86_64, aarch64 — musllinux_1_2

Treiber aktivieren

Das Paket mssql-python hängt von mssql-python-rsab, daher bringt eine normale Installation den Rust-Treiber mit:

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 vor der ersten Verbindung aus, entweder mit einer Umgebungsvariable:

Powershell:

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

Bash oder Zsh:

export MSSQL_PYTHON_NATIVE_PROVIDER=mssql-odbc

oder aus Python:

import mssql_python

mssql_python.native_provider = "mssql-odbc"

Verbinden Sie sich, indem Sie die bestehende Verbindungszeichenfolge Ihrer Anwendung verwenden. Zertifikatsvalidierung aktiviert lassen (Encrypt=yes;TrustServerCertificate=no). Für Authentifizierung und Zertifikatseinrichtung siehe Verbindungszeichenfolgen und Verschlüsselung und Zertifikate.

connection = mssql_python.connect(connection_string)

Der Treiber wendet bei der Auswahl des Anbieters folgende Regeln an:

  • Die Umgebungsvariable MSSQL_PYTHON_NATIVE_PROVIDER hat Vorrang vor native_provider. Eine widersprüchliche Attributzuweisung erzeugt RuntimeWarning.
  • Die Auswahl wird nach der Validierung des Verbindungsstrings und unmittelbar vor dem Aufbau der nativen Verbindung festgelegt. Ein anschließender Verbindungsfehler hebt die Auswahl nicht auf. Ein früherer Fehler beim Parsing von Verbindungszeichenfolgen oder ein fehlendes Provider-Paket behebt das Auswahlproblem nicht. Nachdem die Auswahl festgelegt ist, bewirkt ein Wechsel von RuntimeWarning zu einem anderen Anbieter native_provider und hat keine Wirkung mehr. Starten Sie den Prozess neu, um den Anbieter zu wechseln.
  • Ein nicht anerkannter Anbietername löst ValueError aus; der Treiber fällt nicht auf den Standardanbieter zurück. Ein unbekannter Name, der native_provider zugewiesen wird, löst sofort einen Fehler aus. Ein unbekannter Name in der Umgebungsvariable löst einen Fehler aus, wenn du versuchst, eine Verbindung herzustellen.
  • Setze native_provider auf None, um die Attributauswahl zu löschen, bevor sie fixiert wird. Die Umgebungsvariable hat weiterhin Vorrang.

Rufen Sie mssql_python.get_native_provider_info() auf, um den ausgewählten Anbieter, die Auswahlquelle und ob die Auswahl festgelegt ist, zu überprüfen. Vor der Verbindung wird die Auswahl angezeigt, nicht der Beweis, dass der native Treiber erfolgreich geladen wurde.

Um zurückzugehen, setze die Variable auf msodbcsql18, oder deaktiviere sie und entferne jede native_provider Zuweisung aus deinem Code (oder setze sie auf "msodbcsql18"). Dann starte den Prozess neu.

Was heute funktioniert

Der Treiber mssql-odbc implementiert jede ODBC-Funktion, die mssql-python aufruft, sodass die meisten Anwendungen ohne Codeänderungen den Provider wechseln können. Überprüfen Sie Bekannte Probleme auf die verbleibenden Unterschiede.

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).
Authentication SQL-Authentifizierung (UID / PWD); Windows-Authentifizierung (Trusted_Connection=Yes, unter Verwendung von SSPI unter Windows oder Kerberos unter Linux und macOS); sowie Microsoft Entra interaktiv, Gerätecode, Service Principal, verwaltete Identität, Standardzugangsdaten und Zugriffstoken. Entra-Integration und Kennwortauthentifizierung werden nicht unterstützt; siehe Bekannte Probleme.
TLS Encrypt, TrustServerCertificate, HostnameInCertificate und ServerCertificate.
Abfrageausführung Direkte und vorbereitete Ausführung, Wiederverwendung von vorbereiteten Plänen, qmark Parameter und die von mssql-python durchgeführte pyformat Konvertierung.
ODBC-Escapesyntax Funktion, Datum/Uhrzeit, Outer-Join, GUID, LIKE ... {escape ...}, Intervall und {encrypt ...}-Escape-Formen.
Gespeicherte Prozeduren Rufen Sie sie mit T-SQL oder positionsbezogener {call ...} Syntax über execute() auf, lesen Sie Ergebnismengen und fahren Sie mit nextset() fort.
Eingabeparameter Skalare Parameter, SQL NULL, setinputsizes(), und gemischte reguläre/gestreamte Parameter.
Große Parameter Große Text- und Binärparameter strömen auf dem gewöhnlichen Bindungspfad an den Server; XML- und UDT-Parameterbeschränkungen sind unten aufgeführt.
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, das automatische Commit (oder Rollback, falls ein Fehler nicht abgefangen wurde), das auftritt, wenn ein with connect(...) Block endet, sowie die Read-Uncommitted-, Read-Committed-, Repeatable-Read-, Serializable- und Snapshot-Isolationsstufen.
Zeitüberschreitung bei der Abfrage Setzen Sie Connection.timeout (in Sekunden) so fest, dass die von den Cursorn dieser Verbindung ausgeführten Anweisungen begrenzt werden; bei Ablauf wird OperationalError ausgelöst. 0 bedeutet kein Timeout. Diese Einstellung ist separat von der Login-Zeitüberschreitung, die als connect(timeout=...) übergeben wird.
Verbindungspooling Der integrierte mssql-python Pool, einschließlich der Verbindungszurücksetzung beim Checkout und separaten Pools gemäß Microsoft Entra-Identität.
Metadaten-APIs tables(), columns(), primaryKeys(), foreignKeys(), statistics(), rowIdColumns(), , rowVerColumns(), procedures()und getTypeInfo().
Kodierung und Converter Standardmäßige Wide-Character-Kodierung und Ausgabekonverter. Benutzerdefinierte schmale Zeichendekodierung und Nicht-Unicode-Parameterkonvertierung haben Einschränkungen, die in Bekannte Probleme aufgeführt sind.

Datentypen

Man kann alle SQL Server-Datentypen lesen, und der Treiber unterstützt jeden Parametertyp, den mssql-python bindet. Der Treiber liefert die Werte xml, json und vector als str (vector als JSON-Array) sowie CLR-Typen wie geometry, geography und hierarchyid als bytes. Für andere Python-Mappings siehe Data Type Mappings. Typspezifische Einschränkungen finden Sie unter Bekannte Probleme.

Bekannte Probleme

Überprüfen Sie diese Unterschiede, bevor Sie die Arbeitslast von msodbcsql18 umstellen.

Issue Details Workaround
Integrierte Microsoft Entra-Authentifizierung Authentication=ActiveDirectoryIntegrated wird nicht unterstützt. Die Windows-Authentifizierung (Trusted_Connection=Yes) bleibt unbeeinträchtigt. Verwenden Sie eine andere Microsoft Entra-Methode, oder behalten Sie msodbcsql18.
Microsoft Entra Kennwort-Authentifizierung Authentication=ActiveDirectoryPassword wird nicht unterstützt, und Unterstützung ist nicht geplant, weil diese Methode MFA nicht erfüllen kann. SQL-Authentifizierung (UID / PWD) bleibt unbeeinträchtigt. Verwenden Sie eine weitere Microsoft Entra-Methode, wie einen Service Principal, eine verwaltete Identität oder ein Zugriffstoken.
attrs_before Einstellungen Authentifizierung, Anwendungsabsicht und Multi-Subnet-Failover können nicht als numerische Attribute festgelegt werden. Anweisungsattribute außer dem Abfrage-Timeout werden abgelehnt. Verwenden Sie die entsprechenden Schlüsselwörter für die Verbindungszeichenfolge.
Zeitüberschreitung beim Verbindungsvorgang set_attr(SQL_ATTR_CONNECTION_TIMEOUT, ...) akzeptiert und speichert den Wert, erzwingt aber in 0.3.0 kein Timeout. Verwenden Sie connect(timeout=...) für Login und Connection.timeout für Statements; keines von beiden ist eine allgemeine Verbindungs-Operation-Deadline.
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. Ohne MultiSubnetFailover=Yes, werden Adressen einzeln ausprobiert, sodass eine nicht erreichbare Adresse die Verbindung verzögern kann. Serverunterstütztes DNS-Caching und verbessertes Routing werden nicht vereinbart. MultiSubnetFailover=Yes für Verfügbarkeitsgruppen-Listener und andere Multi-Adress-Hosts festlegen.
Vorübergehende DNS-Ausfälle Wenn eine DNS-Abfrage fehlschlägt, fällt der Treiber nicht auf die zuletzt erfolgreiche Adresse zurück. (#457) Wiederholen Sie die Verbindung.
Datenklassifizierung Metadaten zur Sensitivitätsklassifikation sind nicht verfügbar und SQL_COPT_SS_DATACLASSIFICATION_VERSION (1400) wird nicht unterstützt. Abfrage sys.sensitivity_classifications.
Multithreading Multithreaded-Nutzung wurde nicht validiert. Behalte msodbcsql18 für Multithreaded-Workloads.
fork() nach dem Anschließen Unter Linux kann ein Prozess, der geforkt wird, nachdem sich der Elternprozess verbunden hat, hängen, wenn er den Treiber verwendet, selbst bei einer neuen Verbindung. Mit aktiviertem Pooling kann auch der übergeordnete Prozess hängen. (#566) Verwenden Sie die spawn Startmethode und stellen Sie in jedem Worker die Verbindung her.
Abbrechen einer laufenden Abfrage Eine laufende Abfrage oder Fetch kann nicht unterbrochen werden. Zum Beispiel stoppt das Schließen von arrow_reader() nicht einen laufenden Lesevorgang in einem anderen Thread. Verwenden Sie Connection.timeout, um langlaufende Statements zu begrenzen.
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. Das Schließen eines Cursors, der eine vorbereitete Anweisung verwendet hat, ignoriert Connection.timeout und kann hängen, wenn der Server nicht mehr reagiert. (#546) Rufen Sie nur die benötigten Zeilen ab, zum Beispiel mit TOP.
Große xml und UDT-Parameter Werte, die als SQL_SS_XML oder SQL_SS_UDT durch setinputsizes() gebunden sind, werden im Speicher gepuffert statt gestreamt. Binde xml Werte als gewöhnliche Zeichenfolgen.
Leere imageWerte Ein leerer, nicht-NULL SQL Server-Wert image wird als b"" anstelle von None zurückgegeben. Lies CAST(image_column AS varbinary(max)), oder benutze msodbcsql18 , wenn die Unterscheidung zwischen Leere und NULL relevant ist.
Parameter für Nicht-Unicode-Zeichenfolgen Zeichenketten, die an char / varchar bis setinputsizes() gebunden sind, können für Codepage 437, Codepage 850 und UTF-8-Kollationen falsch codiert werden. Benutze die Standard-Zeichenfolgenbindung.
Legacy-Codepage-Dekodierung unter Windows Mit setdecoding(SQL_CHAR, encoding="cp1252") oder einer anderen alten Codepage kann Text falsch decodiert oder als bytes zurückgegeben werden, da der Treiber / charvarchar-Daten als UTF-8 zurückgibt. Verwenden Sie die Standardwahl: conn.setdecoding(mssql_python.SQL_CHAR).
Connection.getinfo() SQL_USER_NAME gibt die Verbindungszeichenkette UIDzurück, nicht den Datenbankbenutzer. Es ist leer, wenn kein UID den Treiber erreicht. Einige Fähigkeitswerte und paketgrößenbasierte Grenzen unterscheiden sich von msodbcsql18. Verwenden Sie SELECT USER_NAME() für den Datenbankbenutzer.
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.
Lesleistung bei großen Werten In einem Benchmark waren die Chunk-Reads der varchar(max) / nvarchar(max) Daten etwas langsamer als mit msodbcsql18. (#473) Bewerte deine Arbeitslast.

Diese Liste ist nicht vollständig.

Melden von Problemen

Wenn Sie auf einen Fehler stoßen, wählen Sie msodbcsql18, starten Sie den Prozess neu und prüfen Sie, ob das Verhalten weiterhin auftritt. Entferne außerdem alle widersprüchlichen Python-seitigen Provider-Zuweisungen. Der Vergleich hilft, das Problem zu isolieren; er beweist für sich genommen nicht dessen Ursache. Fügen Sie die Ausgabe von mssql_python.get_native_provider_info(), Ihre Plattform und die fehlerhafte SQL- oder Fehlermeldung hinzu:

Für Rust-Treiber-Diagnostik setzen Sie diese Variablen vor dem Start von Python und reproduzieren Sie das Problem mit ausgewähltem mssql-odbc. Beispiel in PowerShell:

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

MSSQL_TDS_TRACE aktiviert die Nachverfolgung, MSSQL_TDS_TRACE_LEVEL wählt den Log-Filter aus und MSSQL_TDS_TRACE_DIR schreibt Dateien pro Prozess statt stderr. Starte Python neu, nachdem du diese Einstellungen geändert hast. Traces können SQL-Text und Parameterwerte enthalten. Überprüfen und schwärzen Sie sensible Daten, bevor Sie relevante Auszüge teilen, und deaktivieren Sie das Nachverfolgen nach der Diagnose.

Verwandte Inhalte

  • Zuletzt aktualisiert um