userver
C++ Async Framework
Loading...
Searching...
No Matches
mysql.hpp
Go to the documentation of this file.
1
#
pragma
once
2
3
/// @file userver/storages/mysql.hpp
4
/// This file is mainly for documentation purposes and inclusion of all headers
5
/// that are required for working with MySQL µserver component.
6
7
#
include
<
userver
/
storages
/
mysql
/
cluster
.
hpp
>
8
#
include
<
userver
/
storages
/
mysql
/
component
.
hpp
>
9
#
include
<
userver
/
storages
/
mysql
/
cursor_result_set
.
hpp
>
10
#
include
<
userver
/
storages
/
mysql
/
exceptions
.
hpp
>
11
12
// clang-format off
13
/// @page mysql_driver MySQL Driver - EXPERIMENTAL
14
///
15
/// **Disclaimer**: current state of the driver is experimental, and
16
/// although APIs are not likely to change drastically, some adjustments may be
17
/// made in the future.
18
/// Please also keep in mind that this driver is
19
/// not backed by Yandex-scale production usage.
20
///
21
/// 🐙 **userver** provides access to MySQL databases servers via
22
/// components::MySQL. The uMySQL driver is asynchronous, and with it one can
23
/// write queries like this:
24
/// @snippet storages/tests/unittests/showcase_mysqltest.cpp uMySQL usage sample - main page
25
/// No macros, no meta-structs, no boilerplate, just your types used directly. <br>
26
/// Interested? - read ahead.
27
///
28
/// @section legal Legal note
29
/// The uMySQL driver itself contains no derivative of any portion of the underlying
30
/// <a href="https://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html">LGPL2.1 licensed</a>
31
/// <a href = "https://github.com/mariadb-corporation/mariadb-connector-c">mariadb-connector-c</a> library.
32
/// However linking with `mariadb-connector-c` may create an executable that is
33
/// a derivative of the `mariadb-connector-c`, while `LGPL2.1` is incompatible
34
/// with `Apache 2.0` of userver. Consult your lawyers on the matter. <br>
35
/// For the reasons above the uMySQL driver doesn't come with
36
/// `mariadb-connector-c` linked in, and it becomes your responsibility to
37
/// link with it and comply with the license.
38
///
39
/// @section features Features
40
/// - Connection pooling;
41
/// - Binary protocol (prepared statements);
42
/// - Transactions;
43
/// - Read-only cursors;
44
/// - Batch Inserts/Upserts (requires MariaDB 10.2.6+);
45
/// - Variadic template statements parameters passing;
46
/// - Statement result extraction into C++ types;
47
/// - Mapping C++ types to native MySQL types;
48
/// - Userver-specific types: Decimal64, Json;
49
/// - Nullable for all supported types (via std::optional<T>);
50
/// - Type safety validation for results extraction, signed vs unsigned
51
/// validation, nullable vs not-nullable validation;
52
/// - Seamless integration with userver infrastructure: configuring, logging,
53
/// metrics etc.;
54
///
55
/// @section enhancements Planned Enhancements
56
/// - TLS/SSL - not implemented yet, soon to come;
57
/// - Automatic primary discovery - not implemented yet,
58
/// might be implemented soon;
59
/// - Compression - not implemented yet, may be implemented;
60
/// - More fine grained configurations - including dynamic configs and exposure
61
/// of wider spectrum of static settings - likely to be implemented soon
62
///
63
/// @section requirements Runtime Requirements
64
/// Recommended version of libmariadb3 to link against is 3.3.4 or above,
65
/// because there exists a very nasty bug prior to 3.3.4: <a href="https://jira.mariadb.org/projects/CONC/issues/CONC-622">CONC-622</a>.<br>
66
/// By default the driver will abort execution if put in situation leading to
67
/// <a href="https://jira.mariadb.org/projects/CONC/issues/CONC-622">CONC-622</a>,
68
/// since there's no generally acceptable way to resolve it: <br>
69
/// either leak memory or straight invoke double free.<br>
70
/// However, if one is unable to bump libmariadb3 version to 3.3.4 or above and
71
/// leaking in some hopefully rare cases is acceptable, <br>cmake variable
72
/// `USERVER_MYSQL_ALLOW_BUGGY_LIBMARIADB` could be set to force the driver
73
/// to leak memory instead of aborting in such cases.
74
///
75
/// @section info More information
76
/// - For configuring see storages::mysql::Component
77
/// - For cluster operations see storages::mysql::Cluster
78
/// - For C++ <-> MySQL mapping see @ref scripts/docs/en/userver/mysql/supported_types.md
79
/// - For typed extraction of statements results into C++ types see
80
/// storages::mysql::StatementResultSet
81
/// - For high-level design and implementation details see @ref scripts/docs/en/userver/mysql/design_and_details.md
82
// clang-format on
83
84
USERVER_NAMESPACE_BEGIN
85
86
/// @brief Top namespace for uMySQL driver.
87
///
88
/// For more information see @ref mysql_driver
89
namespace
storages
::
mysql
{}
90
91
/// @brief Namespace containing helper classes and functions for on-the-flight
92
/// remapping DbType<->UserType
93
namespace
storages
::
mysql
::
convert
{}
94
95
USERVER_NAMESPACE_END
userver
storages
mysql.hpp
Generated on Wed May 15 2024 22:27:42 for userver by
Doxygen
1.10.0