Ruben Q4 update

Author: anarthal

_posts/2025-01-06-Ruben2024Q4Update.md

@@ -0,0 +1,222 @@
+---
+layout: post
+nav-class: dark
+categories: ruben
+title: "Boost.MySQL 1.87 and the new Boost citizens"
+author-id: ruben
+author-name: Rubén Pérez Hidalgo
+---
+
+## Boost.MySQL 1.87
+
+I already anticipated in [my previous post](https://cppalliance.org/ruben/2024/10/20/Ruben2024Q3Update.html)
+that Boost 1.87 was going to be an exciting release for the users of Boost.MySQL.
+Many new features have been promoted to stable, making using the library much more enjoyable.
+After putting the final touches during this last month, Boost 1.87 was released on December
+the 12th with all these new features.
+
+Many of these changes make frequent tasks much easier. In this post, we will review some of the recommendations
+that changed in this release. We suggest sticking to these for new code. Old code will keep working as expected.
+
+### Type-erased connections
+
+[`any_connection`](https://www.boost.org/doc/libs/master/libs/mysql/doc/html/mysql/ref/boost__mysql__any_connection.html)
+is the new recommended way to open connections to MySQL. It features simpler connection establishment semantics,
+more functionality and lower compile times with no loss of performance. We recommend using it over
+`tcp_ssl_connection` and friends in new code. Since an example is worth a thousand words, here's one:
+
+```cpp
+// Boost 1.86
+int main()
+{
+    // The execution context, required for all I/O operations
+    asio::io_context ctx;
+
+    // The SSL context, required for connections that use TLS.
+    asio::ssl::context ssl_ctx(asio::ssl::context::tlsv12_client);
+
+    // Construct the connection
+    mysql::tcp_ssl_connection conn(ctx, ssl_ctx);
+
+    // Resolve the hostname to get a collection of endpoints
+    auto endpoints = resolver.resolve("localhost", mysql::default_port_string);
+
+    // Parameters specifying how to perform the MySQL handshake operation.
+    mysql::handshake_params params(
+        "some_username",
+        "some_password",
+        "some_database"
+    );
+
+    // Connect to the server using the first endpoint returned by the resolver
+    conn.connect(*endpoints.begin(), params);
+}
+
+// Boost 1.87
+int main()
+{
+    // The execution context, required to run I/O operations.
+    asio::io_context ctx;
+
+    // Represents a connection to the MySQL server.
+    mysql::any_connection conn(ctx);
+
+    // The hostname, username and password to use
+    mysql::connect_params params {
+        .server_address = mysql::host_and_port("some_host"),
+        .username = "some_username",
+        .password = "some_password",
+        .database = "some_database",
+    };
+
+    // Connect to the server
+    conn.connect(params);
+}
+```
+
+### Client-side SQL formatting and with_params
+
+`with_params` can be used instead of prepared statements for one-off queries:
+
+```cpp
+// Boost 1.86
+void lookup(mysql::tcp_ssl_connection& conn, int id)
+{
+    // Prepare a statement
+    mysql::statement stmt = conn.prepare_statement("SELECT * FROM user WHERE id = ?");
+
+    // Execute it
+    mysql::static_results<user> res;
+    conn.execute(stmt.bind(id), res);
+
+    // Close it
+    conn.close_statement(stmt);
+
+    // Do something with the results
+}
+
+// Boost 1.87
+void lookup(mysql::any_connection& conn, int id)
+{
+    // Execute your query
+    mysql::static_results<user> res;
+    conn.execute(mysql::with_params("SELECT * FROM user WHERE id = {}", id), res);
+
+    // Do something with the results
+}
+```
+
+Since I already talked about this feature in [my last post](https://cppalliance.org/ruben/2024/10/20/Ruben2024Q3Update.html),
+I won't delve into more detail here.
+
+### Connection pools
+
+Might be the most requested feature in the library. Establishing sessions is costly, especially if TLS is enabled.
+Maintaining connections alive and reconnecting them on failure is also non-trivial.
+[Connection pools](https://www.boost.org/doc/libs/master/libs/mysql/doc/html/mysql/tutorial_connection_pool.html)
+do both for you, so you can focus on your queries, rather than on the infrastructure:
+
+```cpp
+// Boost 1.87. There's no equivalent in previous versions!
+int main()
+{
+    asio::io_context ctx;
+
+    // pool_params contains configuration for the pool.
+    mysql::pool_params params {
+        .server_address = mysql::host_and_port("my_server_hostname.com");
+        .username = "my_username",
+        .password = "my_password",
+        .database = "my_database",
+    };
+
+    // Create the pool and run it. async_run maintains the connections healthy
+    mysql::connection_pool pool(ctx, std::move(params));
+    pool.async_run(asio::detached);
+
+    // ...
+}
+
+asio::awaitable<void> lookup(mysql::connection_pool& pool, int id)
+{
+    // Get a connection from the pool. We don't need to connect or close the connection
+    mysql::pooled_connection conn = co_await pool.async_get_connection();
+
+    // Execute your query
+    mysql::static_results<user> res;
+    co_await conn->async_execute(mysql::with_params("SELECT * FROM user WHERE id = {}", id), res);
+
+    // Do something with the results
+}
+```
+
+### Built-in diagnostics in exceptions when using async functions
+
+MySQL may produce diagnostic text when queries fail. You can get this passing a `diagnostics`
+object that will be populated on error. This, combined with Asio's built-in error checking,
+made using throwing async functions cumbersome. As I already explained in
+[my previous post](https://cppalliance.org/ruben/2024/10/20/Ruben2024Q3Update.html),
+`with_diagnostics` and default completion tokens solve this problem:
+
+```cpp
+// Boost 1.86
+asio::awaitable<void> handle_request(mysql::tcp_ssl_connection& conn)
+{
+    mysql::results r;
+    mysql::diagnostics diag;
+    auto [ec] = co_await conn.async_execute("SELECT 1", r, diag, asio::as_tuple(asio::deferred));
+    mysql::throw_on_error(ec, diag);
+}
+
+// Boost 1.87
+asio::awaitable<void> handle_request(mysql::any_connection& conn)
+{
+    mysql::results r;
+    co_await conn.async_execute("SELECT 1", r);
+}
+```
+
+During these last months, I've polished these features. I've fix a myriad of small
+issues in `connection_pool`, made `mysql::sequence` owning (and thus easier to use
+as argument to `with_params`), and made `mysql::with_diagnostics` more interoperable
+with other tokens, like `asio::as_tuple`.
+
+## A new exposition for Boost.MySQL
+
+With great power comes great responsibility. I strongly believe that these new, exciting features
+are almost worthless if they are not properly explained. I wrote Boost.MySQL docs some time ago,
+and user experience has changed my mind on how an exposition should be.
+I've re-written many of the pages for this release, making them more practical, with more examples and use cases.
+I've introduced not one, but seven tutorials, slowly walking the user through the most common MySQL
+(and Asio) concepts to get them up to speed. And I've added new examples out of questions I received on GitHub.
+
+The old discussion used sync functions to expose library concepts, because they were by far
+the easiest to use. This lack of async examples led many users down to using sync functions
+when they shouldn't. Now that C++20 coroutines yield clean code, I've re-written part of
+the exposition to use them, providing more guidance on async patterns.
+As not everyone can (or want) to use them, I've also added some pages on how
+to port C++20 coroutine code to other completion styles.
+
+Writing all this has proven to be really time-consuming. Some might think of it as unexciting,
+but I hope my users will appreciate it. I'd like to thank the C++ Alliance sponsorship here,
+because these new docs wouldn't be possible without it.
+
+My next step here will be migrating the docs to Asciidoc, so they get a "younger"
+look and feel. This implies moving from the old Docca toolchain to an Asciidoc generator
+like [MrDocs](https://www.mrdocs.com/). I've had the pleasure to be an early user of the tool,
+and been able to provide some (hopefully useful) feedback to its authors.
+My thank you to Allan, Krystian and Fernando here.
+
+## New citizens in Boost: MQTT5 and Hash2
+
+It's been some intense months in Boost. I've had the pleasure to participate in three Boost reviews: a [MQTT5 Asio-based library](https://github.com/mireo/async-mqtt5/), [an SQLite wrapper](https://klemens.dev/sqlite/) and a [hashing library](https://pdimov.github.io/hash2/doc/html/hash2.html).
+
+I've been specially involved in the first one, since Asio is one of my main areas of expertise. With this library, our Asio ecosystem grows, and with it, the overall usefulness of Boost.
+
+## Other contributions
+
+One of my features that I implemented in Boost.MySQL required me to write a `std::to_array` backport.
+I've contributed it to [Boost.Compat](https://www.boost.org/doc/libs/1_87_0/libs/compat/doc/html/compat.html#to_array),
+with the help of its maintainer, Peter Dimov. As always, a great learning opportunity.
+
+I've also helped with some maintenance tasks in Boost.Redis.