soci/docs/errors.md

0001 # Errors
0002
0003 All DB-related errors manifest themselves as exceptions of type `soci_error`, which is derived from `std::runtime_error`.
0004 This allows to handle database errors within the standard exception framework:
0005
0006 ```cpp
0007 int main()
0008 {
0009     try
0010     {
0011         // regular code
0012     }
0013     catch (std::exception const & e)
0014     {
0015         cerr << "Bang! " << e.what() << endl;
0016     }
0017 }
0018 ```
0019
0020 The `soci_error` class exposes two public functions:
0021
0022 The `get_error_message() const` function returns `std::string` with a brief error message, without any additional information that can be present in the full error message returned by `what()`.
0023
0024 The `get_error_category() const` function returns one of the `error_category` enumeration values, which allows the user to portably react to some subset of common errors.
0025 For example, `connection_error` or `constraint_violation` have meanings that are common across different database backends, even though the actual mechanics might differ.
0026
0027 ## Portability
0028
0029 Error categories are not universally supported and there is no claim that all possible errors that are reported by the database server are covered or interpreted.
0030 If the error category is not recognized by the backend, it defaults to `unknown`.
0031
0032 ## MySQL
0033
0034 The MySQL backend can throw instances of the `mysql_soci_error`, which is publicly derived from `soci_error` and has an additional public `err_num_` member containing the MySQL error code (as returned by `mysql_errno()`):
0035
0036 ```cpp
0037 int main()
0038 {
0039     try
0040     {
0041         // regular code
0042     }
0043     catch (soci::mysql_soci_error const & e)
0044     {
0045         cerr << "MySQL error: " << e.err_num_
0046             << " " << e.what() << endl;
0047     }
0048     catch (soci::exception const & e)
0049     {
0050         cerr << "Some other error: " << e.what() << endl;
0051     }
0052 }
0053 ```
0054
0055 ## Oracle
0056
0057 The Oracle backend can also throw the instances of the `oracle_soci_error`, which is publicly derived from `soci_error` and has an additional public `err_num_` member containing the Oracle error code:
0058
0059 ```cpp
0060 int main()
0061 {
0062     try
0063     {
0064         // regular code
0065     }
0066     catch (soci::oracle_soci_error const & e)
0067     {
0068         cerr << "Oracle error: " << e.err_num_
0069             << " " << e.what() << endl;
0070     }
0071     catch (soci::exception const & e)
0072     {
0073         cerr << "Some other error: " << e.what() << endl;
0074     }
0075 }
0076 ```
0077
0078 ## PostgreSQL
0079
0080 The PostgreSQL backend can also throw the instances of the `postgresql_soci_error`, which is publicly derived from `soci_error` and has an additional public `sqlstate()` member function returning the five-character "SQLSTATE" error code:
0081
0082 ```cpp
0083 int main()
0084 {
0085     try
0086     {
0087         // regular code
0088     }
0089     catch (soci::postgresql_soci_error const & e)
0090     {
0091         cerr << "PostgreSQL error: " << e.sqlstate()
0092             << " " << e.what() << endl;
0093     }
0094     catch (soci::exception const & e)
0095     {
0096         cerr << "Some other error: " << e.what() << endl;
0097     }
0098 }
0099 ```