Introduction

Motivation

MySQL and MariaDB are widespread SQL database servers. MySQL clients connect to the server in order to issue SQL queries. For this purpose, MySQL employs a dedicated protocol. Boost.MySQL is an implementation of the client side of this protocol.

This library is a full implementation of the MySQL client/server protocol. It aims to expose the protocol primitives in an efficient but easy-to-use way. It is similar in scope to the official libmysqlclient, but interoperable with Asio, safer and more expressive. Note that Boost.MySQL does not use libmysqlclient: it's a full implementation of the MySQL protocol, which makes it natively compatible with Asio.

This library is relatively low level. It gives you access to text SQL queries and prepared statements. Don't expect an ORM. This section presents a quick tour over the main library capabilities.

The design goals of this library are:

Interoperability with Asio: this library employs the same principles as Boost.Asio and Boost.Beast. Users of any of these libraries will immediately understand Boost.MySQL, and will have it easy to integrate it in their programs.
Basis for further abstraction: it allows efficient access to the MySQL client/server protocol so it can be used by higher level components as a building block. Do a single thing and do it well.
Efficiency.
Ease of use: the MySQL protocol is full of pitfalls. We believe in simplicity. While retaining control over the important parts, the library hides as much complexity from the protocol as possible.

Non-goals:

Being an ORM.
Being a SQL query generator. The library doesn't focus on utilities to generate queries. Don't expect syntax sugar like table("orders").select(["id", "quantity"]).where("id", 42).
Portability to other SQL databases. This library focuses on MySQL. It won't work with Postgres or SQLite.

When to use

If any of the following statements is true, you may consider using Boost.MySQL:

Your application uses Boost.Asio and you need to access a MySQL server.
You need asynchronous access to a MySQL server from a C++ application.
You need efficient access to a MySQL server from a C++ application.
You need a BSL-licensed library to access your MySQL server.
You are writing a higher-level database access library, like an ORM.

Use cases may include web servers, ETL processes and IoT systems.

It may not be a good fit for you if:

You only need synchronous access to a MySQL server and efficiency doesn't matter to your application. The official client libraries may be better suited for you, in this case.
You need homogeneous SQL access to different SQL databases (and not only MySQL access). You may find more value in using sqlpp11 or a similar wrapper library.

Requirements

Boost.MySQL requires:

C++11 capable compiler. Tested with:
- gcc 5.4 (Linux)
- gcc 6.5 (Linux)
- gcc 10.3 (Linux)
- gcc 11.2 (Linux)
- clang 3.6 (Linux)
- clang 7.0 (Linux)
- clang 11.0 (Linux)
- clang 12.0 (Linux)
- clang 13.0 (OSX)
- MSVC 19.25 (Windows)
Boost. Boost.MySQL does not work with the standalone version of Boost.Asio.
OpenSSL.

Boost.MySQL is a header-only library. The following additional libraries are needed at link time:

OpenSSL is always required.
Boost.Context is required when using coroutines created by boost::asio::spawn.

If you are using CMake with a Boost distribution (e.g. one you downloaded and built with b2), you can use the following code to get the required setup:

project(boost_mysql_example LANGUAGES CXX)

find_package(Boost REQUIRED COMPONENTS headers)
find_package(Threads REQUIRED)
find_package(OpenSSL REQUIRED)

add_executable(main main.cpp)
target_link_libraries(main PRIVATE Boost::headers Threads::Threads OpenSSL::Crypto OpenSSL::SSL)

Boost.MySQL has been tested with the following RDBMS systems:

MySQL v5.7.41.
MySQL v8.0.31.
MariaDB v10.11.2.

Acknowledgements

I would like to specially acknowledge Richard Hodges (hodges.r@gmail.com) for his invaluable technical guidance during development. Thanks also to Christian Mazakas for his ideas in early stages, and to Klemens Morgenstern and and Vinnie Falco for his techincal advice. Without you, this library would not exist.

Finally, thanks to Christopher Kohlhoff for his awesome Boost.Asio library, and to Howard Hinnant for his date algorithms, shamelessly copied in this lib.

Boost C++ Libraries

Motivation

When to use

Requirements

Acknowledgements