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:
loopOptional EV loop object (defaults to
EV::default_loop()).host,user,password,database(ordb),port,unix_socketServer connection parameters.
portdefaults to3306.connect_timeout,read_timeout,write_timeoutTimeouts in seconds (unsigned integers;
0orundefdisables the timeout).EV::mysqlenforces these deadlines with event-loop timers on non-blocking network operations (connect,query,query_stream, and utility ops); synchronouslibmysqlclientoperations (see "NOTES ON LIBMYSQLCLIENT ASYNC API") rely onlibmysqlclient's socket-level timeouts.charsetClient character set (for example
'utf8mb4').init_commandSQL statement executed automatically upon establishing a connection.
utf8Boolean; enables Perl UTF-8 decoding for UTF-8 result columns/field names and UTF-8 encoding for queries, parameters, and
escape().compressBoolean; enables MySQL client/server protocol compression.
multi_statementsBoolean; enables semicolon-separated multi-statement queries.
found_rowsBoolean; requests matched-row counts instead of changed-row counts for DML.
ssl_key,ssl_cert,ssl_ca,ssl_capath,ssl_cipherTLS certificate, key, CA, and cipher suite paths/settings.
ssl_verify_server_certBoolean; maps to
SSL_MODE_VERIFY_IDENTITYwhen enabled.ssl_modeString SSL mode:
'DISABLED','PREFERRED','REQUIRED','VERIFY_CA', or'VERIFY_IDENTITY'.on_connect,on_errorCallbacks invoked with no arguments (
on_connect) or($err_msg)(on_error) on connection completion or connection-level failure. Whenon_erroris omitted orundefinnew(), a default handler that callsdie "$_[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
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.