[/
    Copyright (c) 2019-2024 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:examples Examples]

Welcome to __Self__ examples. If you are intending to
run the examples, please go through the [link mysql.examples.setup
setup] first.

Here is a list of available examples:

# [link mysql.examples.async_callbacks Async functions using callbacks]
# [link mysql.examples.async_futures Async functions using futures]
# [link mysql.examples.async_coroutines Async functions using stackful coroutines]
# [link mysql.examples.async_coroutinescpp20 Async functions using C++20 coroutines]
# [link mysql.examples.timeouts Setting timeouts]
# [link mysql.examples.prepared_statements_cpp11 Using prepared statements with the dynamic interface (C++11)]
# [link mysql.examples.prepared_statements_cpp14 Using prepared statements with the static interface (C++14)]
# [link mysql.examples.stored_procedures_cpp11 Using stored procedures with the dynamic interface (C++11)]
# [link mysql.examples.stored_procedures_cpp14 Using stored procedures with the static interface (C++14)]
# [link mysql.examples.metadata Metadata]
# [link mysql.examples.unix_socket UNIX sockets]
# [link mysql.examples.ssl Setting SSL options]
# [link mysql.examples.source_script Using multi-queries to source a .sql file]
# [link mysql.examples.any_connection (Experimental) Using type-erased connections]
# [link mysql.examples.batch_inserts (Experimental) Batch inserts using client-side query formatting]
# [link mysql.examples.batch_inserts_generic (Experimental) Generic batch inserts with Boost.Describe: extending format_sql]
# [link mysql.examples.dynamic_filters (Experimental) Implements a query with several dynamic filters using client-side query formatting]
# [link mysql.examples.patch_updates (Experimental) Implements a dynamic UPDATE query for PATCH-like update semantics using client-side query formatting]
# [link mysql.examples.connection_pool (Experimental) A REST API server that uses connection pooling]
# [@https://github.com/anarthal/servertech-chat The BoostServerTech chat project uses Boost.MySQL and Boost.Redis to implement a chat server]

[heading Setup]

To run the examples, you need a MySQL server you can connect to.
Examples make use of a database named `boost_mysql_examples`.
The server hostname and credentials (username and password) are passed 
to the examples via the command line.

If you're using docker, you can use the `ghcr.io/anarthal-containers/mysql8` container
to simplify the process:

[!teletype]
```
    # If you're on a system supporting UNIX sockets. Note that /var/run/mysqld
    # should be empty for this to work; you can specify a different directory, if it's not
    > docker run -p 3306:3306 -v /var/run/mysqld:/var/run/mysqld -d ghcr.io/anarthal-containers/mysql8

    # If you're on a system that does not support UNIX sockets
    > docker run -p 3306:3306 -d ghcr.io/anarthal-containers/mysql8

    # All the required data can be loaded by running example/db_setup.sql.
    # If you're using the above container, the root user has a blank password
    > mysql -u root < example/db_setup.sql
```

Please note that this container is just for demonstrative purposes,
and is not suitable for production.

The root MySQL user for these containers is `root` and it has an empty password.


[section:async_callbacks Async functions using callbacks]

This example demonstrates how use the asynchronous functions using callbacks.

__assume_setup__

[import ../../example/async_callbacks.cpp]
[example_async_callbacks]

[endsect]




[section:async_futures Async functions using futures]

This example demonstrates how use the asynchronous functions using futures.

__assume_setup__

[import ../../example/async_futures.cpp]
[example_async_futures]

[endsect]




[section:async_coroutines Async functions using stackful coroutines]

This example demonstrates how use the asynchronous functions using stackful coroutines
(using [asioreflink yield_context yield_context] and
[asioreflink spawn spawn]).

__assume_setup__

[import ../../example/async_coroutines.cpp]
[example_async_coroutines]

[endsect]




[section:async_coroutinescpp20 Async functions using C++20 coroutines]

This example demonstrates how use the asynchronous functions using C++20 coroutines
(using [asioreflink use_awaitable use_awaitable] and [asioreflink
co_spawn co_spawn]).

__assume_setup__

[import ../../example/async_coroutinescpp20.cpp]
[example_async_coroutinescpp20]

[endsect]




[section:timeouts Timeouts]

This example demonstrates how to use Boost.Asio's
cancellation features to add timeouts to your async operations,
including the ones provided by __Self__. 
For that purpose, it employs C++20 coroutines.
If you are not familiar with them, look at
[link mysql.examples.async_coroutinescpp20 this example]
first.

__assume_setup__

[import ../../example/timeouts.cpp]
[example_timeouts]

[endsect]




[section:prepared_statements_cpp11 Using prepared statements with the dynamic interface (C++11)]

This example demonstrates how to use prepared statements with the dynamic interface to
implement a minimal order management system for an online store.

The example employs synchronous functions with
exceptions as error handling. __see_error_handling__

This examples requires you to run [link_to_file example/order_management/db_setup.sql].
You can find table definitions there.

[import ../../example/order_management/prepared_statements_cpp11.cpp]

[example_prepared_statements_cpp11]

[endsect]




[section:prepared_statements_cpp14 Using prepared statements with the static interface (C++14)]

This example demonstrates how to use prepared statements with the static interface to
implement a minimal order management system for an online store.

The example employs synchronous functions with
exceptions as error handling. __see_error_handling__

This examples requires you to run [link_to_file example/order_management/db_setup.sql].
You can find table definitions there.

[import ../../example/order_management/prepared_statements_cpp14.cpp]

[example_prepared_statements_cpp14]

[endsect]




[section:stored_procedures_cpp11 Using stored procedures with the dynamic interface (C++11)]

This example demonstrates how to use stored procedures with the dynamic interface to
implement a minimal order management system for an online store.

The example employs synchronous functions with
exceptions as error handling. __see_error_handling__

This examples requires you to run [link_to_file example/order_management/db_setup.sql].
You can find table and procedure definitions there.

[import ../../example/order_management/stored_procedures_cpp11.cpp]

[example_stored_procedures_cpp11]

[endsect]




[section:stored_procedures_cpp14 Using stored procedures with the static interface (C++14)]

This example demonstrates how to use stored procedures with the static interface to
implement a minimal order management system for an online store.

The example employs synchronous functions with
exceptions as error handling. __see_error_handling__

This examples requires you to run [link_to_file example/order_management/db_setup.sql].
You can find table and procedure definitions there.

[import ../../example/order_management/stored_procedures_cpp14.cpp]

[example_stored_procedures_cpp14]

[endsect]




[section:metadata Metadata]

This example demonstrates how to use the available metadata in a [reflink results] object.
It employs synchronous functions with exceptions as error handling. __see_error_handling__

__assume_setup__

[import ../../example/metadata.cpp]
[example_metadata]

[endsect]




[section:unix_socket UNIX sockets]

This example demonstrates how to establish a connection
to a MySQL server using a UNIX domain socket. The path
to the UNIX socket can be passed in as third parameter
in the command line, and defaults to `/var/run/mysqld/mysqld.sock`,
the default on most systems.

The example employs synchronous functions with
exceptions as error handling. __see_error_handling__

__assume_setup__

[import ../../example/unix_socket.cpp]
[example_unix_socket]

[endsect]




[section:ssl Setting SSL options]

This example demonstrates how to configure SSL options
like server certificate verification and hostname validation.

The example employs synchronous functions with
exceptions as error handling. __see_error_handling__

__assume_setup__ Additionally, you should run your MySQL server
with some test certificates we created for you, just for this example.
You can find them in this project's GitHub repository, under `tools/ssl`.
If you're using the docker container, the setup has already been done
for you.

[import ../../example/ssl.cpp]
[example_ssl]

[endsect]




[section:source_script Using multi-queries to source a .sql file]

This example demonstrates how to source a .sql script using the
[link mysql.multi_resultset.multi_queries multi-queries feature].

Note that commands like `DELIMITER` won't work, since these are handled
by the `mysql` command line tool, rather than the server.

The example employs synchronous functions with
exceptions as error handling. __see_error_handling__

__assume_setup__

[import ../../example/source_script.cpp]
[example_source_script]

[endsect]





[section:any_connection (Experimental) Using type-erased connections]

This example demonstrates how to use [reflink any_connection].

The example employs async functions with stackful coroutines.

__assume_setup__

[import ../../example/any_connection.cpp]
[example_any_connection]

[endsect]





[section:batch_inserts (Experimental) Batch inserts using client-side query formatting]

This example demonstrates how to use client-side query formatting using
[reflink format_sql_to] to implement batch inserts. Batch inserting
can highly improve application performance.

The example employs sync functions with exceptions.

__assume_setup__

[import ../../example/batch_inserts.cpp]
[example_batch_inserts]

[endsect]





[section:batch_inserts_generic (Experimental) Generic batch inserts with Boost.Describe: extending format_sql]

This example demonstrates how to extend [reflink format_sql] using [reflink formatter]
to implement batch inserts for any struct that contains Boost.Describe metadata.

The example employs sync functions with exceptions.

__assume_setup__

[import ../../example/batch_inserts_generic.cpp]
[example_batch_inserts_generic]

[endsect]






[section:dynamic_filters (Experimental) Dynamic filters using client-side query formatting]

This example demonstrates how to use [reflink format_sql_to]
to implement filters that can be enabled dynamically.

The example employs async functions with stackful coroutines.

__assume_setup__

[import ../../example/dynamic_filters.cpp]
[example_dynamic_filters]

[endsect]






[section:patch_updates (Experimental) PATCH-like updates using client-side query formatting]

This example demonstrates how use [reflink format_sql_to]
to implement `UPDATE` queries with `PATCH` semantics, i.e.,
that update a dynamic set of fields.

The example employs sync functions with exceptions.

__assume_setup__

[import ../../example/patch_updates.cpp]
[example_patch_updates]

[endsect]







[section:connection_pool (Experimental) Connection pools]

This example demonstrates how to use [reflink connection_pool].
It implements an HTTP REST API server for a text notes
application. The API provides CRUD methods on note objects.
Instead of opening a new MySQL connection per HTTP request,
the server uses a connection pool to reuse connections. 

The example employs async functions with stackful coroutines.

This example contains multiple files, and requires linking to
__Context__, [@boost:/libs/json/index.html Boost.Json] and
and [@boost:/libs/url/index.html Boost.Url].
__assume_setup__

[import ../../example/connection_pool/main.cpp]
[example_connection_pool_main_cpp]

[import ../../example/connection_pool/types.hpp]
[example_connection_pool_types_hpp]

[import ../../example/connection_pool/repository.hpp]
[example_connection_pool_repository_hpp]

[import ../../example/connection_pool/repository.cpp]
[example_connection_pool_repository_cpp]

[import ../../example/connection_pool/handle_request.hpp]
[example_connection_pool_handle_request_hpp]

[import ../../example/connection_pool/handle_request.cpp]
[example_connection_pool_handle_request_cpp]

[import ../../example/connection_pool/server.hpp]
[example_connection_pool_server_hpp]

[import ../../example/connection_pool/server.cpp]
[example_connection_pool_server_cpp]

[import ../../example/connection_pool/log_error.hpp]
[example_connection_pool_log_error_hpp]


[endsect]





[endsect] [/ examples]