mssql-django 的連線選項

本文說明你的 Django DATABASES 設定中的 OPTIONS 字典設定。這些設定控制如何mssql-django透過 ODBC 驅動程式連接 SQL Server。

ODBC 驅動程式選擇

從 1.7 版本起mssql-django，後端預設為 SQL Server 的 ODBC 驅動程式 18。如果沒有安裝 ODBC 驅動程式 18，後端會自動回退到 ODBC 驅動程式 17。

Note

ODBC Driver 18 Encrypt=yes 預設啟用並驗證伺服器憑證。使用 Driver 17 的連線可能會因 SSL/TLS 信任錯誤而失敗。解決失敗問題的方法：

對於本地 SQL Server，請從客戶端已信任的憑證授權中心安裝伺服器憑證，或將現有的伺服器憑證匯入每個用戶端信任儲存庫。有關相關說明，請參閱「配置 SQL Server Database Engine」以加密連線。
如果你用 IP 位址或與憑證主體或主體替代名稱（SAN）不符的別名連線，請加上 HostNameInCertificate=<name-from-certificate>extra_params。

關於針對自簽憑證的本地開發，請參見 TrustServerCertificateExtra ODBC 參數。

你可以明確指定驅動程式：

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

在 Linux 上，你也可以指定驅動程式庫的完整路徑：

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 與 HOST 的比較

你可以用 HOST 名稱或命名的 DSN（資料來源名稱）來連接。

與 HOST 連結

大多數配置直接使用以下 HOST 設定：

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

與DSN連結

請在你的 ODBC 資料來源中使用指定的 DSN：

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

FreeTDS 支援

若要使用 FreeTDS 作為 ODBC 驅動程式，請設定 host_is_server 為 True。這會告訴後端直接使用 HOST 和 PORT ，而不是在：中查找資料伺服器名稱 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,
        },
    },
}

欲了解更多關於FreeTDS無DSN連線的資訊，請參閱 FreeTDS使用者指南。

額外的 ODBC 參數

使用 extra_params 傳遞額外的 ODBC 連線字串參數。該值是一個以分號分隔的字串，附加在連接字串上：

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

此設定也用於 Microsoft Entra 認證關鍵字。

謹慎

僅用於 TrustServerCertificate=yes 本地開發，並使用自簽憑證。不要在生產環境中使用它。它會禁用憑證鏈驗證，並增加中間攻擊者的風險。在伺服器上安裝受信任憑證並連接到 TrustServerCertificate=no。

連線逾時與重試

使用逾時與重試設定來提高連線韌性：

Option	預設	Description
`connection_timeout`	`0` （禁用）	等待連線的最大秒數。
`connection_retries`	`5`	連線失敗時的重試次數。
`connection_retry_backoff_time`	`5`	每次重試之間的等待秒數。
`query_timeout`	`0` （禁用）	等待查詢完成的最長秒數。

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

Collation

為文字欄位查詢設定自訂定序：

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

多重資料庫連接

Django 支援同時連接多個資料庫。這對於讀取副本、跨資料庫查詢或依隔離層級分離工作負載非常有用。

配置多個資料庫

在 DATABASES 設定中定義每個連線：

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

謹慎

READ UNCOMMITTED 允許髒讀。此隔離層僅用於報告或分析查詢，且不需要絕對精確度。欲了解更多資訊，請參閱交易管理。

使用資料庫路由器進行路由查詢

建立資料庫路由器，將讀寫操作導向適當的連線：

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"

在 settings.py 中註冊路由器：

DATABASE_ROUTERS = ["myproject.routers.ReadReplicaRouter"]

將路由器類別儲存在像 myproject/routers.py. 這樣的檔案中。

直接查詢特定資料庫

使用 using() 該方法查詢特定的資料庫別名：

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

欲了解更多關於每個連線資料庫隔離等級的資訊，請參閱「無阻塞讀取資料」。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-07-01