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.