view release on metacpan or  search on metacpan

README  view on Meta::CPAN

        $pg->keep_alive(1);
        my $bool = $pg->keep_alive;

    When true, the read watcher keeps "EV::run" alive even when the callback
    queue is empty. Required when waiting for server-side "NOTIFY" events
    via "on_notify" -- without this flag the loop would exit as soon as the
    "LISTEN" query completes. Getter/setter.

  skip_pending
        $pg->skip_pending;

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

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 "query_params" or "query_prepared"
    -- "query" is rejected.

  enter_pipeline
        $pg->enter_pipeline;

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

  exit_pipeline
        $pg->exit_pipeline;

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

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

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

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

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

  send_flush_request
        $pg->send_flush_request;

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

  pipeline_status
        my $st = $pg->pipeline_status;

    One of "PQ_PIPELINE_OFF", "PQ_PIPELINE_ON", or "PQ_PIPELINE_ABORTED".

COPY METHODS
    A "COPY" command runs in two phases: the query callback first fires with
    a string tag ("COPY_IN" / "COPY_OUT" / "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 eg/copy_in.pl and
    eg/copy_out.pl.

  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
    "on_drain", then retry), or -1 on error.

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

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

  get_copy_data
        my $row = $pg->get_copy_data;

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

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

  on_connect
    Fires once with no arguments after the handshake completes.

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

  on_notify
    Fires as "($channel, $payload, $backend_pid)" for each LISTEN/NOTIFY
    message.

  on_notice
    Fires as "($message)" for server NOTICE/WARNING messages.

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

CONNECTION INFO
    String accessors ("db", "user", "host", "hostaddr", "port",
    "error_message", "parameter_status", "ssl_attribute") return "undef"
    when not connected. Integer accessors return a default value (typically
    0 or -1). Methods that require an active connection ("client_encoding",
    "set_client_encoding", "set_error_verbosity",
    "set_error_context_visibility", "conninfo") croak otherwise.

  error_message
        my $msg = $pg->error_message;