mssql-pythonのエラー処理とSQLSTATEコード

mssql-pythonドライバは、SQL ServerおよびAzure SQL向けの標準的な例外階層、一般的なエラー処理パターン、SQLSTATEコードマッピングを定義しています。

例外階層

mssql-pythonドライバは DB-API 2.0(PEP 249)例外階層に従っています:

Exception (builtins)
├── Warning
└── Error
    ├── InterfaceError
    └── DatabaseError
        ├── DataError
        ├── OperationalError
        ├── IntegrityError
        ├── InternalError
        ├── ProgrammingError
        └── NotSupportedError

ConnectionStringParseError (standalone, not part of hierarchy)

例外の説明

自分の状況に最も合った例外を見つけてください。 例えば、INSERT/UPDATE操作の制約違反をIntegrityErrorキャッチしたり、開発中のSQL構文問題をProgrammingError検知したりします。 基本 Error クラスはあくまで代替手段として利用してください。

基本的なエラー処理

データベースエラーを処理するためにtry-exunxブロックを使用します:

import mssql_python

try:
    conn = mssql_python.connect(connection_string)
    cursor = conn.cursor()
    cursor.execute("INSERT INTO Production.Product (Name) VALUES (%(name)s)", {"name": "Test"})
    conn.commit()
except mssql_python.IntegrityError as e:
    print(f"Constraint violation: {e}")
    conn.rollback()
except mssql_python.ProgrammingError as e:
    print(f"SQL syntax error: {e}")
except mssql_python.OperationalError as e:
    print(f"Connection or operational error: {e}")
except mssql_python.Error as e:
    print(f"Database error: {e}")
finally:
    if 'conn' in locals():
        conn.close()

接続を通じたアクセス例外

例外は接続インスタンスで検出できます:

try:
    cursor.execute("INVALID SQL")
except conn.ProgrammingError as e:
    print(f"Caught via connection: {e}")

エラーメッセージの構造

MSSQL-python例外オブジェクトは、ドライバーの Exception ベースクラスから得られる3つの属性を公開します。

try:
    cursor.execute("SELECT * FROM no_such_table;")
except mssql_python.ProgrammingError as exc:
    print(exc.driver_error)  # Base table or view not found
    print(exc.ddbc_error)    # [Microsoft][SQL Server]Invalid object name 'no_such_table'.
    print(exc)               # Driver Error: Base table or view not found; DDBC Error: ...

SQL Serverエンジンのエラー番号(208や40501など)は属性として公開されておらず、どちらの文字列にも確実に埋め込まれていません。 例外サブクラスとテキスト driver_error 分類。 Azure SQL スロットリングについては、Retry logic を参照してください。

SQLSTATE分類

mssql-pythonはODBCが返すSQLSTATEを使ってPython例外サブクラスとdriver_errorテキストの両方を選択します。 完全なSQLSTATE→例外マッピングはドライバーソースに exceptions.py されています。 次のセクションでは、SQL ServerおよびAzure SQLで最も頻繁に現れるSQLSTATEを挙げます。

接続エラー

mssql_python.connect()からの接続障害は他の接続障害と同様に、mssql_python.OperationalErrorを上げます。

import mssql_python

try:
    conn = mssql_python.connect(
        "Server=unreachable-server.database.windows.net;"
        "Database=<database>;"
        "Authentication=ActiveDirectoryDefault;"
        "Encrypt=yes"
    )
except mssql_python.OperationalError as e:
    print(f"Connection failed: {e.driver_error}")
    # e.driver_error: "Client unable to establish connection"

接続文字列エラー

接続文字列解析エラーは ConnectionStringParseErrorを発生させます:

try:
    conn = mssql_python.connect("Servr=localhost;")  # Typo
except mssql_python.ConnectionStringParseError as e:
    print(f"Invalid connection string: {e}")
    # Output: Unknown keyword 'Servr'

SQLSTATEコード参照

SQLSTATEコードは、エラー状態を識別するための5文字コードです。 最初の2文字はクラスを示し、最後の3文字はサブクラスを示します。 これらのコードを直接確認する必要はほとんどありません。 代わりに、適切なPython例外タイプ(「例外」欄に記載)を検出してください。 同じ例外タイプ内で特定のエラー条件を区別する必要がある場合、例えばデッドロック(40001)と一般的な接続障害(08S01)を区別するためにSQLSTATEコードを使用してください。

クラス00 - 成功した完成

クラス01 - 警告

クラス07 - 動的SQLエラー

クラス08 - 接続例外

クラス21 - 濃度違反

クラス22 - データ例外

クラス23 - 完全性制約違反

クラス24 - 無効カーソル状態

クラス25 - 無効な取引状態

クラス28 - 無効な認可仕様

クラス34 - カーソル名が無効です

クラス3C - 重複カーソル名

クラス3D - カタログ名が無効です

クラス3F - スキーマ名が無効です

クラス40 - トランザクションロールバック

クラス42 - 構文エラーまたはアクセスルール違反

クラス44 - チェックオプション違反

クラスHY - CLI特有疾患

クラスIM - ドライバーマネージャーエラー

一般的なSQL Serverエラー番号

SQLSTATE以外にも、SQL Serverはカッコ内にネイティブのエラー番号を提供します。 これらはアプリケーションコードで最も遭遇しやすいエラーです。 リトライロジックはエラー1205(デッドロック)と一時的な接続エラー( リトライロジック参照)を中心に構築します。

症状から例外へのクイック参照

この表を使って、よくある症状を検出すべき例外タイプにマッピングします:

ベスト プラクティス

• 一般的な例外よりも、具体的な例外を優先してください。 最も具体的(IntegrityError)から最も具体的でない(Error)順に並べます。
• データ改変操作には必ずIntegrityErrorを処理してください。 制約違反は通常の動作(例えば、ユーザーが重複ユーザー名を作成しようとするなど)で予想されます。
• トラブルシューティングのために、エラーの全文脈を記録してください。 例外は driver_error (安定的、SQLSTATE由来のテキスト)と ddbc_error (サーバー側メッセージ)を公開します。 両方記録してください;分類は driver_error。
• 一時的なエラー(接続障害、デッドロック)に対してリトライロジックを実装します。 リ トライロジックを参照してください。
• 例外ハンドラでrollback()を使って失敗したトランザクションをクリーンアップします。 明示的なロールバックがなければ、接続はトランザクション失敗状態のままです。

関連するコンテンツ

• トラブルシューティング ガイド
• クエリの実行
• 接続管理