mirror of
https://github.com/boostorg/mysql.git
synced 2025-05-12 14:11:41 +00:00
ed007e31ae
Added support for running stored procedures that SELECT data Added support for running multiple semicolon-separated queries Added support for running stored procedures with OUT params Added resultset and resultset_view Fixed documentation typos and wording Refactored object creation in tests Close #133 Close #132 Close #8
110 lines
4.1 KiB
Plaintext
110 lines
4.1 KiB
Plaintext
[/
|
|
Copyright (c) 2019-2023 Ruben Perez Hidalgo (rubenperez038 at gmail dot com)
|
|
|
|
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
|
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
|
]
|
|
|
|
[section:error_handling Error handling and available overloads]
|
|
|
|
This section describes the different error handling strategies
|
|
you may use with this library, as well as the different overloads
|
|
available for each function involving network transfers.
|
|
|
|
This library uses Boost.System error codes and exceptions,
|
|
like Asio and Beast. Some server-reported errors may include additional
|
|
diagnostics information. For example, if you issue a query
|
|
and one of the referenced fields does not exist, the server will return
|
|
an error message indicating which was the offending field. This library
|
|
makes these diagnostics available through the following classes and
|
|
functions:
|
|
|
|
[variablelist
|
|
[
|
|
[[reflink diagnostics]]
|
|
[
|
|
An object containing this extra diagnostic information
|
|
about an error. [refmem diagnostics server_message] contains the server-generated error
|
|
string, if any.
|
|
]
|
|
]
|
|
[
|
|
[[reflink error_with_diagnostics]]
|
|
[
|
|
An exception that inherits from `boost::system::system_error`
|
|
that contains a `diagnostics` object.
|
|
]
|
|
]
|
|
[
|
|
[[reflink throw_on_error]]
|
|
[A utility function to check an `error_code` and throw an `error_with_diagnostics` if the operation failed.]
|
|
]
|
|
]
|
|
|
|
Every piece of functionality involving network transfers is offered in four versions:
|
|
|
|
* [*Synchronous with exceptions]. When they fail, they throw an [reflink error_with_diagnostics] exception.
|
|
* [*Synchronous with [reflink error_code] and [reflink diagnostics]]. These functions output an `error_code` and a `diagnostics`
|
|
object by lvalue reference to report failures.
|
|
* [*Asynchronous, without `diagnostics`]. When they fail, they call the completion handler with a non-empty `error_code`.
|
|
* [*Asynchronous, with `diagnostics`]. They have a `diagnostics&` parameter before the `CompletionToken`.
|
|
When they fail, they set the `diagnostics` parameter to any server-provided
|
|
diagnostic information, if available, and then call the completion handler with a non-empty `error_code`.
|
|
|
|
[heading Types of errors]
|
|
|
|
This library defines the following types of errors:
|
|
|
|
[table
|
|
[
|
|
[Type of error]
|
|
[Values contained in...]
|
|
[Error category]
|
|
[Description]
|
|
]
|
|
[
|
|
[Client errors]
|
|
[[reflink client_errc] enum]
|
|
[[reflink get_client_category]]
|
|
[Failures detected by Boost.MySQL, like corrupt messages.]
|
|
]
|
|
[
|
|
[Common server errors]
|
|
[[reflink common_server_errc] enum]
|
|
[[reflink get_common_server_category]]
|
|
[
|
|
Errors reported by the server, common to both MySQL and MariaDB.
|
|
No new codes will be added here, since the two DBs are currently developed independently.
|
|
]
|
|
]
|
|
[
|
|
[MySQL-specific server errors]
|
|
[Integer codes in [br][include_file boost/mysql/mysql_server_errc.hpp]]
|
|
[[reflink get_mysql_server_category]]
|
|
[
|
|
Errors reported by the server, specific to MySQL. New codes will be added in the future.
|
|
]
|
|
]
|
|
[
|
|
[MariaDB-specific server errors]
|
|
[Integer codes in [br][include_file boost/mysql/mariadb_server_errc.hpp]]
|
|
[[reflink get_mariadb_server_category]]
|
|
[
|
|
Errors reported by the server, specific to MariaDB. New codes will be added in the future.
|
|
]
|
|
]
|
|
]
|
|
|
|
Note that new codes are added frequently, so server-specific codes
|
|
are represented as integers, instead of enums.
|
|
|
|
[heading Security notes on diagnostics]
|
|
|
|
The error message given by [refmem diagnostics server_message] [*may contain user-provided input,
|
|
and should be treated as untrusted]. For certain errors, the MySQL server will include the offending
|
|
field names and values, which may contain arbitrary input. Please use with caution.
|
|
|
|
This message may contain non-ASCII characters. It's encoded using the connection's character set.
|
|
|
|
[endsect]
|