Boost C++ Libraries of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for a snapshot of the develop branch, built from commit fa4e49ef67.

Async functions using stackful coroutines

This example demonstrates how use the asynchronous functions using stackful coroutines (using boost::asio::yield_context and boost::asio::spawn).

This example assumes you have gone through the setup.

// To use coroutines created by boost::asio::spawn, you need to link
// against Boost.Context.

#include <boost/mysql/diagnostics.hpp>
#include <boost/mysql/error_code.hpp>
#include <boost/mysql/error_with_diagnostics.hpp>
#include <boost/mysql/handshake_params.hpp>
#include <boost/mysql/row_view.hpp>
#include <boost/mysql/tcp_ssl.hpp>
#include <boost/mysql/throw_on_error.hpp>

#include <boost/asio/io_context.hpp>
#include <boost/asio/ip/tcp.hpp>
#include <boost/asio/post.hpp>
#include <boost/asio/spawn.hpp>
#include <boost/asio/ssl/context.hpp>

#include <iostream>

using boost::mysql::error_code;

void print_employee(boost::mysql::row_view employee)
    std::cout << "Employee '" << << " "   // first_name (string)
              << << "' earns "            // last_name  (string)
              << << " dollars yearly\n";  // salary     (double)

void main_impl(int argc, char** argv)
    if (argc != 4 && argc != 5)
        std::cerr << "Usage: " << argv[0] << " <username> <password> <server-hostname> [company-id]\n";

    const char* hostname = argv[3];

    // The company_id whose employees we will be listing. This
    // is user-supplied input, and should be treated as untrusted.
    const char* company_id = argc == 5 ? argv[4] : "HGS";

    // I/O context and connection. We use SSL because MySQL 8+ default settings require it.
    boost::asio::io_context ctx;
    boost::asio::ssl::context ssl_ctx(boost::asio::ssl::context::tls_client);
    boost::mysql::tcp_ssl_connection conn(ctx, ssl_ctx);

    // Connection params
    boost::mysql::handshake_params params(
        argv[1],                // username
        argv[2],                // password
        "boost_mysql_examples"  // database to use; leave empty or omit for no database

    // Resolver for hostname resolution
    boost::asio::ip::tcp::resolver resolver(ctx.get_executor());

     * The entry point. We spawn a stackful coroutine using boost::asio::spawn.
     * The coroutine will actually start running when we call io_context::run().
     * It will suspend every time we call one of the asynchronous functions, saving
     * all information it needs for resuming. When the asynchronous operation completes,
     * the coroutine will resume in the point it was left.
        [&conn, &resolver, params, hostname, company_id](boost::asio::yield_context yield) {
            // This error_code and diagnostics will be filled if an
            // operation fails. We will check them for every operation we perform.
            boost::mysql::error_code ec;
            boost::mysql::diagnostics diag;

            // Hostname resolution
            auto endpoints = resolver.async_resolve(hostname, boost::mysql::default_port_string, yield[ec]);

            // Connect to server
            conn.async_connect(*endpoints.begin(), params, diag, yield[ec]);
            boost::mysql::throw_on_error(ec, diag);

            // We will be using company_id, which is untrusted user input, so we will use a prepared
            // statement.
            boost::mysql::statement stmt = conn.async_prepare_statement(
                "SELECT first_name, last_name, salary FROM employee WHERE company_id = ?",
            boost::mysql::throw_on_error(ec, diag);

            // Execute the statement
            boost::mysql::results result;
            conn.async_execute(stmt.bind(company_id), result, diag, yield[ec]);
            boost::mysql::throw_on_error(ec, diag);

            // Print the employees
            for (boost::mysql::row_view employee : result.rows())

            // Notify the MySQL server we want to quit, then close the underlying connection.
            conn.async_close(diag, yield[ec]);
            boost::mysql::throw_on_error(ec, diag);
        // If any exception is thrown in the coroutine body, rethrow it.
        [](std::exception_ptr ptr) {
            if (ptr)

    // Don't forget to call run()! Otherwise, your program
    // will not spawn the coroutine and will do nothing.;

int main(int argc, char** argv)
        main_impl(argc, argv);
    catch (const boost::mysql::error_with_diagnostics& err)
        // You will only get this type of exceptions if you use throw_on_error.
        // Some errors include additional diagnostics, like server-provided error messages.
        // Security note: diagnostics::server_message may contain user-supplied values (e.g. the
        // field value that caused the error) and is encoded using to the connection's character set
        // (UTF-8 by default). Treat is as untrusted input.
        std::cerr << "Error: " << err.what() << '\n'
                  << "Server diagnostics: " << err.get_diagnostics().server_message() << std::endl;
        return 1;
    catch (const std::exception& err)
        std::cerr << "Error: " << err.what() << std::endl;
        return 1;