Boost.MySQL

Boost.MySQL provides a C++11 client for MySQL and MariaDB servers with the following capabilities:

• Text queries: Execution of text SQL queries and data retrieval using the MySQL "text protocol".
• Prepared statements: Execution of prepared statements using the MySQL "binary protocol".
• Stored procedures: Support for calling stored procedures.
• Authentication: Supports mysql_native_password and caching_sha2_password authentication plugins.
• Security: Encrypted connections via TLS.
• Transports: Support for both TCP and UNIX socket transports.
• Connection Management: Includes connection pools.
• SQL Generation: Friendly client-side generated SQL.
• Pipelines: Experimental support for pipelines.

Boost.MySQL is built on top of Boost.Asio and is designed to be fully compatible with the Boost.Asio ecosystem (such as Boost.Beast). It supports Boost.Asio's universal asynchronous model, allowing developers to use various concurrency patterns:

• Callbacks
• Futures
• Coroutines (including C++20 coroutines)

Boost.MySQL is a header-only library, but it requires Boost 1.82 or higher (it does not work with standalone Asio), a C++11 capable compiler, and OpenSSL.

Since Boost 1.85, you must also link against the compiled Boost::charconv library. If you encounter linking errors, ensure you are linking to the charconv component in your build system.

project(boost_mysql_example LANGUAGES CXX)

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

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

Statements are no longer I/O objects. While connection::prepare_statement remains the same, execution and closing must now be performed through the connection object.

Actions:

• Replace stmt.execute(...) with conn.execute_statement(stmt, ...).
• Replace stmt.close() with conn.close_statement(stmt).

// Old way (0.2.x)
stmt.execute(params);
stmt.close();

// New way (1.82+)
conn.execute_statement(stmt, params);
conn.close_statement(stmt);

The date and datetime types are now custom types rather than aliases for std::chrono. This allows them to represent zero or invalid dates.

Action: To convert a date or datetime to a std::chrono::time_point, use the as_time_point or get_time_point methods in conjunction with valid() to ensure the value is usable.

The error_info class has been renamed to diagnostics, and error_info::message() is now diagnostics::server_message().

Important: The server message is no longer included by default in the what() string of thrown exceptions because it may not be UTF-8 compatible. To retrieve the server message from an exception, catch the error_with_diagnostics exception type.

Statement parameters are now passed as a std::tuple to execute_statement instead of a collection.

Action:

• Replace stmt.execute(make_values(a, b), ...) with conn.execute_statement(std::make_tuple(a, b), ...).
• If the number of parameters is unknown at compile-time, refer to the community solution for dynamic parameter handling.

// Old way (0.2.x)
stmt.execute(make_values(a, b), ...);

// New way (1.82+)
conn.execute_statement(std::make_tuple(a, b), ...);

// For no parameters
conn.execute_statement(std::make_tuple(), ...);

The value class has been replaced by field_view. Generic accessors have been replaced by type-specific functions. Conversions, get_optional, and get_std_optional have been removed in favor of an interface similar to json::value.

To take ownership of a field_view, use the new field class.

To save allocations, metadata strings (like column names) are no longer retained by default.

Action: If your code relies on metadata (e.g., calling metadata::column_name()), you must call conn.set_metadata_mode(metadata_mode::full) before executing your query or statement.

conn.set_metadata_mode(metadata_mode::full);
auto results = conn.query("SELECT ...");
// Now metadata like column names are available

Binary types such as BLOB, BINARY, VARBINARY, and GEOMETRY are now represented by the blob_view or blob types.

Action: Use is_blob, get_blob, and as_blob functions within field_view to handle these types.