EV::MariaDB

Async MariaDB/MySQL client for Perl using libmariadb and the EV event loop.

Features

• Fully asynchronous connect, query, prepared statements
• Query pipelining via mysql_send_query/mysql_read_query_result (up to 64 in-flight)
• Prepared statements with automatic buffer sizing via max_length detection
• Row streaming via query_stream for large result sets
• Transactions: commit, rollback, autocommit
• Connection utilities: ping, reset, change_user, select_db, reset_connection, set_charset
• Graceful async close via close_async
• Manual parameter binding with bind_params and send_long_data for BLOBs
• Column metadata (field names) returned as optional third callback argument
• Multi-result set support

Synopsis

use EV;
use EV::MariaDB;

my $m = EV::MariaDB->new(
    host       => 'localhost',
    user       => 'root',
    password   => '',
    database   => 'test',
    on_connect => sub { print "connected\n" },
    on_error   => sub { warn "error: $_[0]\n" },
);

# simple query
$m->query("select * from users", sub {
    my ($rows, $err, $fields) = @_;
    if ($err) { warn $err; return }
    for my $row (@$rows) {
        print join(", ", @$row), "\n";
    }
});

# prepared statement
$m->prepare("select * from users where id = ?", sub {
    my ($stmt, $err) = @_;
    die $err if $err;
    $m->execute($stmt, [42], sub {
        my ($rows, $err, $fields) = @_;
        # ...
        $m->close_stmt($stmt, sub { });
    });
});

# pipelined queries (all sent before reading results)
for my $id (1..100) {
    $m->q("select * from t where id = $id", sub {
        my ($rows, $err) = @_;
        # callbacks fire in order
    });
}

EV::run;

Install

Requires EV and Alien::MariaDB (which finds or builds libmariadb).

cpanm EV Alien::MariaDB
perl Makefile.PL && make && make test

Set connection info for tests:

TEST_MARIADB_HOST=127.0.0.1 TEST_MARIADB_USER=root make test
# or via unix socket:
TEST_MARIADB_SOCKET=/var/run/mysqld/mysqld.sock make test

Benchmark

500,000 queries against MariaDB 11.8 with ENGINE=MEMORY tables (no disk I/O), localhost unix socket. Compared to DBD::MariaDB 1.24 (synchronous DBI driver).

SELECT (select 1+1)

| Method | q/s | us/q | vs DBD sync | |---|--:|--:|--:| | EV::MariaDB pipeline(64) | 121,033 | 8.3 | 2.4x | | EV::MariaDB prepared | 58,911 | 17.0 | 1.2x | | EV::MariaDB sequential | 50,468 | 19.8 | 1.0x | | DBD::MariaDB sync prepared | 52,828 | 18.9 | 1.1x | | DBD::MariaDB sync | 49,857 | 20.1 | 1.0x | | DBD::MariaDB async+EV | 49,437 | 20.2 | 1.0x |

INSERT

| Method | q/s | us/q | vs DBD sync | |---|--:|--:|--:| | EV::MariaDB pipeline(64) | 78,781 | 12.7 | 1.8x | | EV::MariaDB prepared | 55,214 | 18.1 | 1.2x | | DBD::MariaDB sync prepared | 55,996 | 17.9 | 1.3x | | EV::MariaDB sequential | 44,380 | 22.5 | 1.0x | | DBD::MariaDB sync | 44,684 | 22.4 | 1.0x | | DBD::MariaDB async+EV | 42,145 | 23.7 | 0.9x |

SELECT point lookup (hash-indexed MEMORY table)

| Method | q/s | us/q | vs DBD sync | |---|--:|--:|--:| | EV::MariaDB pipeline(64) | 50,004 | 20.0 | 1.6x | | EV::MariaDB prepared | 37,911 | 26.4 | 1.2x | | DBD::MariaDB sync prepared | 36,813 | 27.2 | 1.2x | | EV::MariaDB sequential | 30,640 | 32.6 | 1.0x | | DBD::MariaDB sync | 30,778 | 32.5 | 1.0x | | DBD::MariaDB async+EV | 30,005 | 33.3 | 1.0x |

Pipeline mode provides 1.6-2.4x throughput over sequential execution by batching up to 64 queries before reading results, eliminating round-trip latency.

API

See perldoc EV::MariaDB for full documentation, including:

• query($sql, $cb) / q — execute SQL (callback receives $rows, $err, $fields)
• query_stream($sql, $cb) — stream rows one at a time for large result sets
• prepare($sql, $cb) / prep — prepare statement
• execute($stmt, \@params, $cb) — execute prepared statement
• bind_params($stmt, \@params) — manually bind parameters (synchronous)
• send_long_data($stmt, $idx, $data, $cb) — send BLOB/CLOB data in chunks
• close_stmt($stmt, $cb) — close prepared statement
• close_async($cb) — graceful async connection close
• stmt_reset($stmt, $cb) — reset prepared statement state
• commit($cb), rollback($cb), autocommit($mode, $cb) — transactions
• ping($cb), select_db($db, $cb), change_user(...) — utilities
• set_charset($charset, $cb) — change connection character set
• reset_connection($cb) — reset session state without reconnecting
• reset / reconnect — disconnect and reconnect
• finish / disconnect — close connection
• skip_pending — cancel all pending operations
• escape($str) — escape string for SQL
• on_connect($cb), on_error($cb) — get/set handlers
• lib_version, lib_info — class methods for client library info

License

Same terms as Perl itself.