mssql-django のトラブルシューティング

Microsoft FabricのSQL Server、Azure SQL Database、Azure SQL Managed Instance、および 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

または:

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

考えられる原因と解決策:

ODBC ドライバーがインストールされていません

デフォルトのpyodbcパスを使う場合は、Microsoft ODBCドライバーをSQL Server用にインストールしてください。ダウンロードリンクについては、「ODBC Driver for SQL Server のダウンロード」を参照してください。 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 connection-string キーワードを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、 MARS_Connection、そして LongAsMax、 ColumnEncryption、 WSID、 AnsiNPW、 QuotedId、 Regional、 UseFMTONLY、 Current Language、 Network Library、 Description、 Connect Timeout などのpyodbc専用キーワードは許可リストに含まれず、 Unknown keyword フォームを生成します。キーワードを削除するか、そのODBCオプションが必要なエイリアスにはデフォルトのpyodbcパスを使うことができます。
mssql-pythonを制御するドライバーオプションが期待されています

mssql-pythonのパスは driver、 dsn、 host_is_server、 unicode_resultsを無視します。 HOSTそしてPORTSERVER=<server>,<port>になり、空虚なHOSTがlocalhostになる。

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"'.

2番目のフォームは、 mssql_python モジュールが全くインポートできないことを意味します。

解決策: mssql-python>=1.15.0をインストールしましょう。 mssql-django 2.0では mssql-python>=1.15.0を宣言しているため、通常の pip install mssql-django は対応プラットフォーム上で互換性のあるバージョンを解決します。

ドライバー17のフォールバックはmssql-pythonには適用されません

症状:

"python_driver": "mssql_python" を設定するエイリアスは、Microsoft ODBC Driver 17 for SQL Server がインストールされていても、依然として失敗します。

このケースには特有の誤りはありません。 mssql-pythonパスは driver オプションを無言で無視するため、接続は何らかの根本的なエラーで失敗します。ドライバー名を extra_params に移動すると Reserved keyword 'driver' エラーが出ます。 mssql-pythonは接続オプションを拒否します。

解決策:エイリアスが外部にインストールされたODBCドライバー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 ポータルのファイアウォール設定にクライアント 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 および Auto-pause and auto-resume をご覧ください。

サーバーのオーバーロード

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

移行に関する問題

これらのエラーは、SQL Serverに対する Django の移行操作中に発生します。

生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 のみに絞り込み、エスケープ %% リテラルは逐語的に保持され、ファントムプレースホルダーは注入されません。

生の GROUP BEY クエリの `IntegerChoices` 用 `NotImplementedError`

症状:

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

同じ列挙値はORMクエリや GROUP BYなしの生クエリで動作しますが、 GROUP BY 節を含む生クエリにパラメータとして渡されると失敗します。

解決策:最新の mssql-django リリースにアップグレードする。バックエンドはGROUP BYパスのパラメータ型チェックに isinstance を用いているため、IntegerChoices(intサブクラス)が正しくバインドされます。 bool は依然として ビット にバインドされ、通常の 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バージョンのメタデータを説明します。

自動フィールドを変更できません

症状:

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経路でpyodbcSQL 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は、MicrosoftのODBCドライバーとは異なるpyodbc特有の設定を必要とします。

host_is_server エラー

症状:

host_is_serverを指定せずに FreeTDS を使用すると、接続が失敗します。

解決策: FreeTDS を使用するときに host_is_server を True に設定します。

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

FreeTDS 構成の詳細については、「 mssql-django の接続オプション」を参照してください。

データベースの問題をテストする

認証方法によっては、データベースの作成と破棄のテストが失敗する可能性があります。

マネージド ID を使用してテストデータベースを作成できない

症状:

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

または:

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

ActiveDirectoryMsi (マネージド ID) 認証を使用すると、テストランナーはテストデータベースの作成または破棄に失敗します。この制限は次の理由で存在します。

マネージド ID 資格情報は、ホスト環境 (Azure VM や App Service など) から取得されます。
テストランナーは、ティアダウン中に test データベースの認証情報を使用して接続しようとします。
マネージド ID にはデータベースレベルのロールを付与できますが、通常、テストデータベースの作成と削除には、テストランナーにはないサーバーレベルのアクセス許可が必要です。

影響を受ける認証方法:

ActiveDirectoryMsi(マネージド ID Azure)
ActiveDirectoryServicePrincipal (サーバースコープでのみ構成されている場合)

サポートされている認証方法 (データベースの作成のテスト機能):

ActiveDirectoryPassword
ActiveDirectoryIntegrated
SQL 認証 (ユーザー名/パスワード)

テスト環境の認証のトレードオフ

Method	シークレット不要	自動テスト用DBの作成/削除に対応	一般的な使用方法
`ActiveDirectoryMsi`	Yes	通常、いいえ (サーバーレベルの権限が付与されていない場合)	Azureホスト型運用ワークロード
`ActiveDirectoryServicePrincipal`	いいえ (クライアントシークレット/証明書)	付与されたサーバーレベルの権限に依存	明示的な ID 管理を使用した CI/CD
`ActiveDirectoryPassword`	No	はい (十分な SQL アクセス許可を持つ)	開発者および制御された CI 環境
SQL 認証	No	はい (十分な SQL アクセス許可を持つ)	ローカルまたは分離されたテスト環境

解決策:

開発用: --keepdb フラグを使用して、テストデータベースの破棄をスキップします。
```
python manage.py test --keepdb
```

CI/CD パイプラインの場合: 専用のテストデータベースを事前に作成し、マネージド ID に 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 に切り替えます。

ロールバックプロシージャ

移行が途中で失敗した場合は、次のロールバックシーケンスを使用して既知の正常な状態に戻ります。

アプリケーションの書き込みを停止して、スキーマの誤差を回避します。

移行状態を検査する:

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ドライバーのインストールはありませんが、Djangoが読み込むとバックエンドがpyodbcを取り込むため、unixODBCランタイムは必要です。

コンテナーに ODBC ドライバーが見つかりません

症状:

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

考えられる原因と解決策:

コンテナーイメージに ODBC ドライバーがインストールされていない

スリムまたは Alpine の基本イメージには、ODBC ドライバーは含まれません。 pyodbcを使うときはMicrosoft APTリポジトリを追加し、Dockerファイルにmsodbcsql18をインストールしてください。完全な Dockerfile の例については、「 App Service へのデプロイ」を参照してください。
unixodbc-dev パッケージがありません

pyodbc ホイールは、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にフォールバックします。フォールバックは、失敗したドライバーではなく、2番目に試したドライバーを報告します。

解決策: 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のランタイムがありません。 mssql-djangoは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ランタイムライブラリが必要で、スリムベースイメージには含まれていません。

解決策: libkrb5-3 と libgssapi-krb5-2を設置する。

pyodbc がスリムイメージでビルドできない

症状:

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

または:

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ではなく、サービス名 (localhost など) に127.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 バックエンドは、SERVERPROPERTY('EngineEdition')のクエリを実行して、接続のAzure SQL DatabaseとAzure SQL Managed Instanceを自動的に検出します。 Azure SQLに対して実行すると、バックエンドは一時的なエラー (一時的なリソースの制限や短いネットワークの中断など) で接続を再試行します。

この動作は、 connection_retries オプションと connection_retry_backoff_time OPTIONS を使用して調整できます。

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

これらの設定は、最初の接続確立にのみ適用されます。バックエンドは失敗したクエリを再試行しません。接続が確立された後にクエリが一時的なエラーで失敗した場合、例外はアプリケーションコードに反映されます。クエリレベルの回復性には、アプリケーションレベルの再試行ロジック ( django-retry-db やカスタムミドルウェアなど) を使用します。

低速クエリとプラン回帰

通常、これらの問題には、Django レベルのクエリレビューと共にサーバー側の分析が必要です。

クエリの速度が低下するか、タイムアウトを開始する

症状:

同じクエリセットが時間の経過と同時に遅くなったり、デプロイ、インデックスの変更、統計の更新後にタイムアウトが開始されたりします。

考えられる原因と解決策:

組み込みのパフォーマンスレポートから始める

SQL ServerとAzure SQL Managed Instanceの場合は、SQL Server Management Studioでパフォーマンスダッシュボードを開きます。 Azure SQL Databaseの場合は、Azure SQL Databaseの Query Performance Insight を開きます。これらのツールは、コストの高いクエリ、待機、リソースの負荷をすばやく表示するため、通常、アドホック DMV クエリよりも優れた最初の手順です。
回帰を計画する

クエリストアを使用して低速クエリを検索し、複数のプランがあるかどうかを確認します。『クエリストアを使用したワークロードの監視のベストプラクティス』で説明されている 性能が低下したクエリ ビューと最も多くのリソースを消費するクエリビューから始めます。
非効率的な実行プラン

ステートメントの実際の実行プランを開き、テーブルまたはインデックスのスキャン、大きなキー参照、ハッシュスピル、または不正確な行の見積もりを確認します。背景については、「実行プランの概要」を参照してください。
間違ったボトルネックが特定されました

クエリが CPU にバインドされていない場合は、クエリストア待機統計を使用し、CPU、メモリ、ディスク I/O、ブロック、接続の負荷を区別するためのボトルネックを特定します。
間違ったレイヤーで適用される修正

最小の効果的な修正を適用します。インデックスの追加または調整、統計の更新、選択した列と行の削減、大規模な書き込みのバッチ処理などです。緊急対応策が必要な場合、根本原因を修正しながら、DBA はクエリストアで既知の適切な計画を一時的に強制できます。

対話型クエリに dbshell を使用する

Django の dbshell 管理コマンドは、データベースに接続された対話型 SQL シェルを開きます。

python manage.py dbshell

バックエンドは、Microsoft ODBC ドライバーを構成するときにsqlcmdを使用するか、FreeTDS を使用するときにisqlします。ツールがパス上にあるかどうかを確認します。

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 と実パラメーター

生の GROUP BEY クエリの IntegerChoices 用 NotImplementedError

正規表現の検索問題

__regex または __iregex 行を返さない

Cannot find ... dbo.REGEXP_LIKE

日付と時刻の問題

Now() 値は、次の場合にシフトされます。 USE_TZ=True

AttributeError .explain() の呼び出し時

自動フィールドを変更できません

外部キー制約で名前の変更が失敗する

エンコードの問題

Unicode エンコード エラー

FreeTDS の問題

host_is_server エラー

データベースの問題をテストする

マネージド ID を使用してテスト データベースを作成できない

テスト環境の認証のトレードオフ

ロールバック プロシージャ

Docker とコンテナーの問題

コンテナーに ODBC ドライバーが見つかりません

バージョン18をインストールした際にドライバー17が存在しなかったと報告されました

コンテナにpyodbcモジュールを読み込む際のエラー

MSSQL-Pythonドライバーの読み込みに失敗します

pyodbc がスリム イメージでビルドできない

コンテナーがSQL Serverに接続できない

Azure SQL一時的なエラー復旧

低速クエリとプラン回帰

クエリの速度が低下するか、タイムアウトを開始する

対話型クエリに dbshell を使用する

関連するコンテンツ

フィードバック

その他のリソース

エスケープされた `%%` を使用する `IndexError` の GROUP BY と実パラメーター

生の GROUP BEY クエリの `IntegerChoices` 用 `NotImplementedError`

`regex` または `iregex` 行を返さない

`Cannot find ... dbo.REGEXP_LIKE`

`Now()` 値は、次の場合にシフトされます。 `USE_TZ=True`

`AttributeError` `.explain()` の呼び出し時

Unicode エンコードエラー

マネージド ID を使用してテストデータベースを作成できない

ロールバックプロシージャ

pyodbc がスリムイメージでビルドできない