[/
    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:queries Text queries]

To run a text query, use any of the following functions, passing a string-like
object (convertible to [reflink string_view]) containing valid SQL as the first parameter:

* [refmem connection execute] or [refmemunq connection async_execute]: these functions run the query and
  read the generated results into memory.
* [refmem connection start_execution] and [refmemunq connection async_start_execution]: these functions
  initiate a text query as a multi-function operation.

Almost any query that may be issued in the `mysql` command line
can be executed using this method. This includes `SELECT`s,
`UPDATE`s, `INSERT`s, `DELETE`s, `CREATE TABLE`s...
In particular, you may start transactions issuing a `START TRANSACTION`,
commit them using `COMMIT` and rolling them back using `ROLLBACK`.

[heading Use cases]

You should generally prefer prepared statements over text queries. Text queries can be useful for simple,
non-parametrized queries:

* `"START TRANSACTION"`, `"COMMIT"` and `"ROLLBACK"` queries, for transactions.
* `"SET NAMES utf8mb4"` and similar, to set variables for encoding, time zones and similar configuration options.
* `"CREATE TABLE ..."` and similar DDL statements.

If you need to run parametrized SQL, involving user input, you have two options:

* Use [link mysql.prepared_statements prepared statements] instead of text queries.
* If you don't mind using experimental features, you can use [link mysql.sql_formatting client-side SQL formatting]
  to securely compose queries in the client.

[warning
    [*SQL injection warning]: if you compose queries by concatenating strings without sanitization,
    your code is vulnerable to SQL injection attacks. Use prepared statements or proper formatting
    functions instead!
]


[heading Running multiple queries at once]

You can run several semicolon-separated queries in a single `execute()` call by enabling
the [refmem handshake_params multi_queries] option. You can find an example
[link mysql.multi_resultset.multi_queries here].


[endsect]