| Home | Libraries | People | FAQ | More

## 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:

- `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.
- The obtained `field_view` is streamed to `std::cout`.

#### 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.