mirror of
https://github.com/boostorg/mysql.git
synced 2025-05-12 06:01:42 +00:00
119 lines
3.5 KiB
Plaintext
119 lines
3.5 KiB
Plaintext
[/
|
|
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] |