view release on metacpan or  search on metacpan

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

    $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