Boost C++ Libraries

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

PrevUpHomeNext

Tutorial 1: hello world!

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:

  1. Create a connection object.
  2. Establish a session with the server.
  3. Issue the query.
  4. Use the rows generated by the query.
  5. Close the connection.

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.

Namespace conventions

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;

Connection object

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);

Connecting to the server

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);

Issuing the SQL query

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);

Obtaining the results

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:

Closing the connection

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();

Next steps

Full program listing for this tutorial is here.

You can now proceed to the next tutorial.


PrevUpHomeNext