...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
In this first tutorial, we will write a simple program to demonstrate the basic
concepts. We will connect to the server and issue the query SELECT
"Hello World!"
.
To run this tutorial, you need a running MySQL server listening in localhost on port 3306 (the default one). You should have the credentials of a valid MySQL user (username and password). No further setup is needed.
The full program listing for this tutorial can be found here.
We will follow these steps:
This tutorial uses synchronous functions with exceptions, as they're easy to use. In subsequent tutorials, we will learn how to use asynchronous functions, which are more versatile.
All functions and classes reside within the boost::mysql
namespace.
To reduce verbosity, all examples and code samples use the following namespace
aliases:
namespace mysql = boost::mysql; namespace asio = boost::asio;
Like most Asio-based applications, we need to create a asio::io_context
object before anything else. An io_context
is an execution context: it contains an event loop, file descriptor states,
timers and other items required to perform I/O. Most applications should only
create a single io_context
,
even when multiple MySQL connections are needed.
We then create an any_connection
,
which represents a single connection to a MySQL server:
// The execution context, required to run I/O operations. asio::io_context ctx; // Represents a connection to the MySQL server. mysql::any_connection conn(ctx);
any_connection::connect
establishes a client session with the server. It takes a connect_params
object with the required information to establish a session:
// The hostname, username and password to use mysql::connect_params params; params.server_address.emplace_host_and_port(hostname); params.username = username; params.password = password; // Connect to the server conn.connect(params);
any_connection::execute
accepts a string containing the SQL query to run and sends it to the server
for execution. It returns a results
object, containing the rows returned by the query:
// Issue the SQL query to the server const char* sql = "SELECT 'Hello world!'"; mysql::results result; conn.execute(sql, result);
results
is a class that holds the result of a query in memory. To obtain the value
we selected, we can write:
// Print the first field in the first row std::cout << result.rows().at(0).at(0) << std::endl;
Let's break this into steps:
results::rows
returns all the rows that this object contains. It returns a rows_view
,
which is a 2D matrix-like structure.
result.rows().at(0)
returns the first row, represented as
a row_view
.
result.rows().at(0).at(0)
returns the first field in the first row. This is a field_view
,
a variant-like class that can hold any type allowed in MySQL.
field_view
is streamed to std::cout
.
Once we are done with the connection, we can close it by calling any_connection::close
.
Note that this will send a final quit packet to the MySQL server to notify
we are closing the connection, and thus may fail.
// Close the connection conn.close();
Full program listing for this tutorial is here.
You can now proceed to the next tutorial.