Oracle互換アプリケーションエラー処理規範

この記事では、主にOracle互換アプリケーションのエラー処理規範について説明します。

OceanBaseデータベースは、バージョンV2.0からOracleデータベースとの完全な互換性があり、Oracle互換のテナントモードを提供しています。エラーコードについては、エラーコード、SQLSTATE、エラーメッセージなどの3つの情報においてOracleデータベースとの一貫性を可能な限り保証しています。そのため、当社のプロダクト設計原則に基づき、アプリケーションのエラー処理方法はOracleデータベースの処理規範を参考にすることができます。ただし、分散データベースとして、OceanBaseデータベースは集中型のOracleデータベースと本質的に異なるため、分散環境特有の一部のエラーはOracleデータベースのエラーコードでは表現できません。このため、これらの内部エラーコードはエラーコード OBE-00600 にマッピングされ、これがOceanBaseデータベース固有のエラーコードであることを示しています。

OceanBaseデータベースのOracleテナントモードでは、エラーメッセージの形式はOracleデータベースと互換性があり、「プレフィックス + 数値エンコード」の形式で返されます。エラーがSQLに起因する場合は ORA で始まるエラーメッセージが返され、エラーがストアドプロシージャに起因する場合は PLS で始まるエラーメッセージが返されます。OceanBaseデータベースサーバーのOracleテナントモードでの完全なエラーコード一覧については、エラー情報の概要を参照してください。

OBE-00600 エラーコードについては、アプリケーションプログラムはエラーメッセージから具体的な内部エラーコードを抽出する必要があります。例えば、以下のエラーメッセージでは、内部エラーコードは 6210 です。

OBE-00600: internal error code, arguments: -6210, Transaction timeout occurred, please rollback the transaction, set the variable ob_trx_timeout to a larger value and then restart the transaction

エラーコード情報の取得

各言語のドライバープログラムは、エラー情報を取得するための異なるAPIを提供しています。各ドライバーの詳細な説明については、接続方式の概要 の ドライバー セクションを参照してください。

Javaドライバーライブラリ

JDBCを使用するJavaアプリケーションプログラムがSQLステートメントの実行に失敗した場合、SQLException例外をキャッチすることができます。この例外には、エラーコード、SQLSTATE、エラーメッセージの3つの情報が含まれています。SQLException例外の詳細については、JDBC APIドキュメントを参照してください。

SQLException例外をキャッチする方法は以下のとおりです：

• getErrorCode()を呼び出してエラーコードを取得する
• getSQLState()を呼び出してSQLSTATEを取得する
• getMessage()を呼び出してエラーメッセージを取得する

OBCIドライバーライブラリ

OBCIは、Oracle OCI互換のC言語ドライバーライブラリを提供しています。関数呼び出しが OCI_ERROR を返した場合、アプリケーションプログラムは関数 OCIErrorGet() の出力パラメータを通じてエラー情報を取得します：

• 出力パラメータerrcodepを通じてエラーコードを取得する
• 出力パラメータsqlstateを通じてSQLSTATEを取得する
• 出力パラメータbufpを通じてエラーメッセージを取得する

エラー処理規範

OceanBaseデータベースのOracleテナントモードにおける大部分のエラーコードについて、アプリケーションプログラムは特別な処理を行う必要がなく、直接外部にエラーを報告することができます。 フォールトトレランスとアプリケーションプログラムの堅牢性を向上させるため、特定のエラーコードについては、異なるシナリオやエラーの性質に応じて、以下の4つの異なるポリシーを採用できます：

1. ポリシー1：ステートメントのタイプに基づいて処理を行います。

   • SELECT ステートメントの実行時にタイムアウトエラーが発生した場合、副作用がないため、リトライが可能です。

   • リモートまたは分散実行による UPDATE などの更新ステートメントでタイムアウトエラーが発生した場合、ステートメントが実際に実行されたかどうかは不確定であり、トランザクションをロールバックする必要があります（更新ステートメントのセマンティクスが冪等である場合、そのステートメントをリトライできます）。

   • COMMIT または ROLLBACK ステートメントの実行時にタイムアウトエラーが発生した場合、トランザクションの状態が不明であるため、直接外部にエラーを報告する必要があります。

2. ポリシー2：任意のステートメント実行でエラーが発生した場合、現在のトランザクションをロールバックしてから、トランザクションをリトライします。

3. ポリシー3：任意のステートメント実行でエラーが発生した場合、現在のステートメントをリトライします。

4. ポリシー4：任意のステートメント実行でエラーが発生した場合、現在の接続を閉じてから、接続を再確立します。

特に、開発習慣により、OCIインターフェースを使用して開発されたサービス系アプリケーションの多くは長時間接続を使用します。データベースサーバーでランタイム例外が発生し、処理を行わない場合、サービスが自動復旧できない可能性があります。このようなアプリケーションについては、以下の OceanBaseデータベース固有のエラーコードとOracle互換エラーコード の推奨に従ってエラー処理を行う必要があります。

OceanBaseデータベース固有のエラーコード

以下のエラーコードは、一般的なOceanBaseデータベースサーバー固有のランタイム例外のエラーコードです。「内部エラーコード」に応じて、アプリケーションプログラムは「処理ポリシー」の推奨に従って処理することができます。

OBE-00600: internal error code, arguments: %d

Oracle互換エラーコード

一般的なOracleデータベース互換のエラーコードについては、Oracleデータベースと同じ処理方式を遵守してください。特に、以下の一部のエラーコードはOceanBaseデータベースのOracleテナントモードでの一般的な例外であり、アプリケーションプログラムは下表の「処理ポリシー」の推奨に従って処理することができます。

OBCIを使用したアプリケーションプログラムについては、ドライバー側で一部のOracleデータベース互換のエラーコードが返されます。これらもOracleデータベースと同じ処理方式を遵守します。特に、アプリケーションプログラムは以下のエラーコードに注意する必要があります。