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

この記事を使って、 mssql-python 運転者向けのトラブルシューティングの指針を見つけてください。まずはあなたの問題に合う症状やエラーメッセージから始めてください。

インストールの問題

pip install が失敗する、またはソースからビルドされる

サポートされていないPythonバージョン、欠落したホイール、非アクティブな仮想環境、欠落したLinuxライブラリについては、「インストールおよび接続問題のトラブルシューティング」を参照してください。

競合するドライバーのインストール

mssql-pythonとpyodbcを同時にインストールした際のインポートエラーや予期しない動作については、「インストールおよび接続問題のトラブルシューティング」を参照してください。

接続に関する問題

サーバーに接続できません

SQLSTATE 08001、到達不能サーバー、停止したサービス、Azure SQLファイアウォールルールについては、「インストールおよび接続問題のトラブルシューティング」を参照してください。

SQLSTATE 28000、認証モードの不一致、無効な認証情報、欠如したデータベースユーザーについては、「インストールおよび接続問題のトラブルシューティング」を参照してください。

接続タイムアウト

SQLSTATE HYT00 または HYT01、ネットワークレイテンシ、遅いサーバー、接続タイムアウト設定については、「インストールおよび接続問題のトラブルシューティング」を参照してください。

SSL 証明書エラー

信頼できない証明書エラーや安全なローカル開発オプションについては、「インストールおよび接続の問題のトラブルシューティング」をご覧ください。

クエリ実行の問題

テーブルまたはオブジェクトが見つからない

SQLSTATE 42S02、データベースコンテキスト、スキーマ資格、テーブル存在確認については、「クエリ、データ、操作の問題のトラブルシューティング」を参照してください。

構文エラー

SQLSTATE 42000、SQL構文、文字列エスケープ、パラメータ化クエリについては、「クエリ、データ、操作の問題のトラブルシューティング」を参照してください。

パラメータ誤差

SQLSTATE 07001、プレースホルダー数、サポートされるパラメータスタイルについては、「クエリ、データ、操作の問題のトラブルシューティング」を参照してください。

データ型の問題

日付時変換エラー

SQLSTATE 22007 およびdatetimeパラメータ変換については、「クエリ、データ、操作の問題のトラブルシューティング」を参照してください。

十進精度の問題

切り詰められた小数点や丸められた小数点については、「クエリ、データ、操作の問題のトラブルシューティング」を参照してください。

Unicodeエンコーディングの問題点

歪んだ特殊文字やUnicodeの列タイプについては、「クエリ、データ、操作の問題のトラブルシューティング」を参照してください。

パフォーマンスの問題

クエリ実行の遅さ

インデックス作成、大規模な結果セット、接続プーリングについては、「クエリ、データ、操作の問題のトラブルシューティング」を参照してください。

大きな結果に対する記憶の問題

大規模な結果セットのストリーミングおよびページ付けについては、「トラブルシューティングクエリ、データ、運用問題」を参照してください。

取引に関する問題

オートコミットによる一時テーブルのスコーピング

ロールバック後に消える一時テーブルや自動コミットが必要なDDL文については、「クエリ、データ、操作の問題のトラブルシューティング」を参照してください。

トランザクションはコミットされていません

接続終了後も持続しないデータ変更については、「クエリ、データ、操作の問題のトラブルシューティング」を参照してください。

デッドロックエラー

SQLSTATE 40001、リトライガイダンス、繰り返しのデッドロック解析については、「クエリ、データ、操作の問題のトラブルシューティング」を参照してください。

一括読み込みの問題

バルクコピー中の制約違反

一括コピー中の主鍵、一意鍵、チェック鍵、または外部鍵の違反については、「クエリ、データ、操作の問題のトラブルシューティング」を参照してください。

列マッピングエラー

一括コピーのカラム数およびカラム順序の不一致については、「クエリ、データ、操作の問題のトラブルシューティング」をご覧ください。

一括コピー時のタイプミスマッチ

まとめコピー後の切り詰め、丸め、誤った値は「クエリ、データ、操作の問題のトラブルシューティング」を参照してください。

NumPy型のバインディング失敗

NumPyの整数またはfloat型でのパラメータバインディングの失敗については、「クエリ、データ、操作の問題のトラブルシューティング」を参照してください。

一時テーブルを使用した一括コピー

セッション一時テーブルでbulkcopy()を使う際のInvalid object nameエラーについては、「クエリ、データ、操作の問題のトラブルシューティング」をご覧ください。

コンテナおよびCIの問題

Linuxにおける欠落したシステムライブラリ

Linux環境で libltdl やKerberosライブラリが欠けている場合は、「インストールおよび接続問題のトラブルシューティング」をご覧ください。

インストール後のmacOS SSLエラー

macOSのSSL関連エラー(Apple Siliconを含む)については、「インストールおよび接続問題のトラブルシューティング」を参照してください。

診断ツール

ドライバーログを有効にする

mssql_python.setup_logging()を使ってDEBUGログを有効にしてください。ドライバはSQL文、パラメータ、内部ODBC操作、接続状態の変更を記録します。

import mssql_python

# Enable logging to file (default)
mssql_python.setup_logging()

# Output to stdout (useful for CI/CD and containers)
mssql_python.setup_logging(output="stdout")

# Output to both file and stdout
mssql_python.setup_logging(output="both")

# Custom log file path (must use .txt, .log, or .csv extension)
mssql_python.setup_logging(log_file_path="/var/log/myapp/mssql.log")

ログファイルはCSV形式を使用し、512MBで自動回転し、5つのバックアップがあります。ドライバーはパスワードやアクセストークンなどの機密データをログ出力でサニティ処理します。

ドライバーログにアプリケーションエントリを追加するには、 driver_loggerを使用します。

import mssql_python
from mssql_python.logging import driver_logger

mssql_python.setup_logging()

driver_logger.debug("[App] Starting data processing")
driver_logger.error("[App] Failed to process record")

Caution

ログ記録にはパフォーマンス上のオーバーヘッドがあります。問題を解決した時だけ有効にしてください。本番環境ではデフォルトで有効にしないでください。

ドライバー情報を取得する

アクティブな接続からドライバーのバージョンとサーバー情報を取得する:

import mssql_python

conn = mssql_python.connect(connection_string)

print(f"Version: {mssql_python.__version__}")
print(f"Server name: {conn.getinfo(mssql_python.SQL_SERVER_NAME)}")
print(f"Database name: {conn.getinfo(mssql_python.SQL_DATABASE_NAME)}")

接続の状態を確認する

接続がまだ開いているかどうかをテストするために軽量なクエリを実行します:

import mssql_python

try:
    cursor = conn.cursor()
    cursor.execute("SELECT 1")
    print("Connection is open")
except mssql_python.Error:
    print("Connection is closed or broken")

クイックリファレンス:よくある誤り

エラー	SQLSTATE	一般的な原因	トラブルシューティング
クライアントが接続を確立できない	`08001`	サーバーに到達できない	サーバーに接続できません
ログインに失敗しました	`28000`	資格情報が間違っています	ログイン失敗
タイムアウトの期限が切れました	`HYT00` または `HYT01`	スローネットワーク	[接続タイムアウト]
無効なオブジェクト名	`42S02`	誤った表またはスキーマ	テーブルまたはオブジェクトが見つからない
構文エラー	`42000`	SQL エラー	構文エラー
制約違反	`23000`	外部鍵または主鍵の違反	バルクコピー中の制約違反
デッドロック	`40001`	ロックの競合	デッドロックエラー

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-09-21