view release on metacpan or  search on metacpan

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

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.

=head2 query_stream

    $m->query_stream($sql, sub {
        my ($row, $err) = @_;
        if ($err) { warn $err; return }
        if (!defined $row) { print "done\n"; return }
        # 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:

=over 4

=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

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

Sends long parameter data (BLOB/TEXT) for a prepared statement.
C<$param_idx> is zero-based. May be called multiple times for the
same parameter to stream data in chunks. Must be preceded by
C<bind_params> and followed by C<execute> with C<undef> for params:

    $m->prepare("insert into t values (?, ?)", sub {
        my ($stmt) = @_;
        $m->bind_params($stmt, [1, ""]);   # bind all params first
        $m->send_long_data($stmt, 1, $blob_chunk, sub {
            $m->execute($stmt, undef, sub { # undef = keep bound params
                ...
            });
        });
    });

=head2 bind_params

    $m->bind_params($stmt, \@params);

Synchronously binds parameters to a prepared statement without
executing it. Required before C<send_long_data>. Types are detected
the same way as in C<execute>.

Dies with C<"another operation is in progress"> or
C<"cannot bind while pipeline results are pending"> when invoked on a
busy connection.

=head2 reset

    $m->reset;

Disconnects and reconnects using the most recent credentials (as
updated by C<change_user>/C<select_db>/C<set_charset>). Cancels all
pending operations and invalidates every prepared statement handle.
Dies with C<"no previous connection to reset"> if C<connect> has never
been called. Aliased as C<reconnect>.

=head2 finish

    $m->finish;

Closes the connection synchronously and cancels all pending operations
(their callbacks fire with an error). Aliased as C<disconnect>. Use
C<close_async> to close without blocking.

=head2 escape

    my $escaped = $m->escape($string);

Escapes a string for safe interpolation into SQL, respecting the
connection's character set. Warns if the input has Perl's UTF-8 flag
set but the connection charset is not C<utf8>/C<utf8mb4>. Synchronous;
dies with C<"not connected"> if disconnected, or
C<"connection is closing"> while C<close_async> is in flight.

=head2 skip_pending

    $m->skip_pending;

Cancels every pending, queued, and in-flight operation, invoking their
callbacks with C<(undef, "skipped")>. If sent queries are still
awaiting results (or an exclusive op is in flight), the underlying
connection is also closed -- call C<reset> afterwards to reconnect.
Queries that were merely queued are cancelled without disturbing the
connection. When called from within a callback (for example a
C<query_stream> row callback), that same callback is not re-invoked with
the C<"skipped"> error -- you are already inside it.

=head2 on_connect

    $m->on_connect(sub { ... });   # set
    my $cb = $m->on_connect;       # get
    $m->on_connect(undef);         # clear

Accessor for the connect handler. With a CODE ref, replaces the
current handler. With C<undef> (or any non-CODE value), clears it.
With no argument, returns the current handler (or C<undef> if unset).
The handler is fired again after every successful C<reset>/reconnect.

=head2 on_error

    $m->on_error(sub { my ($msg) = @_ });   # set
    my $cb = $m->on_error;                  # get
    $m->on_error(undef);                    # clear

Accessor for the error handler. Same get/set/clear semantics as
C<on_connect>. After clearing, connection-level errors are silently
dropped.

=head1 ACCESSORS

All accessors are synchronous and safe to call at any time; those