Možnosti připojení pro mssql-django

Tento článek vysvětluje nastavení slovníku OPTIONS v konfiguraci Django DATABASES . Tato nastavení určují, jak mssql-django se připojuje k SQL Server.

Výběr ovladače databáze v Python

mssql-djangoVerze 2.0 a novější se připojují buď přes pyodbc, výchozí verzi, nebo přes mssql-python ovladač od Microsoft. Vyberte mssql-python pro databázový alias s python_driver možností:

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

Nenastavujte driver pro tuto cestu. Cesta unicode_results ignoruje možnosti extra_params, host_is_server, dsn a driver, ověřuje mssql-python vůči seznamu povolených hodnot a nepovoluje MARS. Pro úplný seznam rozdílů v chování viz Vybrat ovladač databáze pro mssql-django. Zbytek tohoto článku popisuje výchozí pyodbc cestu, pokud není uvedeno jinak.

Výběr ovladače ODBC

Na cestě pyodbc backend výchozí používá ODBC Driver 18 pro SQL Server. Pokud není nainstalovaný ovladač ODBC 18, back-end se automaticky vrátí do ovladače ODBC 17. Explicitně nakonfigurovaný ovladač se nevrátí zpět.

Note

Ovladač ODBC 18 ve výchozím nastavení povolí Encrypt=yes a ověří certifikát serveru. Připojení, která fungovala s Driver 17, mohou selhat kvůli chybě důvěryhodnosti SSL/TLS. Řešení chyby:

Pro místní SQL Server nainstalujte certifikát serveru z certifikační autority, které už klienti důvěřují, nebo stávající certifikát serveru naimportujte do každého úložiště důvěryhodnosti klienta. Pokyny najdete v tématu Konfigurace Databázový stroj systému SQL Server pro šifrování připojení.
Pokud se připojíte podle IP adresy nebo aliasu, který neodpovídá předmětu certifikátu nebo alternativnímu názvu subjektu (SAN), přidejte HostNameInCertificate=<name-from-certificate> do extra_paramssouboru .

Informace o místním vývoji proti certifikátu s vlastním podpisem najdete TrustServerCertificate v části Další parametry ODBC.

Ovladač můžete explicitně zadat:

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

V Linuxu můžete také zadat úplnou cestu ke knihovně ovladačů:

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

Můžete se připojit pomocí HOST názvu nebo názvu DSN (Název zdroje dat).

Připojit se k HOST

Většina konfigurací používá HOST nastavení přímo:

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

Připojení pomocí DSN

Použijte pojmenované DSN nakonfigurované ve zdrojích dat ODBC:

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

Podpora FreeTDS

Chcete-li jako ovladač ODBC použít FreeTDS, nastavte host_is_server na Truehodnotu . To říká back-endu, aby místo vyhledávání názvu datového serveru používal HOST a PORT přímo v 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,
        },
    },
}

Další informace o připojeních bez DSN pomocí FreeTDS najdete v uživatelské příručce FreeTDS.

Další parametry ODBC

Pomocí extra_params předejte další parametry připojovacího řetězce ODBC. Hodnota je řetězec oddělený středníkem připojený k připojovací řetězec:

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

Toto nastavení se používá také pro Microsoft Entra ověřovací klíčová slova.

Při připojení k Azure SQL Database, Azure SQL Managed Instance, SQL databázi v Microsoft Fabric, naslouchači skupin dostupnosti nebo instance failover clusteru, přidávají MultiSubnetFailover=Yes do extra_params. Když se název serveru přeloží na více než jednu IP adresu, ovladač se připojí ke všem těmto adresám současně a použije tu, která zareaguje jako první. Bez něj řidič zkouší adresy jednu po druhé a adresa, která neodpoví, spotřebuje zbývající časový limit autentizace, než řidič přejde na další. Když DNS přejde na jednu adresu, ovladač provede jeden pokus o připojení, takže nastavení je bezpečné nechat zapnuté.

MultiSubnetFailover=Yes má následující limity:

Nemůžete ho použít přes jiný protokol než TCP.
Připojení k instanci SQL Server nakonfigurované s více než 64 IP adresami selže.
S databázovým zrcadlením to nelze použít. Ovladač vrátí chybu, když připojovací řetězec určuje Failover_Partner, a také když server hlásí, že je databáze zrcadlená. Zrcadlení databází je ve všech podporovaných verzích SQL Server zastaralé. Místo toho používejte skupiny dostupnosti AlwaysOn.

Caution

Používejte TrustServerCertificate=yes pouze pro místní vývoj s certifikáty podepsanými svým držitelem. Nepoužívejte ho v produkčním prostředí. Zakáže ověřování řetězce certifikátů a zvyšuje riziko útoku typu man-in-the-middle. Nainstalujte na server důvěryhodný certifikát a připojte se pomocí TrustServerCertificate=no.

Vypnout MARS

V případě cesty pyodbc backend při použití ovladače Microsoft ODBC v systému Windows ve výchozím nastavení povoluje více aktivních sad výsledků (MARS). Některé endpointy odmítají klíčové slovo MARS_Connection, včetně služby Microsoft Fabric Warehouse. Pro připojení k jednomu z těchto koncových bodů nastavte MARS_Connection=no v tomto aliasu extra_params:

DATABASES = {
    "warehouse": {
        "ENGINE": "mssql",
        "NAME": "<database>",
        "USER": "<user_id>",
        "PASSWORD": "<password>",
        "HOST": "<server>.datawarehouse.fabric.microsoft.com",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "Authentication=ActiveDirectoryServicePrincipal;MARS_Connection=no",
        },
    },
}

Od mssql-django verze 2.0 je respektována explicitní MARS_Connection hodnota a shoda ignoruje případ, takže backend nepřidává konfliktní výchozí hodnotu. Ve verzi 1.8.0 a starších verzích Windows výchozí přepsal explicitní hodnotu a spojení selhalo.

Při vypnutém MARS načte QuerySet.iterator() celý výsledek do paměti, než začne vracet řádky, aby vnořený dotaz mohl znovu použít připojení. Zohledněte náklady na paměť u velkých querysetů.

Pro jiné autentizační metody zachovejte odpovídající autentizační nastavení a připojte MARS_Connection=no k extra_params. Toto nastavení připojení neznamená plnou podporu Microsoft Fabric Warehouse pro migrace Django nebo jiné funkce SQL Server.

Cesta mssql-python neumožňuje MARS a odmítá klíčové slovo MARS_Connection , takže toto nastavení platí pouze pro pyodbc.

Časové limity připojení a opakované pokusy

Konfigurace odolnosti připojení pomocí časového limitu a nastavení opakování:

Option	Default	Description
`connection_timeout`	`0` (zakázáno)	Maximální počet sekund čekání na připojení
`connection_retries`	`5`	Počet opakovaných pokusů o selhání připojení
`connection_retry_backoff_time`	`5`	Sekundy čekání mezi opakovanými pokusy.
`query_timeout`	`0` (zakázáno)	Maximální počet sekund čekání na dokončení dotazu

Example:

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

connection_timeout=0 je ve výchozím nastavení pro mssql-django. Protože pyodbc volá SQLSetConnectAttr(SQL_ATTR_LOGIN_TIMEOUT, ...) pouze tehdy, když zadáte kladnou hodnotu, platí výchozí nastavení závislé na ovladači (15 sekund pro Microsoft ODBC Driver for SQL Server). Nastavte explicitní hodnotu, aby nereagující pokusy o připojení selhaly předvídatelně.

Pokud je cílem serverless Azure SQL Database s povoleným automatickým pauzováním, použijte alespoň 60. Automaticky pozastavená databáze se obnoví při prvním pokusu o připojení a tento pokus může selhat s chybou 40613, zatímco databáze pokračuje. Při kratším timeoutu první pokus o připojení vyprší dříve, než se životopis dokončí. connection_retries Nakonec uspěje, ale první požadavek čeká několik časových limitů, než se připojí. Více informací naleznete v části Automatické pozastavení a automatické obnovení.

Collation

Nastavte vlastní kolaci pro vyhledávání v textových polích:

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

Více databázových připojení

Django podporuje připojení k více databázím současně. To je užitečné například pro repliky určené ke čtení, dotazy mezi databázemi nebo oddělení pracovních zátěží podle úrovně izolace.

Konfigurace více databází

Definujte každé připojení v DATABASES nastavení:

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

Caution

READ UNCOMMITTED umožňuje špinavé čtení. Tuto úroveň izolace použijte pouze pro dotazy pro účely sestav nebo analýz, u nichž není vyžadována absolutní přesnost. Další informace naleznete v tématu Správa transakcí.

Směrování dotazů pomocí směrovače databáze

Vytvořte směrovač databáze pro přímé operace čtení a zápisu do příslušného připojení:

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"

Zaregistrujte směrovač v settings.py:

DATABASE_ROUTERS = ["myproject.routers.ReadReplicaRouter"]

Uložte třídu směrovače do souboru, například myproject/routers.py.

Dotazování konkrétní databáze přímo

Použijte metodu using() k dotazování konkrétního aliasu databáze:

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

Další informace o úrovních izolace v databázích pro jednotlivá připojení viz Čtení dat bez blokování.

Váš názor

Byla tato stránka užitečná?

Poslední aktualizace v 2026-09-29