Verbindungsoptionen für mssql-django

In diesem Artikel werden die OPTIONS Wörterbucheinstellungen in Ihrer Django-Konfiguration DATABASES erläutert. Diese Einstellungen steuern, wie mssql-django eine Verbindung mit SQL Server über den ODBC-Treiber hergestellt wird.

ODBC-Treiberauswahl

mssql-django Ab 1.7 wird das Back-End standardmäßig auf ODBC-Treiber 18 für SQL Server festgelegt. Wenn ODBC-Treiber 18 nicht installiert ist, greift das Back-End automatisch auf ODBC-Treiber 17 zurück.

Note

ODBC-Treiber 18 aktiviert Encrypt=yes standardmäßig und überprüft das Serverzertifikat. Verbindungen, die mit Treiber 17 gearbeitet haben, können mit einem SSL/TLS-Vertrauensfehler fehlschlagen. So beheben Sie den Fehler:

Installieren Sie für lokale SQL Server ein Serverzertifikat von einer Zertifizierungsstelle, der Ihre Clients bereits vertrauen, oder importieren Sie das vorhandene Serverzertifikat in jeden Clientvertrauensspeicher. Anweisungen finden Sie unter Konfigurieren von SQL Server-Datenbank-Engine zum Verschlüsseln von Verbindungen.
Wenn Sie eine Verbindung über eine IP-Adresse oder einen Alias herstellen, der nicht mit dem Subjektnamen oder dem Subject Alternative Name (SAN) des Zertifikats übereinstimmt, fügen Sie HostNameInCertificate=<name-from-certificate> zu extra_params hinzu.

Informationen zur lokalen Entwicklung mit einem selbstsignierten Zertifikat finden Sie unter TrustServerCertificate im Abschnitt Zusätzliche ODBC-Parameter.

Sie können den Treiber explizit angeben:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 17 for SQL Server",
        },
    },
}

Unter Linux können Sie auch den vollständigen Pfad zur Treiberbibliothek angeben:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "/opt/microsoft/msodbcsql18/lib64/libmsodbcsql-18.0.so.1.1",
        },
    },
}

DSN vs HOST

Sie können eine Verbindung mit einem HOST Namen oder einem benannten DSN (Datenquellenname) herstellen.

Verbindung mit HOST herstellen

Die meisten Konfigurationen verwenden die HOST Einstellung direkt:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
        },
    },
}

Herstellen einer Verbindung mit DSN

Verwenden Sie einen benannten DSN, der in Ihren ODBC-Datenquellen konfiguriert ist:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "OPTIONS": {
            "dsn": "MyDataSourceName",
        },
    },
}

FreeTDS-Unterstützung

Wenn Sie FreeTDS als ODBC-Treiber verwenden möchten, setzen Sie host_is_server auf True. Dadurch wird dem Backend mitgeteilt, HOST und PORT direkt zu verwenden, anstatt in freetds.conf nach einem Datenservernamen zu suchen:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "FreeTDS",
            "host_is_server": True,
        },
    },
}

Weitere Informationen zu DSN-losen Verbindungen mit FreeTDS finden Sie im FreeTDS-Benutzerhandbuch.

Zusätzliche ODBC-Parameter

Verwenden Sie extra_params, um zusätzliche Parameter für die ODBC-Verbindungszeichenfolge zu übergeben. Der Wert ist eine durch Semikolons getrennte Zeichenfolge, die an die Verbindungszeichenfolge angefügt wird:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "TrustServerCertificate=yes;ApplicationIntent=ReadOnly",
        },
    },
}

Diese Einstellung wird auch für Microsoft Entra Authentifizierungstichwörter verwendet.

Vorsicht

Verwenden Sie TrustServerCertificate=yes nur für die lokale Entwicklung mit selbstsignierten Zertifikaten. Verwenden Sie sie nicht in der Produktion. Dadurch wird die Validierung der Zertifikatskette deaktiviert und das Risiko eines Man-in-the-Middle-Angriffs erhöht. Installieren Sie ein vertrauenswürdiges Zertifikat auf dem Server, und stellen Sie eine Verbindung mit TrustServerCertificate=no.

Verbindungstimeouts und Wiederholungen

Konfigurieren der Verbindungsresilienz mit Timeout- und Wiederholungseinstellungen:

Auswahl	Vorgabe	Description
`connection_timeout`	`0` (deaktiviert)	Maximale Anzahl an Sekunden, die auf eine Verbindung gewartet wird.
`connection_retries`	`5`	Anzahl der Wiederholungsversuche bei Verbindungsfehlern.
`connection_retry_backoff_time`	`5`	Wartezeit in Sekunden zwischen den Wiederholungsversuchen.
`query_timeout`	`0` (deaktiviert)	Maximale Anzahl von Sekunden, bis eine Abfrage abgeschlossen ist.

Beispiel:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "connection_timeout": 30,
            "connection_retries": 3,
            "connection_retry_backoff_time": 10,
            "query_timeout": 120,
        },
    },
}

Sortierung

Festlegen einer benutzerdefinierten Sortierung für Textfeld-Nachschlagevorgänge:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "collation": "Chinese_PRC_CI_AS",
        },
    },
}

Mehrere Datenbankverbindungen

Django unterstützt gleichzeitig eine Verbindung mit mehreren Datenbanken. Dies ist nützlich zum Lesen von Replikaten, datenbankübergreifenden Abfragen oder zum Trennen von Workloads nach Isolationsebene.

Konfigurieren mehrerer Datenbanken

Definieren Sie jede Verbindung in der DATABASES Einstellung:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "app_db",
        "HOST": "<your-primary-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
        },
    },
    "readonly": {
        "ENGINE": "mssql",
        "NAME": "app_db",
        "HOST": "<your-readonly-replica>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "Encrypt=yes;ApplicationIntent=ReadOnly",
        },
    },
    "analytics": {
        "ENGINE": "mssql",
        "NAME": "analytics_db",
        "HOST": "<your-analytics-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "isolation_level": "READ UNCOMMITTED",
        },
    },
}

Vorsicht

READ UNCOMMITTED erlaubt schmutzige Lesevorgänge. Verwenden Sie diese Isolationsstufe nur für Berichte oder Analyseabfragen, bei denen absolute Genauigkeit nicht erforderlich ist. Weitere Informationen finden Sie unter Transaktionsverwaltung.

Weiterleiten von Abfragen mit einem Datenbankrouter

Erstellen Sie einen Datenbankrouter, um Lese- und Schreibvorgänge an die entsprechende Verbindung zu leiten:

class ReadReplicaRouter:
    """Route read queries to the readonly replica, writes to the primary."""

    def db_for_read(self, model, **hints):
        return "readonly"

    def db_for_write(self, model, **hints):
        return "default"

    def allow_relation(self, obj1, obj2, **hints):
        return True

    def allow_migrate(self, db, app_label, model_name=None, **hints):
        return db == "default"

Registrieren Sie den Router in settings.py:

DATABASE_ROUTERS = ["myproject.routers.ReadReplicaRouter"]

Speichern Sie die Router-Klasse in einer Datei wie myproject/routers.py.

Direktes Abfragen einer bestimmten Datenbank

Verwenden Sie die using() Methode, um einen bestimmten Datenbankalias abzufragen:

# Explicit read from analytics database
reports = AnalyticsReport.objects.using("analytics").filter(date__gte="2025-01-01")

# Write to default
Product.objects.create(name="Widget", price=9.99)

Weitere Informationen zu Isolationsstufen für Datenbanken pro Verbindung finden Sie unter Lesen von Daten ohne Blockieren.

Feedback

War diese Seite hilfreich?

Last updated on 2026-07-01