view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    INSERT / UPDATE / DELETE
        "($cmd_tuples)" -- the string returned by "PQcmdTuples" (e.g. "1",
        "0").

    Describe
        "(\%meta)" with keys "nfields", "nparams", and (when non-zero)
        "fields" (arrayref of "{name, type}" hashes) and "paramtypes"
        (arrayref of OIDs).

    COPY
        "("COPY_IN")", "("COPY_OUT")", or "("COPY_BOTH")".

    Pipeline sync
        "(1)".

    Error
        "(undef, $error_message)".

    Exceptions thrown inside callbacks are caught and emitted as warnings.

CONSTRUCTOR
  new
        my $pg = EV::Pg->new(%args);

    Arguments:

    conninfo
        libpq connection string. If provided, "connect" is called
        immediately.

    conninfo_params
        Hashref of connection parameters (e.g. "{ host => 'localhost',
        dbname => 'mydb', port => '5432' }"). Alternative to "conninfo". If
        provided, "connect_params" is called immediately.

    expand_dbname
        If true and "conninfo_params" is used, the "dbname" value is parsed
        as a connection string (allowing "dbname => 'postgresql://...'").

    on_connect
        Callback invoked (with no arguments) when the connection is
        established.

    on_error
        Callback invoked as "($error_message)" on connection-level errors.
        Defaults to "sub { die @_ }".

    on_notify
        Callback invoked as "($channel, $payload, $backend_pid)" on
        LISTEN/NOTIFY messages.

    on_notice
        Callback invoked as "($message)" on PostgreSQL notice/warning
        messages.

    on_drain
        Callback invoked (with no arguments) when the send buffer has been
        flushed during COPY IN. Useful for resuming "put_copy_data" after it
        returns 0.

    keep_alive
        When true, the connection keeps "EV::run" alive even when no queries
        are pending. See "keep_alive".

    loop
        An EV loop object. Defaults to "EV::default_loop".

CONNECTION METHODS
  connect
        $pg->connect($conninfo);

    Initiates an asynchronous connection. The "on_connect" handler fires on
    success; "on_error" fires on failure.

  connect_params
        $pg->connect_params(\%params);
        $pg->connect_params(\%params, $expand_dbname);

    Initiates an asynchronous connection using keyword/value parameters
    instead of a connection string. $expand_dbname allows the "dbname"
    parameter to contain a full connection URI.

  reset
        $pg->reset;

    Drops the current connection and reconnects using the original conninfo.
    Pending callbacks receive "(undef, "connection reset")". Alias:
    "reconnect".

  finish
        $pg->finish;

    Closes the connection. Pending callbacks receive "(undef, "connection
    finished")". Alias: "disconnect".

  is_connected
        my $bool = $pg->is_connected;

    Returns 1 if connected and ready for queries.

  status
        my $st = $pg->status;

    Returns the libpq connection status ("CONNECTION_OK" or
    "CONNECTION_BAD").

QUERY METHODS
  query
        $pg->query($sql, sub { my ($result, $err) = @_; });

    Sends a simple query. Not allowed in pipeline mode -- use "query_params"
    instead. Multi-statement strings (e.g. "SELECT 1; SELECT 2") are
    supported but only the last result is delivered to the callback.
    PostgreSQL stops executing after the first error, so errors always
    appear as the last result.

  query_params
        $pg->query_params($sql, \@params, sub { my ($result, $err) = @_; });

    Sends a parameterized query. Parameters are referenced in SQL as $1, $2,
    etc. "undef" values are sent as SQL NULL.

  prepare

README  view on Meta::CPAN

    Describes a prepared statement. The callback receives a hashref with
    keys "nfields" and "nparams". When "nfields" is non-zero, a "fields" key
    is also present (arrayref of "{name, type}" hashes). When "nparams" is
    non-zero, a "paramtypes" key is also present (arrayref of OIDs).

  describe_portal
        $pg->describe_portal($name, sub { my ($meta, $err) = @_; });

    Describes a portal. The callback receives the same hashref structure as
    "describe_prepared".

  set_single_row_mode
        my $ok = $pg->set_single_row_mode;

    Switches the most recently sent query to single-row mode. Returns 1 on
    success, 0 on failure (e.g. no query pending). The callback fires once
    per row with "(\@rows)" where @rows is an arrayref containing a single
    row (e.g. "[[$col1, $col2, ...]]"), then a final empty "(\@rows)" (where
    @rows has zero elements) for the completion.

  set_chunked_rows_mode
        my $ok = $pg->set_chunked_rows_mode($chunk_size);

    Switches the most recently sent query to chunked rows mode, delivering
    up to $chunk_size rows at a time (requires libpq >= 17). Like single-row
    mode, but with lower per-callback overhead for large result sets.
    Returns 1 on success, 0 on failure.

  close_prepared
        $pg->close_prepared($name, sub { my ($result, $err) = @_; });

    Closes (deallocates) a prepared statement at protocol level (requires
    libpq >= 17). The callback receives an empty string ("") on success.
    Works in pipeline mode, unlike "DEALLOCATE" SQL.

  close_portal
        $pg->close_portal($name, sub { my ($result, $err) = @_; });

    Closes a portal at protocol level (requires libpq >= 17). The callback
    receives an empty string ("") on success.

  cancel
        my $err = $pg->cancel;

    Sends a cancel request using the legacy "PQcancel" API. This is a
    blocking call. Returns "undef" on success, an error string on failure.

  cancel_async
        $pg->cancel_async(sub { my ($err) = @_; });

    Sends an asynchronous cancel request using the "PQcancelConn" API
    (requires libpq >= 17). The callback receives no arguments on success,
    or an error string on failure. Croaks if libpq was built without async
    cancel support ("LIBPQ_HAS_ASYNC_CANCEL").

  pending_count
        my $n = $pg->pending_count;

    Returns the number of callbacks in the queue.

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

    When true, the connection's read watcher keeps "EV::run" alive even when
    no queries are pending. Useful when waiting for server-side "NOTIFY"
    events via "on_notify" — without this flag the event loop would exit
    after the "LISTEN" query completes.

  skip_pending
        $pg->skip_pending;

    Cancels all pending callbacks, invoking each with "(undef, "skipped")".

PIPELINE METHODS
  enter_pipeline
        $pg->enter_pipeline;

    Enters pipeline mode. Queries are batched and sent without waiting for
    individual results.

  exit_pipeline
        $pg->exit_pipeline;

    Exits pipeline mode. Croaks if the pipeline is not idle (has pending
    queries).

  pipeline_sync
        $pg->pipeline_sync(sub { my ($ok) = @_; });

    Sends a pipeline sync point. The callback fires with "(1)" when all
    preceding queries have completed. Alias: "sync".

  send_pipeline_sync
        $pg->send_pipeline_sync(sub { my ($ok) = @_; });

    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;

    Sends a flush request, asking the server to deliver results for queries
    sent so far. Alias: "flush".

  pipeline_status
        my $st = $pg->pipeline_status;

    Returns "PQ_PIPELINE_OFF", "PQ_PIPELINE_ON", or "PQ_PIPELINE_ABORTED".

COPY METHODS
  put_copy_data
        my $ok = $pg->put_copy_data($data);

    Sends data to the server during a COPY IN operation. Returns 1 on
    success (data flushed or flush scheduled), 0 if the send buffer is full
    (wait for writability and retry), or -1 on error.

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

    Ends a COPY IN operation. Pass an error message to abort the COPY.
    Returns 1 on success, 0 if the send buffer is full (retry after