userver: MySQL Driver - EXPERIMENTAL
Loading...
Searching...
No Matches
MySQL Driver - EXPERIMENTAL

Disclaimer: current state of the driver is experimental, and although APIs are not likely to change drastically, some adjustments may be made in the future. Please also keep in mind that this driver is not backed by Yandex-scale production usage.

🐙 userver provides access to MySQL databases servers via components::MySQL. The uMySQL driver is asynchronous, and with it one can write queries like this:

struct Developer final {
std::string developer_id;
std::uint64_t lines_of_code_written{}; // uint64_t is generous :)
};
std::vector<Developer> best_developers =
cluster
->Execute(ClusterHostType::kPrimary,
"SELECT id, loc_written FROM Devs "
"ORDER BY loc_written DESC LIMIT ?",
3)
.AsVector<Developer>();
// your top 3 best devs are right here!

No macros, no meta-structs, no boilerplate, just your types used directly.
Interested? - read ahead.

Legal note

The uMySQL driver itself contains no derivative of any portion of the underlying LGPL2.1 licensed mariadb-connector-c library. However linking with mariadb-connector-c may create an executable that is a derivative of the mariadb-connector-c, while LGPL2.1 is incompatible with Apache 2.0 of userver. Consult your lawyers on the matter.
For the reasons above the uMySQL driver doesn't come with mariadb-connector-c linked in, and it becomes your responsibility to link with it and comply with the license.

Features

  • Connection pooling;
  • Binary protocol (prepared statements);
  • Transactions;
  • Read-only cursors;
  • Batch Inserts/Upserts (requires MariaDB 10.2.6+);
  • Variadic template statements parameters passing;
  • Statement result extraction into C++ types;
  • Mapping C++ types to native MySQL types;
  • Userver-specific types: Decimal64, Json;
  • Nullable for all supported types (via std::optional<T>);
  • Type safety validation for results extraction, signed vs unsigned validation, nullable vs not-nullable validation;
  • Seamless integration with userver infrastructure: configuring, logging, metrics etc.;

Planned Enhancements

  • TLS/SSL - not implemented yet, soon to come;
  • Automatic primary discovery - not implemented yet, might be implemented soon;
  • Compression - not implemented yet, may be implemented;
  • More fine grained configurations - including dynamic configs and exposure of wider spectrum of static settings - likely to be implemented soon

Runtime Requirements

Recommended version of libmariadb3 to link against is 3.3.4 or above, because there exists a very nasty bug prior to 3.3.4: CONC-622.
By default the driver will abort execution if put in situation leading to CONC-622, since there's no generally acceptable way to resolve it:
either leak memory or straight invoke double free.
However, if one is unable to bump libmariadb3 version to 3.3.4 or above and leaking in some hopefully rare cases is acceptable,
cmake variable USERVER_MYSQL_ALLOW_BUGGY_LIBMARIADB could be set to force the driver to leak memory instead of aborting in such cases.

More information