Wählen Sie den Datenbanktreiber für mssql-django aus

Ab Version 2.0 verbindet sich mssql-django über einen von zwei Python-Datenbanktreibern:

• pyodbc mit einem extern installierten Microsoft ODBC-Treiber für SQL Server. Dieser Treiber ist der Standardtreiber.
• mssql-python, Microsoft's Python-Treiber, der keinen separat installierten ODBC-Treiber benötigt.

Du wählst den Treiber für jedes Datenbankalias. Ein Alias kann mssql-python verwenden, während der Rest des Projekts bei pyodbc bleibt. Der Wert ENGINE bleibt in beiden Fällen "mssql".

Ein Alias für mssql-python aktivieren

Setzen Sie die python_driver Option im Wörterbuch dieses Aliases OPTIONS :

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<database>",
        "USER": "<user_id>",
        "PASSWORD": "<password>",
        "HOST": "<server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "python_driver": "mssql_python",
            "extra_params": "Encrypt=yes",
        },
    },
}

Das Backend akzeptiert "mssql_python", "mssql-python", und "python", und der Vergleich ignoriert den Fall. Weglassen python_driver, es leer lassen oder so einstellen, dass "pyodbc" der Standardtreiber bleibt. Da die Einstellung per Alias ist, rollst du eine Datenbank nach dem anderen zurück, indem du die Option entfernst.

Das Modul mssql-python wird nur importiert, wenn ein Alias es auswählt. Wenn die installierte Version älter als 1.15.0 ist, gibt das Backend ImproperlyConfigured mit der erforderlichen Version aus.

Installationsanforderungen

pip install mssql-django installiert beide Treiber. Der Pfad mssql-python hat keine separate ODBC-Treiberinstallation. Eine --no-deps-Installation oder ein privater Index, der mssql-python nicht spiegelt, führt dazu, dass das Paket fehlt und der Alias beim Import fehlschlägt.

Installieren Sie die Plattformvoraussetzungen für mssql-python, einschließlich OpenSSL auf macOS und der erforderlichen Bibliotheken unter Linux.

Da mssql-python eine erforderliche Abhängigkeit ist, lässt sich mssql-django 2.0 nur auf Plattformen installieren, die über eine kompatible mssql-python-Distribution verfügen. Die Plattformliste finden Sie unter mssql-django Support und Lebenszyklus.

Unterschiede im Verhalten

Die beiden Treiber bauen unterschiedliche Verbindungsstrings auf und stellen unterschiedliche Verbindungsschlüsselwörter frei. Schau dir diesen Abschnitt an, bevor du ein Alias wechselst.

Verbindungseinstellungen

Timeouts, Wiederholungsversuche, Isolationslevel, Kollation und return_rows_bulk_insert verhalten sich in beiden Pfaden gleich.

Zusätzliche Verbindungsparameter

mssql-python 1.15 validiert extra_params gegen eine Erlaubnisliste und lehnt alles außerhalb davon ab. Unterstützte Schlüsselwörter umfassen ServerCertificate, ServerSPN, MultiSubnetFailover, ApplicationIntent, ConnectRetryCount, KeepAlive, KeepAliveInterval, ConnectRetryInterval, IpAddressPreference, PacketSize, HostnameInCertificate, TrustServerCertificate, Encrypt und Authentication.

Der Treiber lehnt DRIVER, DSN, SERVERNAME und MARS_Connection sowie ausschließlich von pyodbc verwendete Schlüsselwörter wie APP, LongAsMax, WSID, ColumnEncryption, AnsiNPW, UseFMTONLY, QuotedId, Current Language, Network Library, Regional, Description und Connect Timeout ab. Entferne diese Schlüsselwörter, bevor du ein Alias wechselst, und nutze die connection_timeout Option anstelle von Connect Timeout.

Wenn extra_params ein Schlüsselwort gesetzt wird, das auch vom Backend generiert wird, gewinnt der explizite Wert.

Multiple Active Result Sets (Mehrere aktive Resultsets)

Im pyodbc-Pfad fügt das Backend MARS_Connection=yes hinzu, wenn der Alias unter Windows einen Microsoft-ODBC-Treiber verwendet. Stattdessen wird ein expliziter MARS_Connection Wert in extra_params berücksichtigt, und das Match ignoriert den Fall.

Der Pfad mssql-python aktiviert MARS niemals und lehnt das Schlüsselwort MARS_Connection ab, sodass Sie MARS für dieses Alias nicht aktivieren können.

Ohne MARS QuerySet.iterator() liest sie das vollständige Ergebnis in den Speicher, bevor sie Zeilen liefert, sodass eine verschachtelte Abfrage die Verbindung wiederverwenden kann, und chunk_size ändert das nicht. Berücksichtigen Sie die Speicherkosten großer Abfragesätze.

Für Endpunkte, die MARS ablehnen, wie Microsoft Fabric Warehouse, siehe MARS deaktivieren.

Kodierungskonfiguration

Beide Treiber akzeptieren setencoding und setdecoding, und jeder Eintrag führt zur Verbindungsmethode des ausgewählten Treibers. Jeder setdecoding Eintrag benötigt auf beiden Pfaden einen sqltype Schlüssel, und derselbe Eintrag funktioniert auf beiden Treibern. Ein Unterschied: mssql-python akzeptiert -99 für SQL_WMETADATA, und pyodbc lehnt es ab.

Wählen Sie zwischen den Fahrern

Verwenden Sie für neue Entwicklungen mssql-python. Es entfernt den ODBC-Treiber-Installationsschritt aus Container-Images und App-Service-Deployments.

Verwenden pyodbc Sie, wenn Ihre Bereitstellung von einem benannten DSN, FreeTDS, Always Encrypted über das ColumnEncryption Schlüsselwort, einer ODBC-Treiberversion, die Sie selbst verwalten, oder MARS abhängt. Für das, was MARS auf jedem Pfad benötigt, siehe Multiple Active Result Sets.

Bestehende Projekte können bleiben.pyodbc Es bleibt der Standard und wird vollständig unterstützt. Wenn du die Umstellung tatsächlich vornimmst, wechsle jeweils nur einen Alias und lass deine Testsuite dagegen laufen, bevor du die übrigen umstellst.

Verwandte Inhalte

• Verbindungsoptionen für mssql-django
• mssql-django-Konfigurationsreferenz
• Verbindungs-Pooling in mssql-django
• Microsoft Entra Authentifizierung mit mssql-django
• mssql-python treiber für SQL Server