本文為 Django 資料庫後端的完整 settings.py 設定參考資料 mssql-django 。 透過編輯 DATABASES Django 專案settings.py檔案中的字典來設定 SQL Server 連線。
最小配置
以下範例顯示了最小所需的配置：
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",
},
},
}
資料庫連線設定
這些設定會設定你的 DATABASES 連線。 大多數是標準的 Django 設定;例外情況如下：
| Setting | 類型 | Description |
|---|---|---|
ENGINE |
String | 必須是 "mssql"。 |
NAME |
String | 資料庫名稱。 必須的。 |
HOST |
String | 伺服器主機名稱或 IP 位址。 命名實例請使用 "server\\instance" 格式。 |
PORT |
String | 伺服器實例埠。 空字串代表預設埠。 |
USER |
String | 資料庫用戶名稱。 若未提供，則使用 Windows 整合安全。 |
PASSWORD |
String | 資料庫使用者密碼。 |
AUTOCOMMIT |
布林值 | 設定為 False 以停用 Django 的交易管理。 預設值為 True。 |
Trusted_Connection |
String | 設定為"yes"（預設）使用 Windows 整合安全，當USER沒有提供時。 當 USER 和 PASSWORD 都設定好時，這些憑證會優先 Trusted_Connection 且會被忽略。 設定為 "no" 以明確停用 Windows 驗證。 這是擴充， mssql-django 不是標準的 Django 設定。 |
TOKEN |
String | Microsoft Entra 認證的存取權杖（例如，透過 azure.identity）。 這是擴充， mssql-django 不是標準的 Django 設定。 |
測試設定
這些設定控制 Django 測試執行器所使用的測試資料庫：
| Setting | 類型 | Description |
|---|---|---|
NAME |
String | 測試資料庫名稱。 預設值："test_" + NAME。 |
COLLATION |
String | 測試資料庫的彙整。 預設：實例預設。 |
DEPENDENCIES |
List | 資料庫的建立順序相依關係。 |
MIRROR |
String | 測試時用來鏡像的資料庫別名。 |
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",
},
"TEST": {
"NAME": "test_mydb",
"COLLATION": "SQL_Latin1_General_CP1_CI_AS",
},
},
}
選項
字 OPTIONS 典提供後端專屬的設定。 將以下設定放入字典中 DATABASES["default"]["OPTIONS"] ：
| Option | 類型 | 預設 | Description |
|---|---|---|---|
driver |
String | "ODBC Driver 18 for SQL Server" |
使用 ODBC 驅動程式。 如果沒有安裝驅動程式 18，會自動回退回驅動程式 17。 |
isolation_level |
String | None |
交易隔離層級：READ UNCOMMITTED、READ COMMITTEDREPEATABLE READSNAPSHOT或。SERIALIZABLE |
dsn |
String | None |
命名為DSN。 可替代 HOST。 |
host_is_server |
布林值 | False |
設定為True直接使用PORTHOST/FreeTDS 而非資料freetds.conf伺服器名稱。 |
unicode_results |
布林值 | False |
啟動 pyodbc unicode_results 的功能。 |
extra_params |
String | None |
格式中的 "param=value;param=value" 額外 ODBC 參數。 用於 Microsoft Entra 認證。 |
collation |
String | None |
用於文字欄位查詢的彙整（例如， "Chinese_PRC_CI_AS"）。 |
connection_timeout |
Integer | 0 |
連線逾時數為秒0 （= 停用）。 |
connection_retries |
Integer | 5 |
連線重試次數。 |
connection_retry_backoff_time |
Integer | 5 |
重試間隔的退後時間在幾秒內。 |
query_timeout |
Integer | 0 |
查詢逾時時間（秒數：0 = 停用）。 |
setencoding / setdecoding |
List | None |
PYODBC 編碼 / 解碼 配置。 |
return_rows_bulk_insert |
布林值 | False |
允許從大量插入物回傳的行。 一定是 False 表格有觸發器。 |
datefirst |
Integer | 7 |
每週的第一天。SET DATEFIRST
7是星期天（SQL Server 預設1），是星期一。 |
driver_needs_utf8 |
僅在場選項 | 未設定 | 啟用 ODBC 驅動程式的 UTF-8 編碼。 當金鑰存在於 OPTIONS;時此選項會啟用;該值本身被忽略。 通常在 FreeTDS 或較舊的 UnixODBC 預設為 Latin-1 時需要。 |
driver_charset |
String | None |
ODBC 驅動程式的明確字元集（例如 "UTF-8"）。 當驅動程式沒有自動偵測編碼時，使用 driver_needs_utf8 。 |
connection_recovery_interval_msec |
浮動 | 0.0 |
在網路錯誤後，後端連線恢復迴圈中，重試嘗試之間等待的時間是毫秒。 對於不穩定的網路連結，則提高這個值。 |
常見選項範例：
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": "Encrypt=yes",
"isolation_level": "READ COMMITTED",
"connection_timeout": 30,
"connection_retries": 3,
"connection_retry_backoff_time": 5,
"query_timeout": 60,
},
},
}
後端專屬設定
此設定位於模組層 settings.py級，位於 DATABASES 字典之外：
| Setting | 類型 | 預設 | Description |
|---|---|---|---|
DATABASE_CONNECTION_POOLING |
布林值 | True |
設定為 False 以停用 pyodbc 的連線池。 |
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",
},
},
}
# Set this to False to disable pyodbc's connection pooling
DATABASE_CONNECTION_POOLING = False