view release on metacpan or  search on metacpan

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

    $pg->skip_pending;

Drops every queued callback, invoking each with
C<(undef, "skipped")>.  Any in-flight server results are drained and
discarded; the connection remains usable for new queries.

=head1 PIPELINE METHODS

Pipeline mode lets you send multiple queries without waiting for
individual results, then receive the results in order after a sync
point.  Inside a pipeline you must use C<query_params> or
C<query_prepared> -- C<query> is rejected.

=head2 enter_pipeline

    $pg->enter_pipeline;

Switches the connection into pipeline mode.  Croaks if there are
unfinished results outstanding.

=head2 exit_pipeline

    $pg->exit_pipeline;

Returns to normal mode.  Croaks if the pipeline is not idle.

=head2 pipeline_sync

    $pg->pipeline_sync(sub { my ($r, $err) = @_; });

Sends a pipeline sync point.  The callback fires with C<(1)> after all
preceding queries in the batch have completed, or
C<(undef, $errmsg)> if the connection drops first.  Alias: C<sync>.

=head2 send_pipeline_sync

    $pg->send_pipeline_sync(sub { my ($r, $err) = @_; });

Like C<pipeline_sync> but does B<not> flush the send buffer (requires
libpq E<gt>= 17).  Useful for batching multiple sync points before a
single manual flush via C<send_flush_request>.

=head2 send_flush_request

    $pg->send_flush_request;

Asks the server to deliver results for queries sent so far -- the
manual companion to C<send_pipeline_sync>.  Alias: C<flush>.

=head2 pipeline_status

    my $st = $pg->pipeline_status;

One of C<PQ_PIPELINE_OFF>, C<PQ_PIPELINE_ON>, or
C<PQ_PIPELINE_ABORTED>.

=head1 COPY METHODS

A C<COPY> command runs in two phases: the query callback first fires
with a string tag (C<"COPY_IN"> / C<"COPY_OUT"> / C<"COPY_BOTH">) to
signal that streaming has started, then fires a second time with the
final command result (or error) when the stream ends.  See
F<eg/copy_in.pl> and F<eg/copy_out.pl>.

=head2 put_copy_data

    my $rc = $pg->put_copy_data($data);

Sends a chunk during COPY IN.  Returns 1 on success (data buffered or
flushed), 0 if the send buffer is full (wait for writability via
C<on_drain>, then retry), or -1 on error.

=head2 put_copy_end

    my $rc = $pg->put_copy_end;
    my $rc = $pg->put_copy_end($errmsg);

Ends a COPY IN.  With C<$errmsg> aborts the COPY server-side.  Same
return convention as C<put_copy_data>.

=head2 get_copy_data

    my $row = $pg->get_copy_data;

Retrieves the next row during COPY OUT.  Returns the row bytes,
the integer C<-1> when the stream is complete, or C<undef> if nothing
is currently buffered (call again after the next read).

=head1 HANDLER METHODS

Each handler is a getter/setter: pass a coderef to install it
(returning the new value), pass C<undef> to clear it, or call without
arguments to read the current handler.

=head2 on_connect

Fires once with no arguments after the handshake completes.

=head2 on_error

Fires as C<($error_message)> for connection-level errors (handshake
failure, lost socket, libpq protocol errors).  Per-query errors come
through the query callback, not here.

=head2 on_notify

Fires as C<($channel, $payload, $backend_pid)> for each
LISTEN/NOTIFY message.

=head2 on_notice

Fires as C<($message)> for server NOTICE/WARNING messages.

=head2 on_drain

Fires with no arguments when the libpq send buffer has been fully
flushed during a COPY -- use it to resume C<put_copy_data> after a
0 return.

=head1 CONNECTION INFO