mirror of
https://github.com/boostorg/mysql.git
synced 2026-02-14 12:52:17 +00:00
86e0eacd6a
* SSL/TLS rework * Unified connection object * New prepared_statement::execute interface * New resultset::read_one mechanic * Unified row object * null_t type * Travis to GitHub actions migration * Integration test rework
112 lines
4.2 KiB
Plaintext
112 lines
4.2 KiB
Plaintext
[/
|
|
Copyright (c) 2019-2022 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 Tutorial]
|
|
|
|
[import ../../example/tutorial.cpp]
|
|
|
|
Welcome to Boost.Mysql's tutorial. We will go through the simplest
|
|
possible piece of code using Boost.Mysql: a program that connects
|
|
to the MySQL server and issues the query `SELECT "Hello World!"`.
|
|
|
|
This tutorial assumes you have 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.
|
|
|
|
This tutorial assumes you have a basic familiarity with __Asio__
|
|
(e.g. you know what a [asioreflink io_context io_context] is).
|
|
|
|
[heading Connection object]
|
|
|
|
The first step is to create a connection object, which
|
|
represents a single connection over TCP to the MySQL server.
|
|
We will be using [reflink tcp_ssl_connection], which supports TLS.
|
|
If you're using the latest MySQL version with its default configuration,
|
|
you will need to use TLS to successfully establish a connection.
|
|
|
|
A [reflink tcp_ssl_connection] is an I/O object. It can be constructed from a
|
|
[asioreflink io_context/executor_type io_context::executor_type] and a
|
|
[asioreflink ssl__context ssl::context]:
|
|
|
|
[tutorial_connection]
|
|
|
|
[heading Connecting to the server]
|
|
|
|
The next step is to connect to the server. We will use the function
|
|
[reflink2 connection.connect tcp_ssl_connection::connect],
|
|
which accepts two parameters:
|
|
|
|
* Physical connection parameters. As we are using TCP, this is a
|
|
[asioreflink ip__tcp/endpoint ip::tcp::endpoint],
|
|
identifying the host and port to connect to.
|
|
* MySQL handshake parameters. This is an instance of
|
|
[reflink connection_params], containing the username and password.
|
|
You may also set other options like the database name to connect to
|
|
or whether to use SSL or not.
|
|
|
|
[tutorial_connect]
|
|
|
|
[note
|
|
Read-only strings, like the ones used in [reflink connection_params]'s
|
|
constructor, are represented as `boost::string_view`s, which are similar
|
|
to `std::string_view`s but do not require C++17 to work.
|
|
]
|
|
|
|
[heading Issuing the SQL query]
|
|
|
|
The next step is to issue the query to the server. We will use
|
|
[reflink2 connection.query tcp_ssl_connection::query],
|
|
which accepts a string containing a single SQL query and instructs
|
|
the server to run it. It returns a [reflink tcp_resultset]
|
|
object, containing the query results:
|
|
|
|
[tutorial_query]
|
|
|
|
[heading Reading the results]
|
|
|
|
A [reflink resultset] is an object that represents the result of a query,
|
|
in tabular format. Resultsets are not containers, but I/O objects:
|
|
they do not contain by themselves the entire result of the query, but allow
|
|
the user to read it using several methods. We will use
|
|
[reflink2 resultset.read_all tcp_ssl_resultset::read_all], which just
|
|
reads all the rows in the resultset and places them in a `std::vector`
|
|
of [reflink row] objects:
|
|
|
|
[tutorial_read]
|
|
|
|
Rows are essentially arrays of [reflink value]s . A [reflink value]
|
|
is a union-like class of all types allowed in MySQL. You can access the row's
|
|
contents using [refmem row values].
|
|
|
|
[tutorial_values]
|
|
|
|
Let's break this down: from our vector of rows, we're selecting the first one
|
|
using `std::vector::at`. That row contains a single value, which we retrieve
|
|
using [refmem row values] and `std::vector::at`. We finally stream the value
|
|
to `std::cout`, which prints the expected phrase to the console.
|
|
|
|
To learn more about how to use the [reflink value] class, read [link mysql.values this section].
|
|
|
|
[heading Closing the connection]
|
|
|
|
Once we are done with the connection, we close it by calling
|
|
[reflink2 connection.close tcp_ssl_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_close]
|
|
|
|
[heading Final notes]
|
|
|
|
This concludes our __Self__ tutorial! You can now read more
|
|
about [link mysql.values MySQL values],
|
|
[link mysql.queries text queries], [link mysql.prepared_statements
|
|
prepared statements] and [link mysql.resultsets resultsets]. You can also
|
|
look at more complex [link mysql.examples examples].
|
|
|
|
[endsect] |