疑難排解 mssql-django

診斷並解決 SQL Server、Azure SQL Database、Azure SQL 受控執行個體及 Microsoft Fabric 中 SQL 資料庫後端常見問題mssql-django。

mssql-django 2.0 支援預設的 pyodbc 驅動程式路徑及可選擇加入的 mssql-python 驅動程式路徑。欲了解更多資訊，請參閱 MSSQL-django 的選擇資料庫驅動程式。

連接問題

本節將介紹最常見的連線錯誤及其解決方法。

ODBC 驅動程式不在 pyodbc 路徑上

徵兆：

django.core.exceptions.ImproperlyConfigured: 'ODBC Driver 18 for SQL Server' is not a recognized ODBC driver

Or:

Error: ('01000', "[01000] [unixODBC][Driver Manager]Can't open lib 'ODBC Driver 18 for SQL Server'")

多個原因與解決方案：

未安裝 ODBC 驅動程式

使用預設 pyodbc 路徑時，安裝 Microsoft ODBC 驅動程式用於 SQL Server。欲下載連結，請參閱下載 SQL Server 的 ODBC 驅動程式。 mssql-python 路徑不會使用外部安裝的 ODBC 驅動程式。

安裝多個驅動程式版本

請在： settings.py中指定精確的驅動程式名稱或路徑：

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<database>",
        "USER": "<user_id>",
        "PASSWORD": "<password>",
        "HOST": "<server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 17 for SQL Server",
        },
    },
}

在 Linux 上，請指定完整路徑：

"OPTIONS": {
    "driver": "/opt/microsoft/msodbcsql17/lib64/libmsodbcsql-17.10.so.6.1",
},

檢查已安裝的驅動程式
- 在 Linux/macOS 上，執行 odbcinst -q -d。
- 在 Windows 上，請在管理工具中檢查 ODBC 資料來源。

MSSQL-Python 拒絕連線選項

徵兆：

將 "python_driver": "mssql_python" 設為別名時，在你將 pyodbc 連線字串關鍵字移至 OPTIONS["extra_params"] 後，會在設定連線期間失敗，並出現下列其中一個錯誤：

mssql_python.exceptions.ConnectionStringParseError: Connection string parsing failed:
  Unknown keyword 'longasmax' is not recognized

mssql_python.exceptions.ConnectionStringParseError: Connection string parsing failed:
  Reserved keyword 'driver' is controlled by the driver and cannot be specified by the user

訊息中的關鍵字名稱是小寫的，所以你寫的 LongAsMax 關鍵字會顯示為 longasmax。 ConnectionStringParseError 不屬於 DB-API 例外階層，因此 Django 不會將其重新包裝為 django.db.utils 錯誤。

多個原因與解決方案：

extra_params 中的 pyodbc 專用關鍵字

mssql-python 路徑會根據允許清單驗證 extra_params。 DRIVER 和 APP 供駕駛人使用，並產生 Reserved keyword 表單。 DSN、SERVERNAME、LongAsMax，以及僅限 pyodbc 的關鍵字，例如 ColumnEncryption、Regional、UseFMTONLY、Network Library、Current Language、QuotedId、AnsiNPW、Description、WSID、Connect Timeout 和 Unknown keyword，都不在允許清單中，並會產生 MARS_Connection 形式。移除關鍵字，或使用預設的 pyodbc 路徑來設定需要該 ODBC 選項的別名。
驅動程式選項預期用於控制 mssql-python

mssql-python 路徑忽略 driver、 dsn、 host_is_server、 unicode_results。 HOST變PORT為，空HOST變為 localhostSERVER=<server>,<port>。

MSSQL-Python 相依關係太舊了

徵兆：

設定了 "python_driver": "mssql_python" 的別名在建立連線時會失敗，並出現以下其中一個錯誤：

django.core.exceptions.ImproperlyConfigured: mssql-python 1.15.0 or newer is required; you have 1.14.0

django.core.exceptions.ImproperlyConfigured: The 'python_driver' connection option requests mssql-python, but the module could not be imported: No module named 'mssql_python'. Install it with 'pip install "mssql-python>=1.15.0"'.

第二種表單代表模組 mssql_python 完全無法匯入。

解決方案：安裝 mssql-python>=1.15.0。 mssql-django 2.0 宣告 mssql-python>=1.15.0，因此一般的 pip install mssql-django 在支援的平台上會解析為相容版本。

驅動程式 17 的備援不適用於 mssql-python

徵兆：

即使安裝了 Microsoft ODBC Driver 17 for SQL Server，設定的別名"python_driver": "mssql_python"仍然會失敗。

此案沒有明顯的錯誤。 mssql-python 路徑會靜默忽略該 driver 選項，因此連線會失敗，並出現底層錯誤。如果你把駕駛者的名字移到 extra_params 裡面，就會收到 Reserved keyword 'driver' 錯誤。請參考 mssql-python 拒絕連線選項。

解決方案：如果別名必須使用外部安裝的 ODBC Driver 17，則使用預設的 pyodbc 路徑。 mssql-python 路徑不會退回到 Driver 17，且會忽略這個 driver 選項。那條路徑不需要另外安裝 ODBC 驅動程式。

連線被拒

徵兆：

django.db.utils.OperationalError: ('08001', '[08001] ... TCP Provider: Error code 0x2749 ...')

多個原因與解決方案：

SQL Server 上未啟用 TCP/IP
- 開啟 SQL Server 組態管理員。
- 在 SQL Server 網路設定中啟用 TCP/IP。
- 在 TCP/IP 屬性中，啟用用於該連線的 IP 位址。
- 重新啟動 SQL Server 服務。
防火牆阻擋埠 1433
- 確認防火牆規則是否允許在 1433 埠接入連線。
- 對於 Azure SQL，請在 Azure portal 防火牆設定中新增你的客戶端 IP。
伺服器名稱或埠口錯誤

確認您設定中的 HOST 和 PORT 值。

徵兆：

django.db.utils.OperationalError: ('28000', "[28000] [Microsoft][ODBC Driver 18 for SQL Server][SQL Server]Login failed for user '<user_id>'. (18456) (SQLDriverConnect); [28000] [Microsoft][ODBC Driver 18 for SQL Server][SQL Server]Login failed for user '<user_id>'. (18456)")

在 mssql-python 這條路線上：

django.db.utils.OperationalError: Driver Error: Invalid authorization specification; DDBC Error: [Microsoft][SQL Server]Login failed for user '<user_id>'.

多個原因與解決方案：

錯誤的資格證明

請驗證使用者名稱和密碼。
資料庫 NAME 不存在

在 SQL Server 上，mssql-python 路徑會產生同樣OperationalError的訊息，和錯誤密碼一樣，所以光是訊息本身並不能告訴你你打到哪一個。在更改憑證前，先確認資料庫是否存在。讓 NAME 指向 master，以單獨測試登入：如果能連線成功，代表憑證正確，問題出在資料庫。 pyodbc 路徑將此情況分別報告為 Cannot open database "<database>" requested by the login. The login failed. (4060)。

Azure SQL Database 對此情況的報告方式不同。 mssql-python 路徑會引發 Driver Error: General error; DDBC Error: [Microsoft][SQL Server]Cannot open server "<server>" requested by the login. The login failed.。訊息中指出了伺服器名稱，但伺服器名稱本身沒有問題。請直接檢查 NAME 。
使用者不存在

確認登入是否映射到目標資料庫中的使用者。
SQL Server 認證已停用

啟用混合模式驗證，或使用 Windows 或 Microsoft Entra 認證。

連線超時

徵兆：

django.db.utils.OperationalError: ('HYT00', '[HYT00] [Microsoft][ODBC Driver 18 for SQL Server]Login timeout expired')

多個原因與解決方案：

網路等待時間

在 OPTIONS 中增加 connection_timeout。
已啟用自動暫停的 Azure SQL Database 無伺服器

自動暫停的資料庫會在第一次連線嘗試時恢復，該嘗試可能因錯誤 40613 而失敗，而資料庫則會繼續連線。將 connection_timeout 設為至少 60，然後重新嘗試首次連線。欲了解更多資訊，請參閱 Azure SQL Database serverless 及自動暫停與自動恢復。

伺服器過載

增加 connection_retries 且 connection_retry_backoff_time。

"OPTIONS": {
    "driver": "ODBC Driver 18 for SQL Server",
    "connection_timeout": 30,
    "connection_retries": 5,
    "connection_retry_backoff_time": 10,
},

移轉問題

這些錯誤發生在 Django 對 SQL Server 的遷移操作中。

原始 SQL 與 GROUP BY 問題

這些錯誤會在帶有 GROUP BY 子句的原始查詢或附有註解的查詢通過後端的佔位符重寫步驟時發生。

`IndexError` 在 GROUP BY 上，包含逃逸 `%%` 參數與實參數

徵兆：

IndexError: Replacement index N out of range for positional args tuple

查詢在沒有 GROUP BY 子句時可以運作，在沒有經過跳脫的 %% 常值時也可以運作，但當兩者與實際的 %s 參數同時存在時，就會失敗。

解決方法：升級到最新版本 mssql-django 。後端會將佔位符重寫正則表達式縮小為 %% 和 %s ，因此逃逸 %% 的字面值會被逐字保留，且不會注入任何幻影佔位符。

`NotImplementedError` 對於 `IntegerChoices` 在原始 GROUP BY 查詢中

徵兆：

NotImplementedError: Not supported type <enum '...'> (StatusChoices.IN_PROGRESS)

相同的枚舉值可在 ORM 查詢及不含 GROUP BY的原始查詢中運作，但當將參數傳入包含 GROUP BY 子句的原始查詢時，則會失敗。

解決方法：升級到最新版本 mssql-django 。後端在 GROUP BY 路徑中使用 isinstance 進行參數型別檢查，因此 IntegerChoices（int 的子類別）能正確綁定。 bool 仍會繫結 bit，而純 int 則維持不變。

正則表達式查詢問題

`regex` 或 `iregex` 不回傳任何列

症狀：查詢無錯誤執行，回傳的結果集為空，儘管所有列與模式相符。

Product.objects.filter(name__regex=r"^Widget \d+$")  # no rows, though "Widget 42" exists

原因： dbo.REGEXP_LIKE 忽略圖案中的字面空白。該模式會被視為如同是 ^Widget\d+$，因此任何含有空格的值都無法符合。什麼都沒升起，所以空的結果看起來像是資料問題。

解決方案：將空白寫成跳脫字元或字元類別：

Product.objects.filter(name__regex=r"^Widget\s\d+$")
Product.objects.filter(name__regex=r"^Widget[ ]\d+$")

`Cannot find ... dbo.REGEXP_LIKE`

徵兆：

django.db.utils.ProgrammingError: ('42000', '[42000] [Microsoft][ODBC Driver 18 for SQL Server][SQL Server]Cannot find either column "dbo" or the user-defined function or aggregate "dbo.REGEXP_LIKE", or the name is ambiguous. (4121) (SQLExecDirectW)')

在 mssql-python 路徑上：

django.db.utils.ProgrammingError: Driver Error: Syntax error or access violation; DDBC Error: [Microsoft][SQL Server]Cannot find either column "dbo" or the user-defined function or aggregate "dbo.REGEXP_LIKE", or the name is ambiguous.

原因：CLR 組件並未安裝在你查詢的資料庫中。它是按資料庫安裝的，不是按伺服器安裝的。

解決方案：對該資料庫執行 python manage.py install_regex_clr <database>。刪除並重新建立資料庫後，再重新執行一次。請參見設定正則表達式查詢。

日期與時間問題

`Now()` 值會在 `USE_TZ=True` 時位移

徵兆：

使用 Django Now()、auto_now 或 auto_now_add 寫入的時間戳記，在 SQL Server 主機時區不是 UTC 時會發生位移。

解決方法：升級到最新版本 mssql-django 。後端會產生具時區感知功能的 Now() SQL，保留 datetimeoffset 的偏移量，並透過 zoneinfo 和 tzdata 讀取時區資料。

`AttributeError` 呼叫 `.explain()` 時

徵兆：

AttributeError: ... explain_format ...

解決方法：升級到最新版本 mssql-django 。後端負責解釋每個支援的 Django 版本的元資料。

無法更改 AutoField

徵兆：

django.db.utils.ProgrammingError: Cannot alter column to or from an IDENTITY column

解決方案：SQL Server 不支援將欄位從或變更為 AutoField。建立一個想要的欄位類型的新模型，手動遷移資料，然後丟棄舊資料表。有關解決方法，請參見 mssql-django 的資料庫遷移。

重命名在外鍵限制下失敗

徵兆：

django.db.utils.ProgrammingError: ... could not drop constraint ...

解決方案：SQL Server 需要在重新命名欄位前先捨棄外鍵約束。在您的遷移過程中使用 SeparateDatabaseAndState。舉例來說，請參考 mssql-django 的資料庫遷移。

編碼問題

當 pyodbc pyodbc 路徑誤解 SQL Server 的字元資料時，通常會發生編碼錯誤。

Unicode 編碼錯誤

徵兆：

UnicodeDecodeError: 'utf-8' codec can't decode byte ...

解決方案：在 OPTIONS 字典中設定 pyodbc 編碼。 mssql-python 路徑忽略 unicode_results。

"OPTIONS": {
    "driver": "ODBC Driver 18 for SQL Server",
    "unicode_results": True,
},

FreeTDS 問題

FreeTDS 需要 pyodbc 專用設定，且與 Microsoft ODBC 驅動程式不同。

host_is_server 錯誤

徵兆：

使用未指定 host_is_server的 FreeTDS 時連線失敗。

解決方案：設定 host_is_server 為 True 使用 FreeTDS 時：

"OPTIONS": {
    "driver": "FreeTDS",
    "host_is_server": True,
},

欲了解更多 FreeTDS 設定資訊，請參閱 mssql-django 的連線選項。

測試資料庫問題

測試資料庫的建立與銷毀可能會因你的認證方式而失敗。

無法建立使用管理身份的測試資料庫

徵兆：

django.db.utils.DatabaseError: ('42000', '[42000] ... EXECUTE permission denied on object ...')

Or:

django.db.utils.OperationalError: ('28000', ... login failed ...)

當你使用 ActiveDirectoryMsi （管理身份）驗證時，測試執行者無法建立或銷毀測試資料庫。此限制存在的原因在於：

管理身份憑證是從主機環境（例如 Azure VM 和 App Service）取得的。
測試執行器在 teardown 期間會嘗試使用 test 資料庫憑證進行連線。
管理身份可以被賦予資料庫層級的角色，但測試資料庫的建立與刪除通常需要伺服器層級的權限，而測試執行者往往沒有這些權限。

受影響的認證方式：

ActiveDirectoryMsi（Azure managed identity）
ActiveDirectoryServicePrincipal （僅在伺服器範圍內設定時）

支援的認證方法 （測試資料庫建立可行）：

ActiveDirectoryPassword
ActiveDirectoryIntegrated
SQL 認證（使用者名稱/密碼）

測試環境中的身分驗證取捨

方法	無秘密	可配合自動建立／刪除測試資料庫運作	典型用途
`ActiveDirectoryMsi`	Yes	通常不會（除非有伺服器層級的權限）	Azure 託管的生產工作負載
`ActiveDirectoryServicePrincipal`	否（用戶端密碼/憑證）	這取決於被授予的伺服器層級權限	採用明確身分管理的 CI/CD
`ActiveDirectoryPassword`	否	是的（只要有足夠的 SQL 權限）	開發人員與受控的 CI 環境
SQL 驗證	否	是的（只要有足夠的 SQL 權限）	局部或隔離測試環境

解決方案：

開發時：使用 --keepdb 旗標以略過測試資料庫的清理：
```
python manage.py test --keepdb
```

針對 CI/CD 管線：預先建立專用測試資料庫並授予受管理身份 CREATE TABLE 與 ALTER 權限：

-- Connect as a server admin, then:
USE [test_database_name];

-- Grant permissions for managed identity (replace with your identity name)
CREATE USER [your-app-identity] FROM EXTERNAL PROVIDER;
GRANT CREATE TABLE TO [your-app-identity];
GRANT ALTER ON SCHEMA::dbo TO [your-app-identity];

替代方案：測試環境使用 SQL 認證，或在 CI/CD 測試執行器中切換至 ActiveDirectoryPassword SQL 認證。

回退程序

當遷移中途失敗時，請使用此回滾序列回到已知良好狀態：

停止應用程式寫入以避免額外的結構漂移。

檢視移轉狀態：

python manage.py showmigrations
python manage.py sqlmigrate <app_label> <migration_number>

回復到上一個已知正常的遷移版本：

python manage.py migrate <app_label> <previous_migration>

如果結構描述與遷移歷史不一致，只有在確認實際資料庫架構後，才可使用 --fake 謹慎修復狀態。
先在暫存環境中重執行遷移，然後再嘗試生產環境。

Important

對於破壞性遷移，如丟棄、重命名及欄位型別變更，部署前請先進行測試備份。如果無法透過遷移回滾，請從備份還原並重新套用已驗證的遷移。

Docker 與容器問題

容器映像檔在使用預設 pyodbc 路徑時，需要明確安裝 ODBC 驅動程式並建立建置相依關係。 mssql-python 方案不需要另外安裝 ODBC 驅動程式，但仍需要 unixODBC 執行階段，因為 Django 載入後端時會匯入 pyodbc。

貨櫃中找不到 ODBC 驅動程式

徵兆：

Error: ('01000', "[01000] [unixODBC][Driver Manager]Can't open lib 'ODBC Driver 18 for SQL Server'")

多個原因與解決方案：

ODBC 驅動程式未安裝在容器映像中

Slim 或 Alpine 的基礎映像檔不包含 ODBC 驅動程式。使用 pyodbc 時，加入 Microsoft APT 倉庫並安裝msodbcsql18在你的 Dockerfile 裡。完整 Dockerfile 範例請參見 Deploy to App Service 。
遺失包裹unixodbc-dev

pyodbc wheel 連結至 libodbc.so。安裝 Python 套件前，先安裝unixodbc-dev（Debian/Ubuntu）或 unixODBC-devel （RHEL/Fedora）。
apt-get autoremove 在安裝驅動程式後libgssapi-krb5-2移除

msodbcsql18 會在執行階段載入 libgssapi-krb5-2，但未將其宣告為相依性。庫通常以的curl依賴形式出現，因此用 --auto-remove清除 curl 或之後執行apt-get autoremove即可移除。映像檔可順利建置，但之後所有連線都失敗。明確安裝 libgssapi-krb5-2 ，安裝驅動程式後不要自動移除。

安裝版本 18 時，驅動程式 17 顯示遺失

徵兆：

Error: ('01000', "[01000] [unixODBC][Driver Manager]Can't open lib 'ODBC Driver 17 for SQL Server' : file not found (0) (SQLDriverConnect)")

錯誤顯示版本為 17，但 odbcinst -q -d 顯示已註冊版本 18，且 dpkg -l msodbcsql18 顯示已安裝。

原因：版本 18 已註冊但無法載入，因此 mssql-django 會退回到未安裝的版本 17。備援機制回報的是它第二次嘗試的驅動程式，而不是失敗的那個驅動程式。

解決方法：安裝 libgssapi-krb5-2 並重建。請參考前面的自動移除備註，了解圖書館如何消失。

在容器中載入 pyodbc 模組時錯誤

徵兆：

django.core.exceptions.ImproperlyConfigured: Error loading pyodbc module: libodbc.so.2: cannot open shared object file: No such file or directory

原因：該映像檔沒有 unixODBC 執行時間。當 Django 載入該後端時，mssql-django 會匯入 pyodbc，因此這個錯誤在 mssql-python 流程中也會發生，也就是說，在嘗試任何連線之前就會出現。

解決方法：安裝 unixodbc （或 unixodbc-dev）。

MSSQL-Python 驅動程式無法載入

徵兆：

django.db.utils.OperationalError: Driver Error: Connection operation failed; DDBC Error: Failed to load the driver.

原因：隨附 mssql-python 的驅動程式需要 Kerberos 執行時函式庫，而 slim base 映像檔沒有這些函式庫。

解決方案：安裝 libkrb5-3 和 libgssapi-krb5-2。

PYODBC 未能在薄型映像上建構

徵兆：

error: command 'gcc' failed: No such file or directory

Or:

fatal error: sql.h: No such file or directory

解決方案：先安裝建置相依性，再進行 pip install：

RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc \
    g++ \
    unixodbc-dev

或者，使用多階段製作來保持最終影像的體積小：

# Build stage
FROM python:3.12-slim AS builder
RUN apt-get update && apt-get install -y --no-install-recommends gcc g++ unixodbc-dev
COPY requirements.txt .
RUN pip wheel --no-cache-dir --wheel-dir /wheels -r requirements.txt

# Runtime stage
FROM python:3.12-slim
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl gnupg2 unixodbc \
    && curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg \
    && curl -fsSL https://packages.microsoft.com/config/debian/12/prod.list > /etc/apt/sources.list.d/mssql-release.list \
    && apt-get update \
    && ACCEPT_EULA=Y apt-get install -y --no-install-recommends msodbcsql18 libgssapi-krb5-2 \
    && apt-get purge -y curl gnupg2 \
    && rm -rf /var/lib/apt/lists/*
COPY --from=builder /wheels /wheels
RUN pip install --no-cache-dir /wheels/*

容器無法連接到 SQL Server

徵兆：

django.db.utils.OperationalError: ('08001', '... TCP Provider: Error code 0x2749 ...')

多個原因與解決方案：

Docker Compose 服務名稱未被用作主機

使用 Docker Compose 時，請設 DB_HOST 為服務名稱（例如）， db而非 localhost127.0.0.1。

SQL Server 容器尚未準備好

SQL Server 容器啟動需要幾秒鐘。新增健康檢查或延遲啟動：

services:
  db:
    image: mcr.microsoft.com/mssql/server:2022-latest
    healthcheck:
      test: /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "$$MSSQL_SA_PASSWORD" -No -Q "SELECT 1" || exit 1
      # $$ escapes the $ sign in Docker Compose YAML
      interval: 10s
      retries: 10
      start_period: 10s
  web:
    depends_on:
      db:
        condition: service_healthy

港口映射衝突

如果主機上有其他 SQL Server 實例，請更改暴露的埠口（例如 1434:1433），並相應更新你的 Django 設定。

Azure SQL 暫時性錯誤復原

後端會mssql-django自動偵測 Azure SQL Database 與 Azure SQL 受控執行個體連線，方法是查詢 SERVERPROPERTY('EngineEdition')。在執行 Azure SQL 時，後端會因暫時錯誤（如暫時資源限制或短暫網路中斷）而重試連線。

你可以透過以下connection_retriesconnection_retry_backoff_time選項來調整這個行為：

"OPTIONS": {
    "driver": "ODBC Driver 18 for SQL Server",
    "connection_retries": 5,
    "connection_retry_backoff_time": 5,
},

這些設定僅適用於初始連線建立。後端不會重試失敗的查詢。如果連線建立後查詢因暫態錯誤失敗，該例外會傳播到你的應用程式程式碼。使用應用程式層級的重試邏輯（例如 django-retry-db 或自訂中介軟體）來提升查詢層級的韌性。

慢速查詢與計畫迴歸

這些問題通常需要伺服器端分析以及 Django 層級的查詢審查。

查詢變慢或開始超時

徵兆：

同一個查詢集會隨著時間變慢，或在部署、索引變更或統計資料更新後開始發生逾時。

多個原因與解決方案：

從內建的效能報告開始

對於 SQL Server 和 Azure SQL 受控執行個體，請在 SQL Server Management Studio 中開啟效能儀表板。對於 Azure SQL Database，請開啟 Query Performance Insight for Azure SQL Database。這些工具通常比臨時撰寫的 DMV 查詢更適合作為第一步，因為它們能迅速找出高成本查詢、等待情形及資源壓力。
計畫迴歸

使用查詢存放區找出慢速查詢，並檢查是否有多個方案。從 使用查詢存放區監視工作負載的最佳做法 中所述的 回歸查詢 和最耗用資源的查詢檢視開始。
執行計畫效率低下

開啟該語句的實際執行計畫，檢查是否有資料表或索引掃描、大金鑰查詢、雜湊溢出或不準確的列估計。背景請參見執行計畫概述。
錯誤的瓶頸被識別

如果查詢不受 CPU 限制，請使用查詢存放區等待統計和識別瓶頸，以區分 CPU、記憶體、磁碟 I/O、阻塞和連線壓力。
修正被套用在錯誤的層

施行最小有效的修正：新增或調整索引、更新統計、減少選取的欄位和列，或批次處理大型寫入。如果您需要緊急因應措施，DBA 可以在您修正根本原因的同時，暫時在查詢存放區中強制使用已知有效的執行計畫。

使用 dbshell 進行互動式查詢

Django 的 dbshell 管理指令會開啟一個連接到你的資料庫的互動式 SQL shell：

python manage.py dbshell

當您設定 Microsoft ODBC 驅動程式時，後端會使用 sqlcmd；當您使用 FreeTDS 時，則會使用 isql。確認該工具是否在您的 PATH 上：

Windows：sqlcmd包含在 SQL Server 工具中，或者你可以另外下載。
Linux 和 macOS：從 Microsoft 倉庫安裝mssql-tools18。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-09-29

疑難排解 mssql-django

連接問題

ODBC 驅動程式不在 pyodbc 路徑上

MSSQL-Python 拒絕連線選項

MSSQL-Python 相依關係太舊了

驅動程式 17 的備援不適用於 mssql-python

連線被拒

登入失敗

連線超時

移轉問題

原始 SQL 與 GROUP BY 問題

IndexError 在 GROUP BY 上，包含逃逸 %% 參數與實參數

NotImplementedError 對於 IntegerChoices 在原始 GROUP BY 查詢中

正則表達式查詢問題

__regex 或 __iregex 不回傳任何列

Cannot find ... dbo.REGEXP_LIKE

日期與時間問題

Now() 值會在 USE_TZ=True 時位移

AttributeError 呼叫 .explain() 時

無法更改 AutoField

重命名在外鍵限制下失敗

編碼問題

Unicode 編碼錯誤

FreeTDS 問題

host_is_server 錯誤

測試資料庫問題

無法建立使用管理身份的測試資料庫

測試環境中的身分驗證取捨

回退程序

Docker 與容器問題

貨櫃中找不到 ODBC 驅動程式

安裝版本 18 時，驅動程式 17 顯示遺失

在容器中載入 pyodbc 模組時錯誤

MSSQL-Python 驅動程式無法載入

PYODBC 未能在薄型映像上建構

容器無法連接到 SQL Server

Azure SQL 暫時性錯誤復原

慢速查詢與計畫迴歸

查詢變慢或開始超時

使用 dbshell 進行互動式查詢

相關內容

意見反應

其他資源

`IndexError` 在 GROUP BY 上，包含逃逸 `%%` 參數與實參數

`NotImplementedError` 對於 `IntegerChoices` 在原始 GROUP BY 查詢中

`regex` 或 `iregex` 不回傳任何列

`Cannot find ... dbo.REGEXP_LIKE`

`Now()` 值會在 `USE_TZ=True` 時位移

`AttributeError` 呼叫 `.explain()` 時