EV-MariaDB

 view release on metacpan or  search on metacpan

Changes  view on Meta::CPAN

    - 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)

MariaDB.xs  view on Meta::CPAN

    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;

README.md  view on Meta::CPAN

# 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

=item * Prepared statements with automatic buffer management

=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, 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

=item ssl_cipher => $list

=item ssl_verify_server_cert => 1

SSL/TLS connection options.

=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>).
This applies to text queries, prepared statements, and streaming results.
Column names in C<$fields> are UTF-8-flagged when the connection charset
is C<utf8> or C<utf8mb4>, regardless of this option. Without this option,
all result values are returned as raw byte
strings (the default, matching DBD::mysql behavior).

Requires the connection charset to be C<utf8> or C<utf8mb4> for correct
behavior.

=back

lib/EV/MariaDB.pm  view on Meta::CPAN

        # process $row (arrayref)
    });

Executes a SELECT query and streams results row-by-row using
C<mysql_use_result>/C<mysql_fetch_row>. The callback is invoked once
per row with C<($arrayref)>, once at EOF with C<(undef)>, or on error
with C<(undef, $error_message)>. Unlike C<query>, results are not
buffered in memory - suitable for large result sets.

This is an exclusive operation: 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 (sends C<COM_QUIT>
without blocking the event loop). After completion, C<is_connected>
returns false. Use C<finish> for immediate synchronous close.

=head2 send_long_data

lib/EV/MariaDB.pm  view on Meta::CPAN

    );

The C<charset> option sets the connection character set used by the server.
The C<utf8> option 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 work correctly.

=head2 Reading data

With C<< utf8 => 1 >>, text query results, prepared statement results, and
streaming results are automatically UTF-8-flagged per column based on the
column's charset. Binary and non-UTF-8 columns are returned as raw byte
strings. Column names (the C<$fields> arrayref) are UTF-8-flagged when the
connection charset is C<utf8> or C<utf8mb4>, regardless of this option.

Without C<< utf8 => 1 >>, all result values are byte strings (the default).
Use C<Encode::decode_utf8()> to decode them manually.

=head2 Writing data

No special handling is needed for inserting Unicode. Perl strings (whether