view release on metacpan or  search on metacpan

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

C<$field_names> 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

Queries are pipelined: multiple calls to C<query> before the event loop
runs will be sent as a batch, with results read back in order. May be
called after C<connect> has been initiated (even before it completes);
queries are buffered and sent once connected. Also safe to call while a
utility operation (C<ping>, C<select_db>, etc.) is active - the query
is buffered and executed when the operation completes. Dies if
C<connect> has not been called at all.

B<Note:> By default, result strings are returned as byte strings without
Perl's internal UTF-8 flag. Set C<< utf8 => 1 >> in the constructor to
automatically flag UTF-8 results, or use C<Encode::decode_utf8> manually.

=head2 prepare

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

Prepares a server-side statement. The callback receives an opaque
statement handle or an error. Pass the handle to C<execute>,
C<close_stmt>, and C<stmt_reset>.

=head2 execute

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

Executes a prepared statement with the given parameters. Parameters are
type-detected: integers bind as C<BIGINT> (unsigned integers are flagged
accordingly), floats as C<DOUBLE>, all others as C<STRING>. Pass
C<undef> for C<NULL>. The callback receives results in the same format
as C<query> (including C<$fields> for SELECT results).

Pass C<undef> instead of C<\@params> to skip parameter binding and use
previously bound parameters (see C<bind_params> and 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). B<Must> be called for every
prepared statement to avoid memory leaks.

=head2 stmt_reset

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

Resets a prepared statement (clears errors and unbinds parameters)
without closing it.

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

=head2 change_user

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

Changes the user and optionally the database. Pass C<undef> for C<$db>
to keep the current database.

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

=head2 set_charset

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

Changes the connection character set asynchronously (e.g., C<utf8mb4>).

=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 (C<$mode = 1>) or disables (C<$mode = 0>) autocommit mode.

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