Error handling specifications for Oracle-compatible applications

This topic describes the error handling specifications for Oracle-compatible applications.

OceanBase Database V2.0 and later are fully compatible with Oracle Database and provide an Oracle tenant mode. OceanBase Database also strives to maintain consistency with Oracle Database in terms of error codes, SQLSTATE, and error messages. Therefore, according to our product design principles, application error handling can refer to Oracle Database's handling specifications. However, as a distributed database, OceanBase Database has fundamental differences from a standalone Oracle database, and some errors unique to distributed environments cannot be expressed using Oracle Database's error codes. Therefore, these internal error codes are mapped to OBE-00600, which indicates that they are unique to OceanBase Database.

In the Oracle mode of OceanBase Database, error codes are in the format of "prefix + number", which is the same as in Oracle Database. If an error originates from an SQL statement, the error code starts with OBE. If an error originates from a stored procedure, the error code starts with PLS. For more information about the error codes supported by the Oracle mode of OceanBase Database, see Overview of error messages.

For the error code OBE-00600, applications must extract the internal error code from the error message. For example, in the following error message, the internal error code is 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

Obtain error information

Drivers in different languages provide different APIs to obtain error information. For more information, see Drivers in Connection methods.

Java driver

When a Java application that uses JDBC fails to execute an SQL statement, an SQLException can be captured. The exception contains the error code, SQLSTATE value, and error message. For more information about SQLException, see JDBC API reference.

Methods for capturing an SQLException are as follows:

• Call the getErrorCode() method to obtain the error code.
• Call the getSQLState() method to obtain the SQLSTATE value.
• Call the getMessage() method to obtain the error message.

OBCI driver

OceanBase Call Interface (OBCI) provides a C language driver compatible with Oracle Call Interface (OCI). When a function call returns OCI_ERROR, the application obtains error information from the output parameters of the OCIErrorGet() function:

• Obtain the error code from the output parameter errcodep.
• Obtain the SQLSTATE value from the output parameter sqlstate.
• Obtain the error message from the output parameter bufp.

Error handling specifications

Most errors in the Oracle mode of OceanBase Database do not need to be handled by applications and can be directly returned. For fault tolerance and application robustness, the following four different strategies can be used for error handling based on the scenario and error type:

1. Strategy 1: Handle errors based on the statement type.

   • If a timeout error occurs during execution of a SELECT statement, the statement can be retried because the retry operation has no side effect.

   • If a timeout error occurs during remote or distributed execution of a modification statement such as UPDATE, the transaction must be rolled back because whether the statement is successfully executed is uncertain. If the statement is idempotent, it can be retried.

   • If a timeout error occurs during execution of a COMMIT or ROLLBACK statement, the error is directly returned because the transaction status is unknown.

2. Strategy 2: If an error occurs during execution of any statement, roll back the current transaction and then retry it.

3. Strategy 3: If an error occurs during execution of any statement, retry the current statement.

4. Strategy 4: If an error occurs during execution of any statement, close the current connection and then reestablish the connection.

Particularly, due to development conventions, many service applications developed through OCI use persistent connections. If a runtime exception occurs on a database server without being handled, services may not be automatically recovered. For such applications, errors must be handled by following the suggestions in Error codes specific to OceanBase Database and Oracle-compatible error codes.

Error codes specific to OceanBase Database

The following table describes common runtime error codes unique to OceanBase Database. Applications can handle such errors by using strategies suggested for corresponding error codes.

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

Oracle-compatible error codes

For general error codes that are compatible with Oracle Database, applications follow the same handling methods as those for Oracle Database. The following table describes common errors in the Oracle mode of OceanBase Database. Applications can handle these errors based on the strategies suggested in the following table.

For applications that use OBCI, the driver returns some Oracle-compatible error codes. Applications need to handle such errors by using the same methods as those for Oracle Database. In particular, applications need to pay attention to the following error codes.