EV-MariaDB
view release on metacpan or search on metacpan
- Document multi_statements result/error behavior and charset
requirements for UTF-8 prepared statement parameters
0.01 2026-03-07
- Async queries via MariaDB non-blocking API
- Query pipelining via mysql_send_query/mysql_read_query_result
- Prepared statements (prepare, execute, close_stmt, stmt_reset)
- Column metadata (field names) returned with query/execute results
- Streaming row-by-row results via query_stream
- Async transaction control (commit, rollback, autocommit)
- BLOB/TEXT streaming via send_long_data/bind_params
- Async graceful close via close_async
- set_charset for runtime character set changes
- Connection utility ops: ping, reset_connection, select_db, change_user
- Connection options (timeouts, compression, charset, SSL, multi_statements)
- Accessors: insert_id, warning_count, info, error_number, sqlstate
- Multi-result set drain for multi-statement queries
- Escape functions
- Short method aliases (q, prep, reconnect, disconnect, errstr, errno)
int draining; /* draining multi-result extras */
/* current operation context */
int op_ret;
MYSQL_RES *op_result;
MYSQL_STMT *op_stmt;
ev_mariadb_stmt_t *op_stmt_ctx; /* per-stmt wrapper for bind_params cleanup */
ev_mariadb_stmt_t *stmt_list; /* all allocated stmt wrappers */
MYSQL *op_conn_ret;
my_bool op_bool_ret;
MYSQL_ROW op_row; /* for streaming fetch_row result */
SV *stream_cb; /* streaming per-row callback */
char *op_data_ptr; /* copied data buffer for send_long_data */
SV *on_connect;
SV *on_error;
int callback_depth;
pid_t connect_pid; /* PID at connect time, for fork detection */
/* connection options (applied before mysql_real_connect_start) */
unsigned int connect_timeout;
# 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
```perl
lib/EV/MariaDB.pm view on Meta::CPAN
});
# 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
});
}
# streaming row-by-row (no full-result buffering)
$m->query_stream("select * from big_table", sub {
my ($row, $err) = @_;
if ($err) { warn $err; return }
if (!defined $row) { print "done\n"; return } # EOF
# process $row (arrayref)
});
EV::run;
=head1 DESCRIPTION
lib/EV/MariaDB.pm view on Meta::CPAN
=item * Column metadata (field names) returned with query results
=item * Streaming row-by-row results via C<query_stream>
=item * Async transaction control (commit, rollback, autocommit)
=item * Connection utility operations (ping, reset, reset_connection,
change_user, select_db, set_charset)
=item * BLOB/TEXT streaming via C<send_long_data>
=item * Async graceful close via C<close_async>
=item * Multi-result set support for multi-statement queries
=back
=head1 CONSTRUCTOR
=head2 new
lib/EV/MariaDB.pm view on Meta::CPAN
SSL/TLS connection options. The first five take a string (path or
cipher list); C<ssl_verify_server_cert> takes a boolean. See
L<MYSQL_OPT_SSL_*|https://mariadb.com/docs/connector-c/data-types-and-structures/mysql_optionsv> options
for semantics.
=item utf8 => 1
When enabled, result strings from columns with a UTF-8 charset are
automatically flagged with Perl's internal UTF-8 flag (C<SvUTF8_on>).
Applies to text queries, prepared statements, and streaming results.
Without this option, all result values are returned as raw byte
strings (matching DBD::mysql's default).
Column names in C<$fields> are UTF-8-flagged when the connection
charset is C<utf8> or C<utf8mb4>, regardless of this option.
Requires the connection charset to be C<utf8> or C<utf8mb4> for correct
behaviour. See L</UNICODE>.
=back
lib/EV/MariaDB.pm view on Meta::CPAN
=item * once per row with C<($row)>, where C<$row> is an arrayref
=item * once at EOF with C<(undef)>
=item * on error with C<(undef, $error_message)>
=back
Unlike C<query>, rows are not buffered -- suitable for very large
result sets. No other queries can be queued while streaming is active.
=head2 close_async
$m->close_async(sub { my ($ok, $err) = @_ });
Gracefully closes the connection asynchronously (C<COM_QUIT> without
blocking the event loop). C<is_connected> returns false once the
callback has fired. Use C<finish> for an immediate synchronous close.
=head2 send_long_data
lib/EV/MariaDB.pm view on Meta::CPAN
);
C<charset> sets the connection character set used by the server.
C<utf8> controls Perl-side string flagging: when enabled, result
strings from UTF-8 columns are returned with Perl's internal UTF-8
flag set so C<length>, regex, and other character operations behave
correctly.
=head2 Reading
With C<< utf8 => 1 >>, text query, prepared-statement, and streaming
results are UTF-8-flagged per column based on the column's charset.
Binary and non-UTF-8 columns are returned as raw bytes. Column names
in C<$fields> are UTF-8-flagged whenever the connection charset is
C<utf8> or C<utf8mb4>, regardless of this option.
Without C<< utf8 => 1 >>, all values are byte strings -- decode with
L<Encode/decode_utf8>.
=head2 Writing
t/15_review_gaps.t view on Meta::CPAN
use warnings;
use Test::More;
use lib 't/lib';
use TestMariaDB;
plan skip_all => 'No MariaDB/MySQL server' unless TestMariaDB::server_available();
plan tests => 6;
use EV;
use EV::MariaDB;
# --- query() is rejected while a stream is active -------------------------
# query_stream is exclusive: "No other queries can be queued while streaming
# is active." Verify the guard actually croaks.
{
my $m; my $croaked = 0;
$m = EV::MariaDB->new(
TestMariaDB::connect_args(),
on_connect => sub {
$m->query_stream("select 1 union all select 2", sub {
my ($row, $err) = @_;
return if $err;
if (!defined $row) { EV::break; return }
( run in 2.519 seconds using v1.01-cache-2.11-cpan-600a1bdf6e4 )