Verbindingsopties voor mssql-django

In dit artikel worden de OPTIONS woordenlijstinstellingen in uw Django-configuratie DATABASES uitgelegd. Met deze instellingen bepaalt u hoe mssql-django u verbinding maakt met SQL Server via het ODBC-stuurprogramma.

Selectie van ODBC-stuurprogramma

Vanaf mssql-django 1.7 wordt de back-end standaard ingesteld op ODBC-stuurprogramma 18 voor SQL Server. Als ODBC-stuurprogramma 18 niet is geïnstalleerd, valt de back-end automatisch terug op ODBC-stuurprogramma 17.

Note

ODBC-stuurprogramma 18 schakelt standaard in Encrypt=yes en valideert het servercertificaat. Verbindingen die met stuurprogramma 17 hebben gewerkt, kunnen mislukken met een SSL/TLS-vertrouwensfout. De fout oplossen:

Installeer voor on-premises SQL Server een servercertificaat van een certificeringsinstantie die uw clients al vertrouwen of importeer het bestaande servercertificaat in elk clientvertrouwensarchief. Zie SQL Server Database Engine configureren voor het versleutelen van verbindingen voor instructies.
Als u verbinding maakt met een IP-adres of een alias die niet overeenkomt met de onderwerp- of onderwerp alternatieve naam (SAN) van het certificaat, voegt u dit toe HostNameInCertificate=<name-from-certificate> aan extra_params.

Zie TrustServerCertificate voor lokale ontwikkeling op basis van een zelfondertekend certificaat.

U kunt het stuurprogramma expliciet opgeven:

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",
        },
    },
}

In Linux kunt u ook het volledige pad naar de stuurprogrammabibliotheek opgeven:

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 versus HOST

U kunt verbinding maken met behulp van een HOST naam of een benoemde DSN (gegevensbronnaam).

Verbinding maken met HOST

De meeste configuraties gebruiken de HOST instelling rechtstreeks:

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",
        },
    },
}

Verbinding maken met DSN

Gebruik een benoemde DSN die is geconfigureerd in uw ODBC-gegevensbronnen:

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

Ondersteuning voor FreeTDS

Als u FreeTDS wilt gebruiken als het ODBC-stuurprogramma, stelt u in host_is_server op True. Dit vertelt de backend om HOST en PORT rechtstreeks te gebruiken in plaats van de naam van een dataserver op te zoeken in freetds.conf:

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,
        },
    },
}

Zie de gebruikershandleiding voor FreeTDS voor meer informatie over DSN-less-verbindingen met FreeTDS.

Extra ODBC-parameters

Gebruik extra_params om extra ODBC-verbindingsreeksparameters door te geven. De waarde is een door puntkomma's gescheiden tekenreeks die is toegevoegd aan de verbindingsreeks:

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",
        },
    },
}

Deze instelling wordt ook gebruikt voor Microsoft Entra verificatietrefwoorden.

Waarschuwing

Alleen gebruiken TrustServerCertificate=yes voor lokale ontwikkeling met zelfondertekende certificaten. Gebruik het niet in productie. Hierdoor wordt de validatie van de certificaatketen uitgeschakeld en neemt het man-in-the-middle-risico toe. Installeer een vertrouwd certificaat op de server en maak verbinding met TrustServerCertificate=no.

Verbindingstime-outs en nieuwe pogingen

De veerkracht van de verbinding configureren met time-out- en herhalingsinstellingen:

Option	Default	Description
`connection_timeout`	`0` (uitgeschakeld)	Maximum aantal seconden dat moet worden gewacht op een verbinding.
`connection_retries`	`5`	Aantal nieuwe pogingen bij verbindingsfouten.
`connection_retry_backoff_time`	`5`	Seconden om te wachten tussen nieuwe pogingen.
`query_timeout`	`0` (uitgeschakeld)	Maximum aantal seconden dat moet worden gewacht totdat een query is voltooid.

Voorbeeld:

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,
        },
    },
}

Collation

Stel een aangepaste sortering in voor opzoekacties voor tekstvelden:

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",
        },
    },
}

Meerdere databaseverbindingen

Django ondersteunt gelijktijdig verbinding maken met meerdere databases. Dit is handig voor leesreplica’s, query’s tussen databases of het scheiden van workloads naar isolatieniveau.

Meerdere databases configureren

Definieer elke verbinding in de DATABASES instelling:

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",
        },
    },
}

Waarschuwing

READ UNCOMMITTED staat vuile leesbewerkingen toe. Gebruik dit isolatieniveau alleen voor rapportage- of analysequery's waarvoor geen absolute nauwkeurigheid is vereist. Zie Transactiebeheer voor meer informatie.

Query's routeren met een databaserouter

Maak een databaserouter om lees- en schrijfbewerkingen naar de juiste verbinding te leiden:

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"

Registreer de router in settings.py:

DATABASE_ROUTERS = ["myproject.routers.ReadReplicaRouter"]

Sla de routerklasse op in een bestand, zoals myproject/routers.py.

Rechtstreeks een query uitvoeren op een specifieke database

Gebruik de using() methode om een query uit te voeren op een specifieke databasealias:

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

Zie Gegevens lezen zonder te blokkeren voor meer informatie over isolatieniveaus voor databases per verbinding.

Feedback

Is deze pagina nuttig?

Last updated on 2026-07-01