view release on metacpan or  search on metacpan

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

Set the C<CLIENT_FOUND_ROWS> flag. Makes C<UPDATE> return the number of
matched rows instead of changed rows. Useful for upsert patterns where
you need to know if a row existed regardless of whether it was modified.

=item charset => $name

Character set name (e.g., C<utf8mb4>). Controls both result encoding
and how string parameters are interpreted by the server. To round-trip
Perl Unicode strings, set this to C<utf8> or C<utf8mb4> -- see L</UNICODE>.

=item init_command => $sql

SQL statement executed automatically after connecting.

=item ssl_key, ssl_cert, ssl_ca, ssl_capath, ssl_cipher, ssl_verify_server_cert

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

B<Event loop:>

=over 4

=item loop => $ev_loop

EV loop to use. Default: C<EV::default_loop>.

=back

=head1 METHODS

All asynchronous methods take a callback as the last argument. The
callback convention is C<($result, $error)>: on success C<$error> is
C<undef>; on failure C<$result> is C<undef> and C<$error> contains the
error message.

Methods divide into two scheduling classes:

=over 4

=item B<Queueable>

C<query> can be called at any time the object is alive -- before connect
completes, while a utility op is running, or while other queries are
already in flight. Calls are pipelined and their callbacks fire in
FIFO order.

=item B<Exclusive>

Every other async method (C<prepare>, C<execute>, C<close_stmt>,
C<stmt_reset>, C<ping>, C<select_db>, C<change_user>,
C<reset_connection>, C<set_charset>, C<commit>, C<rollback>,
C<autocommit>, C<query_stream>, C<close_async>, C<send_long_data>)
requires the connection to be idle. It dies with
C<"cannot start operation while pipeline results are pending"> if any
queued query has not yet delivered its result, or with
C<"another operation is in progress"> if another exclusive op is
running. Schedule these from inside the last queued query's callback,
or after a previous exclusive op completes.

=back

=head2 connect

    $m->connect($host, $user, $password, $database, $port, $unix_socket);

Connects to the server. Called automatically by C<new> when C<host> or
C<user> is provided; use this directly for deferred connection:

    my $m = EV::MariaDB->new(
        on_connect => sub { ... },
        on_error   => sub { ... },
    );
    $m->connect('localhost', 'root', '', 'test', 3306);

C<$port> defaults to C<3306>. C<$password>, C<$database>, and
C<$unix_socket> may be empty strings or C<undef> when not needed.
Dies with C<"already connected"> or C<"connection already in progress">
if invoked twice on the same object.

=head2 query

    $m->query($sql, sub { my ($result, $err, $fields) = @_ });

Executes a SQL query. The callback receives:

=over 4

=item *

For SELECT: C<($rows, undef, $fields)>, where C<$rows> is an arrayref
of row arrayrefs and C<$fields> is an arrayref of column name strings.

=item *

For DML (insert/update/delete): C<($affected_rows, undef)>.

=item *

On error: C<(undef, $error_message)>.

=back

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

(C<ping>, C<select_db>, ...) is in flight -- the query is buffered
until the connection is idle. Dies with C<"not connected"> if no
connection exists (never connected, or already closed via C<finish>).

By default, result strings are returned as raw bytes. Set
C<< utf8 => 1 >> in the constructor to flag UTF-8 columns automatically;
otherwise decode with L<Encode/decode_utf8>. See L</UNICODE>.

=head2 prepare

    $m->prepare($sql, sub { my ($stmt, $err) = @_ });

Prepares a server-side statement. The callback receives
C<($stmt, undef)> on success or C<(undef, $error)> on failure. Pass
the opaque C<$stmt> handle to C<execute>, C<bind_params>,
C<send_long_data>, C<stmt_reset>, and C<close_stmt>.

A prepared statement is invalidated by C<reset>, C<reset_connection>,
C<change_user>, and C<finish>. Re-prepare after any of these.

=head2 execute

    $m->execute($stmt, \@params, sub { my ($result, $err, $fields) = @_ });

Executes a prepared statement with the given parameters. Parameter
types are detected from the SV: integers bind as C<MYSQL_TYPE_LONGLONG>
(C<BIGINT>) with the unsigned flag tracking C<SvUOK>, floats as
C<MYSQL_TYPE_DOUBLE>, everything else as C<MYSQL_TYPE_STRING>. Pass
C<undef> for C<NULL>. The callback receives results in the same shape
as L</query>.

Pass C<undef> instead of C<\@params> to skip parameter binding and
re-use parameters set by a prior C<bind_params>/C<send_long_data>.

=head2 close_stmt

    $m->close_stmt($stmt, sub { my ($ok, $err) = @_ });

Closes a prepared statement, freeing server and client resources
(including bound parameter buffers). Should be called when the handle
is no longer needed, to free server-side state promptly; otherwise
cleanup happens at object destruction.

Already-invalidated handles (after C<reset>/C<reset_connection>/
C<change_user>) are accepted: the callback fires synchronously with
C<(1, undef)> and the wrapper is freed.

=head2 stmt_reset

    $m->stmt_reset($stmt, sub { my ($ok, $err) = @_ });

Resets a prepared statement (clears errors, unbinds parameters)
without closing it. Croaks
C<"statement handle is no longer valid (connection was reset)"> on a
handle invalidated by C<reset>/C<reset_connection>/C<change_user>.

=head2 ping

    $m->ping(sub { my ($ok, $err) = @_ });

Checks if the connection is alive.

=head2 select_db

    $m->select_db($dbname, sub { my ($ok, $err) = @_ });

Changes the default database. The new name is cached so a subsequent
C<reset> reconnects to it; the cache is rolled back if the operation
fails.

=head2 change_user

    $m->change_user($user, $password, $db_or_undef, sub { my ($ok, $err) = @_ });

Changes the authenticated user and optionally the database. Pass
C<undef> for C<$db> to keep the current database. The new credentials
are cached for C<reset>; the cache is rolled back if the change fails.

B<Note:> The server discards all prepared statements as part of this
operation -- see L</reset_connection> for details.

=head2 reset_connection

    $m->reset_connection(sub { my ($ok, $err) = @_ });

Resets session state (variables, temporary tables, etc.) without
reconnecting. Equivalent to C<COM_RESET_CONNECTION>.

B<Note:> The server discards all prepared statements as part of this
operation. Every statement handle held by Perl code is automatically
marked closed; subsequent C<execute>/C<stmt_reset> calls on those
handles croak C<"statement handle is no longer valid (connection was reset)">.
The same applies to C<change_user>. Re-prepare any statements you need
after the operation completes.

=head2 set_charset

    $m->set_charset($charset, sub { my ($ok, $err) = @_ });

Changes the connection character set asynchronously (e.g.,
C<utf8mb4>). The new charset is cached for C<reset>; the cache is
rolled back if the change fails.

=head2 commit

    $m->commit(sub { my ($ok, $err) = @_ });

Commits the current transaction.

=head2 rollback

    $m->rollback(sub { my ($ok, $err) = @_ });

Rolls back the current transaction.

=head2 autocommit

    $m->autocommit($mode, sub { my ($ok, $err) = @_ });

Enables or disables autocommit mode. C<$mode> is interpreted as a
boolean: any truthy value enables, any falsy value disables.