NAME EV::mysql - Asynchronous MySQL client using libmysqlclient and EV SYNOPSIS use EV; use EV::mysql; my $db; $db = EV::mysql->new( host => '127.0.0.1', port => 3306, user => 'root', password => '', database => 'test', utf8 => 1, on_connect => sub { print "connected to ", $db->server_info, "\n" }, on_error => sub { die "MySQL connection error: $_[0]\n" }, ); $db->query("select 1 + 1 as sum", sub { my ($rows, $err, $fields) = @_; die "Query failed: $err\n" if $err; print "$fields->[0] = $rows->[0][0]\n"; $db->close_async(sub { EV::break }); }); EV::run; DESCRIPTION "EV::mysql" is an asynchronous, non-blocking Perl client for MySQL built on top of the EV event loop and Oracle's "libmysqlclient" (discovered or built via Alien::MySQL). Designed as a sibling module to EV::MariaDB with a compatible Perl API, it allows EV-based applications targeting Oracle MySQL (including MySQL 8.x and 9.x) to execute queued queries, row-by-row streaming queries, transactions, and prepared statements without blocking the event loop. INSTALLATION Requires "EV" (>= 4.11) and "Alien::MySQL". cpanm EV Alien::MySQL perl Makefile.PL make TEST_MYSQL_HOST=127.0.0.1 TEST_MYSQL_USER=root make test make install Live server tests also accept "TEST_MYSQL_PORT", "TEST_MYSQL_PASS", "TEST_MYSQL_DB", and "TEST_MYSQL_SOCKET" (for Unix domain socket connections). METHODS new(%args) Creates a new "EV::mysql" connection handle. If "host" or "unix_socket" is provided, an asynchronous connection is initiated immediately. Croaks on any unrecognized argument. Supported arguments: * "loop" Optional EV loop object (defaults to EV::default_loop()). * "host", "user", "password", "database" (or "db"), "port", "unix_socket" Server connection parameters. "port" defaults to 3306. * "connect_timeout", "read_timeout", "write_timeout" Timeouts in seconds (unsigned integers; 0 or "undef" disables the timeout). "EV::mysql" enforces these deadlines with event-loop timers on non-blocking network operations ("connect", "query", "query_stream", and utility ops); synchronous "libmysqlclient" operations (see "NOTES ON LIBMYSQLCLIENT ASYNC API") rely on "libmysqlclient"'s socket-level timeouts. * "charset" Client character set (for example 'utf8mb4'). * "init_command" SQL statement executed automatically upon establishing a connection. * "utf8" Boolean; enables Perl UTF-8 decoding for UTF-8 result columns/field names and UTF-8 encoding for queries, parameters, and escape(). * "compress" Boolean; enables MySQL client/server protocol compression. * "multi_statements" Boolean; enables semicolon-separated multi-statement queries. * "found_rows" Boolean; requests matched-row counts instead of changed-row counts for DML. * "ssl_key", "ssl_cert", "ssl_ca", "ssl_capath", "ssl_cipher" TLS certificate, key, CA, and cipher suite paths/settings. * "ssl_verify_server_cert" Boolean; maps to "SSL_MODE_VERIFY_IDENTITY" when enabled. * "ssl_mode" String SSL mode: 'DISABLED', 'PREFERRED', 'REQUIRED', 'VERIFY_CA', or 'VERIFY_IDENTITY'. * "on_connect", "on_error" Callbacks invoked with no arguments ("on_connect") or "($err_msg)" ("on_error") on connection completion or connection-level failure. When "on_error" is omitted or "undef" in new(), a default handler that calls "die "$_[0]\n"" is installed. connect($host, $user, $password, $database, $port, $unix_socket) Initiates an asynchronous connection on a disconnected handle. Croaks if already connected or connecting, or if $port is out of range (defaults to 3306 when omitted, "undef", or 0). reset() Resets and reconnects the connection using the previously configured connection parameters (alias "reconnect"). Cancels any pending operations and invalidates outstanding prepared statement handles. finish() Immediately closes the connection, clears pending timeouts/watchers, and cancels any queued operations with "connection finished" (alias "disconnect"). Also invalidates any prepared statement handles. close_async($cb) Drains prior queued operations, sends "COM_QUIT", tears down the connection, and invokes "$cb->(1, undef)". Rejects subsequent queuing with "connection is closing"; previously prepared statement handles are no longer valid after "close_async". on_connect([$handler]), on_error([$handler]) Gets or sets the connection-level callback handlers. Calling with an argument replaces the current handler (passing "undef" or a non-CODE value clears it); calling with no arguments returns the current handler (or "undef"). query($sql, $cb) Queues an SQL query for asynchronous FIFO execution (alias "q"). Multiple queries may be queued while connecting or while a utility op (such as "ping", "select_db", "reset_connection", "set_charset", "commit", "rollback", "autocommit") is running; croaks "cannot queue query while streaming is active" during "query_stream", "not connected" on an uninitialized/disconnected handle, or "connection is closing" after "close_async". On completion, "$cb->($res, $err, $fields)" is invoked: for result sets $res is an arrayref of arrayrefs and $fields is an arrayref of column names; for non-select statements (insert, update, delete, do, etc.) $res is the integer affected row count. On error $res is "undef" and $err holds the error string. When "multi_statements" is enabled and the first statement succeeds, secondary statement or drain errors are delivered to "on_error". query_stream($sql, $row_cb) Streams result rows one at a time via "$row_cb->($row, $err, $fields)" as they arrive, invoking $row_cb->(undef) at end-of-results (or "$row_cb->(undef, $err)" on error). Croaks if streaming is already active. Secondary errors in a "multi_statements" batch after the first result completes are delivered to "on_error". prepare($sql, $cb) Prepares a server-side statement (alias "prep") and invokes "$cb->($stmt, $err)". Prepared statement handles are invalidated by "close_stmt", "finish", "reset", "reset_connection", "change_user", and "close_async". execute($stmt, \@params, $cb) / execute($stmt, $cb) Executes a prepared statement (snapshotting "\@params" at queue time, or using parameters bound via "bind_params" / "send_long_data" when "\@params" is omitted or "undef") and invokes "$cb->($res, $err, $fields)". bind_params($stmt, \@params) Manually binds parameters on a prepared statement (typically before "send_long_data" or "execute($stmt, undef, $cb)"). Must be called when no incompatible operation is in progress or queued. send_long_data($stmt, $param_idx, $data, $cb) Sends binary or text parameter chunks for 0-based parameter index $param_idx before "execute" and invokes "$cb->($ok, $err)". Can be called multiple times per parameter to stream chunks cleanly. stmt_reset($stmt, $cb) Resets a prepared statement handle on the server and invokes "$cb->($ok, $err)". Prepared statement handles become invalid after "close_stmt", "finish", "reset", "reset_connection", "change_user", or "close_async". close_stmt($stmt, $cb) Closes a prepared statement handle and invokes "$cb->($ok, $err)". Calling "close_stmt", "finish", "reset", "reset_connection", "change_user", or "close_async" invalidates outstanding statement handles; closing an already-invalidated handle invokes "$cb->(1, undef)" immediately. ping($cb), select_db($db, $cb), reset_connection($cb) Asynchronous connection maintenance helpers (utility ops) invoking "$cb->($ok, $err)". "reset_connection" clears server session state and invalidates outstanding prepared statement handles. commit($cb), rollback($cb), autocommit($bool, $cb) Asynchronous transaction helpers (utility ops) invoking "$cb->($ok, $err)". For "autocommit", any truthy value enables autocommit and any falsy value disables it. set_charset($charset, $cb), change_user($user, $password, $db, $cb) Updates the client character set (utility op) or re-authenticates the session user/database (which also invalidates prepared statements) and invokes "$cb->($ok, $err)". Pass "undef" for $db to keep the current database. skip_pending(), pending_count() skip_pending() cancels queued callbacks with error "skipped" (closing the wire socket if an in-flight request was already sent). pending_count() returns the total number of currently active and queued operations. escape($str) Escapes $str for SQL literal interpolation using "mysql_real_escape_string". Requires an active connection. is_connected(), is_connecting() Returns connection state booleans. error_message(), error_number(), sqlstate() Returns the latest error message string (aliases "error", "errstr"), MySQL error code (alias "errno"), and 5-character SQLSTATE string. affected_rows(), insert_id(), warning_count(), info() Returns metadata from the most recent completed query or statement (note: insert_id() returns "undef" when disconnected). thread_id(), host_info(), server_info(), server_version(), character_set_name(), socket() Returns connection and server metadata (alias "socket_fd" for socket()). EV::mysql->lib_version(), EV::mysql->lib_info() Class methods returning the linked "libmysqlclient" version integer and informational string (aliases "client_version", "client_info"). NOTES ON LIBMYSQLCLIENT ASYNC API Unlike MariaDB's "libmariadb", Oracle's "libmysqlclient" exports non-blocking functions exclusively for connection setup, query execution, result retrieval, row streaming, and connection reset ("mysql_*_nonblocking"). Functions without non-blocking equivalents in "libmysqlclient" (prepared statements, "set_charset", "change_user", and "close_async") execute against "libmysqlclient" synchronously while preserving "EV::mysql"'s queue, error handling, and asynchronous callback semantics. Handles are fork-safe (a forked child automatically detaches the inherited socket without disturbing the parent connection) and set "CLONE_SKIP" to 1 for Perl ithreads safety. EXAMPLES See the eg/ directory included in the distribution: * eg/basic.pl - Connecting, creating a temporary table, inserting, selecting, and closing cleanly * eg/pipeline.pl - Pipelined queries and FIFO result ordering * eg/prepared.pl - Prepared statements, parameter binding, NULL values, and cleanup * eg/error_handling.pl - Query errors vs connection errors, recovery, and "reset_connection" SEE ALSO EV, Alien::MySQL, EV::MariaDB AUTHOR vividsnow COPYRIGHT AND LICENSE This software is copyright (c) 2026 by vividsnow. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.