本文說明連線池 mssql-django 在 Django 應用中的運作方式，以及如何設定它。
連線池的運作方式
預設會由 mssql-django 使用驅動程式層級的連線集區。 預設的 pyodbc 路徑使用 pyodbc 池化，而 mssql-python 路徑則使用 mssql-python 池化。 當 Django 關閉連線時，主動驅動程式會將該連線回回池，而非關閉底層的資料庫連線。 後續的連線請求會重複使用合併連線，減少建立新資料庫連線的開銷。 關於驅動程式選擇的詳細資訊，請參閱 mssql-django 的選擇資料庫驅動程式。
設定連線集區
連線集區由 DATABASE_CONNECTION_POOLING 設定來控制，該設定位於 settings.py 的模組層級（在 DATABASES 字典之外）：
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 to False to disable driver-level connection pooling
DATABASE_CONNECTION_POOLING = False
| 價值觀 | 行為 |
|---|---|
True (預設值) |
連線池已啟用。 已關閉的連線會回到池中。 |
False |
驅動程式層級的連線池被禁用。 pyodbc 路徑會設定 Database.pooling=False，而 mssql-python 路徑會呼叫 PoolingManager.disable()。 |
何時應停用連線集區
在以下情況下，請考慮關閉連線池功能：
- 基於憑證的認證：使用過期的存取憑證時，池連線可能會持有過期的憑證。
- 對連線問題進行偵錯：停用連線集區可簡化疑難排解，確保每個請求都會建立全新的連線。
- 短命程序：對於腳本或管理指令，只要查詢幾次就結束，池化並不會帶來任何好處。
連線重試設定
不論池化設定如何，你都可以設定連線失敗時的重試行為。 完整重試與逾時選項清單，請參閱設定參考。
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_retries": 3,
"connection_retry_backoff_time": 10,
"connection_timeout": 30,
},
},
}
Django 的 CONN_MAX_AGE
Django 也提供一個 CONN_MAX_AGE 設定，可以控制 Django 在關閉資料庫連線前保持開啟的時間長短。 此設定可與驅動程式層級的連線池搭配運作：
DATABASES = {
"default": {
"ENGINE": "mssql",
"NAME": "<your-database>",
"USER": "<your-username>",
"PASSWORD": "<your-password>",
"HOST": "<your-server>",
"PORT": "1433",
"CONN_MAX_AGE": 600, # Keep connections open for 10 minutes
"OPTIONS": {
"driver": "ODBC Driver 18 for SQL Server",
},
},
}
欲了解更多相關 CONN_MAX_AGE資訊，請參閱 Django 資料庫設定文件。
實務起點：
-
CONN_MAX_AGE=0：最適合用於除錯和短時間執行的作業。 -
CONN_MAX_AGE=600： 對許多網頁應用程式來說都是不錯的預設值。 -
CONN_MAX_AGE=3600：對經過負載測試後的穩定高吞吐量服務而言是合理的。
Note
當你使用 ASGI 伺服器（例如 Daphne 或 Uvicorn）或執行緒部署時，持久連線可能會在非同步上下文間洩漏。 如果你將 CONN_MAX_AGE 與 ASGI 伺服器搭配使用，請在受支援的 Django 版本中設定 CONN_HEALTH_CHECKS = True，並在實際的並行情境下進行測試。 欲了解更多資訊，請參閱 Django 關於 連線管理的文件。
CONN_HEALTH_CHECKS 在重複使用前驗證合併連線。 如果 Django 偵測到連線過時，它會透明地開啟一條新的連線。 這會為每次請求增加少量檢查成本，對於長時間執行的程序通常值得啟用。