userver: userver/storages/mysql.hpp Source File
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
84USERVER_NAMESPACE_BEGIN
85
86/// @brief Top namespace for uMySQL driver.
87///
88/// For more information see @ref mysql_driver
89namespace storages::mysql {}
90
91/// @brief Namespace containing helper classes and functions for on-the-flight
92/// remapping DbType<->UserType
93namespace storages::mysql::convert {}
94
95USERVER_NAMESPACE_END