[/
    Copyright (c) 2019-2025 Ruben Perez Hidalgo (rubenperez038 at gmail dot com)
   
    Distributed under the Boost Software License, Version 1.0. (See accompanying
    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
]

[section:tutorial_sync 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 [link mysql.examples.tutorial_sync here].

We will follow these steps:

# Create a connection object.
# Establish a session with the server.
# Issue the query.
# Use the rows generated by the query.
# 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.

[heading 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:

[tutorial_sync_namespaces]




[heading Connection object]

Like most Asio-based applications, we need to create a
[asioreflink io_context 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 [reflink any_connection], which represents a single connection
to a MySQL server:

[tutorial_sync_connection]




[heading Connecting to the server]

[refmem any_connection connect] establishes a client session with the server.
It takes a [reflink connect_params] object with the required
information to establish a session:

[tutorial_sync_connect]




[heading Issuing the SQL query]

[refmem any_connection execute] accepts a string containing
the SQL query to run and sends it to the server for execution.
It returns a [reflink results] object, containing the rows returned by the query:

[tutorial_sync_query]




[heading Obtaining the results]

[reflink results] is a class that holds the result of a query in memory.
To obtain the value we selected, we can write:

[tutorial_sync_results]

Let's break this into steps:

* [refmem results rows] returns all the rows that this object contains.
  It returns a [reflink rows_view], which is a 2D matrix-like structure.
* `result.rows().at(0)` returns the first row, represented as a [reflink row_view].
* `result.rows().at(0).at(0)` returns the first field in the first row. This is a
  [reflink field_view], a variant-like class that can hold any type allowed in MySQL.
* The obtained `field_view` is streamed to `std::cout`.




[heading Closing the connection]

Once we are done with the connection, we can close it by calling
[refmem 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.

[tutorial_sync_close]




[heading Next steps]

Full program listing for this tutorial is [link mysql.examples.tutorial_sync here].

You can now proceed to [link mysql.tutorial_async the next tutorial].

[endsect]