diff --git a/TODO.txt b/TODO.txt index b44b3f73..545a1bb5 100644 --- a/TODO.txt +++ b/TODO.txt @@ -1,3 +1,9 @@ +UNIX socket + Network functions for UNIX sockets (generic would be better) + Test suite for UNIX sockets (and maybe SSL too) + Conditionally build/run stuff for UNIX sockets + Config files for CIs to know where UNIX socket is + Docs Better docs Breaking up the tutorial in pieces Explaining the different overloads and async methods available @@ -19,15 +25,19 @@ Usability Metadata in rows: being able to index by name Iterators for sync resultset iteration Consideration of timezones + Timeouts + Retries + Connection pool Types Decimal Bit Geometry - UNIX socket connection connection::connect that handles TCP/Unix and MySQL connect connection::run_sql that hides the resultset concept Consider if header-only is a good idea Technical debt + Bad serialize(value.value) somewhere + Valgrindize Integ tests for different default auth plugins Integ tests for not enough capabilities Integ tests for ssl_mode::enable and SSL not available diff --git a/example/CMakeLists.txt b/example/CMakeLists.txt index 658d0828..649d3ef6 100644 --- a/example/CMakeLists.txt +++ b/example/CMakeLists.txt @@ -22,6 +22,7 @@ set(MYSQL_EXAMPLES query_async_futures metadata prepared_statements + unix_socket ) # We will autogenerate run_examples.bat and run_examples.sh, which will diff --git a/example/unix_socket.cpp b/example/unix_socket.cpp new file mode 100644 index 00000000..83726bf2 --- /dev/null +++ b/example/unix_socket.cpp @@ -0,0 +1,105 @@ + +#include "boost/mysql/connection.hpp" +#include +#include +#include + +/** + * For this example, we will be using the 'mysql_asio_examples' database. + * You can get this database by running db_setup.sql. + * This example assumes you are connecting to MySQL server using + * a UNIX socket. The socket path can be configured using command line + * arguments, and defaults to /tmp/mysql.sock + * + * This example uses synchronous functions and handles errors using exceptions. + */ + +void print_employee(const boost::mysql::row& employee) +{ + using boost::mysql::operator<<; // Required for mysql::value objects to be streamable, due to ADL rules + std::cout << "Employee '" + << employee.values()[0] << " " // first_name (type std::string_view) + << employee.values()[1] << "' earns " // last_name (type std::string_view) + << employee.values()[2] << " dollars yearly\n"; // salary (type double) +} + +void main_impl(int argc, char** argv) +{ + if (argc != 3 && argc != 4) + { + std::cerr << "Usage: " << argv[0] << " []\n"; + exit(1); + } + + const char* socket_path = "/tmp/mysql.sock"; + if (argc == 4) + { + socket_path = argv[3]; + } + + /** + * Connection parameters that tell us where and how to connect to the MySQL server. + * There are two types of parameters: + * - UNIX-level connection parameters, identifying the UNIX socket to connect to. + * - MySQL level parameters: database credentials and schema to use. + */ + boost::asio::local::stream_protocol::endpoint ep (socket_path); + boost::mysql::connection_params params ( + argv[1], // username + argv[2], // password + "mysql_asio_examples" // database to use; leave empty or omit the parameter for no database + ); + // Note: by default, SSL will be used if the server supports it. + // connection_params accepts an optional ssl_options argument + // determining whether to use SSL or not. See ssl_options and ssl_mode + // documentation for further details on SSL. + + boost::asio::io_context ctx; + + // Connection to the MySQL server, over a UNIX socket + boost::mysql::unix_connection conn (ctx); + conn.next_layer().connect(ep); // next_level() returns a boost::asio::local::stream_protocol::socket + conn.handshake(params); // Authenticates to the MySQL server + + const char* sql = "SELECT first_name, last_name, salary FROM employee WHERE company_id = 'HGS'"; + boost::mysql::unix_resultset result = conn.query(sql); + + // Get all the rows in the resultset + std::vector employees = result.fetch_all(); + for (const auto& employee: employees) + { + print_employee(employee); + } + + // We can issue any SQL statement, not only SELECTs. In this case, the returned + // resultset will have no fields and no rows + sql = "UPDATE employee SET salary = 10000 WHERE first_name = 'Underpaid'"; + result = conn.query(sql); + assert(result.fields().size() == 0); // fields() returns a vector containing metadata about the query fields + + // Check we have updated our poor intern salary + result = conn.query("SELECT salary FROM employee WHERE first_name = 'Underpaid'"); + auto rows = result.fetch_all(); + assert(rows.size() == 1); + [[maybe_unused]] auto salary = std::get(rows[0].values()[0]); + assert(salary == 10000); +} + +int main(int argc, char** argv) +{ + try + { + main_impl(argc, argv); + } + catch (const boost::system::system_error& err) + { + std::cerr << "Error: " << err.what() << ", error code: " << err.code() << std::endl; + return 1; + } + catch (const std::exception& err) + { + std::cerr << "Error: " << err.what() << std::endl; + return 1; + } +} + diff --git a/include/boost/mysql/connection.hpp b/include/boost/mysql/connection.hpp index 93311ee0..f50ff54c 100644 --- a/include/boost/mysql/connection.hpp +++ b/include/boost/mysql/connection.hpp @@ -10,6 +10,7 @@ #include "boost/mysql/prepared_statement.hpp" #include "boost/mysql/connection_params.hpp" #include +#include /** * \defgroup connection Connection @@ -163,7 +164,9 @@ public: */ using tcp_connection = connection; -// TODO: UNIX socket connection +#if defined(BOOST_ASIO_HAS_LOCAL_SOCKETS) || defined(BOOST_MYSQL_DOXYGEN) +using unix_connection = connection; +#endif /** * \ingroup connection diff --git a/include/boost/mysql/prepared_statement.hpp b/include/boost/mysql/prepared_statement.hpp index e8e23207..15f64eb4 100644 --- a/include/boost/mysql/prepared_statement.hpp +++ b/include/boost/mysql/prepared_statement.hpp @@ -6,6 +6,8 @@ #include "boost/mysql/detail/protocol/prepared_statement_messages.hpp" #include "boost/mysql/detail/auxiliar/async_result_macro.hpp" #include +#include +#include /** * \defgroup stmt Prepared statements @@ -179,6 +181,10 @@ public: */ using tcp_prepared_statement = prepared_statement; +#if defined(BOOST_ASIO_HAS_LOCAL_SOCKETS) || defined(BOOST_MYSQL_DOXYGEN) +using unix_prepared_statement = prepared_statement; +#endif + } // mysql } // boost diff --git a/include/boost/mysql/resultset.hpp b/include/boost/mysql/resultset.hpp index 2d1e1b3b..094243d4 100644 --- a/include/boost/mysql/resultset.hpp +++ b/include/boost/mysql/resultset.hpp @@ -9,6 +9,7 @@ #include "boost/mysql/detail/network_algorithms/common.hpp" // deserialize_row_fn #include "boost/mysql/detail/auxiliar/async_result_macro.hpp" #include +#include #include /** @@ -204,6 +205,10 @@ public: */ using tcp_resultset = resultset; +#if defined(BOOST_ASIO_HAS_LOCAL_SOCKETS) || defined(BOOST_MYSQL_DOXYGEN) +using unix_resultset = resultset; +#endif + } // mysql } // boost