view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    and "(undef, $error_message)" on error, so

        my ($result, $err) = @_;

    works for every shape: $result is the success payload, $err is defined
    only on error. The shape of $result depends on the query:

    SELECT (or single-row / chunked mode)
        "\@rows" -- arrayref of rows; each row is an arrayref of column
        values with SQL NULL mapping to Perl "undef".

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

    PREPARE / close_prepared / close_portal
        "" -- always an empty string (these commands return no row count).

    describe_prepared / describe_portal
        "\%meta" -- hashref with "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" -- a string tag identifying
        the COPY direction.

    pipeline_sync
        1.

    Exceptions thrown inside callbacks are caught and reported via "warn" so
    that one bad callback does not derail the rest of the queue.

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

    Returns a new EV::Pg object. If "conninfo" or "conninfo_params" is
    supplied, an asynchronous connect starts immediately; otherwise call
    "connect" later.

    Recognized arguments:

    conninfo
        libpq connection string passed to "connect".

    conninfo_params
        Hashref of connection parameters (e.g. "{ host => 'localhost',
        dbname => 'mydb', port => 5432 }"), passed to "connect_params".
        Mutually exclusive with "conninfo".

    expand_dbname
        When true together with "conninfo_params", the "dbname" value is
        itself parsed as a connection string -- so "dbname =>
        'postgresql://host/db?sslmode=require'" works.

    on_connect
        Fires once with no arguments when the handshake completes.

    on_error
        Fires as "($error_message)" on connection-level errors. Defaults to
        "sub { die @_ }"; pass an explicit handler to keep the loop alive.

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

    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 sending after
        "put_copy_data" returned 0.

    keep_alive
        When true, the connection keeps "EV::run" alive even with an empty
        callback queue. See "keep_alive".

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

    Unknown arguments produce a "carp" warning and are otherwise ignored.

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

    Starts an asynchronous connection from a libpq connection string.
    "on_connect" fires on success, "on_error" on failure.

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

    Like "connect" but takes a hashref of keyword/value parameters. When
    $expand_dbname is true, the "dbname" entry may itself be a connection
    string or URI.

  reset
        $pg->reset;

    Drops the current connection and reconnects with the same parameters.
    Pending callbacks fire with "(undef, "connection reset")" first. Alias:
    "reconnect".

  finish
        $pg->finish;

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

  is_connected
        my $bool = $pg->is_connected;

    True if the handshake has completed and the connection is ready for
    queries. False during connect, after "finish", and after a fatal error.

  status
        my $st = $pg->status;

    libpq connection status: "CONNECTION_OK" or "CONNECTION_BAD". Returns
    "CONNECTION_BAD" when not connected.

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

    Sends a simple query. Multi-statement strings (e.g. "SELECT 1; SELECT
    2") are accepted, but only the final result reaches the callback --
    intermediate results are silently discarded, and because PostgreSQL
    stops at the first error, errors always arrive as that final result. Not
    allowed in pipeline mode -- use "query_params" there. Alias: "q".

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

    Sends a parameterized query. Parameters are referenced in SQL as $1, $2,

README  view on Meta::CPAN

        $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 into single-row mode. Must be
    called immediately after a send method ("query", "query_params", ...)
    and before the event loop delivers any results -- a 0 return means no
    query was in the right async state and should be treated as a programmer
    error rather than a runtime condition.

    The query callback then fires once per row with a single-row "\@rows"
    (e.g. "[[$col0, $col1, ...]]"), and once more at the end with an empty
    "\@rows" as the completion sentinel.

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

    Like "set_single_row_mode" but delivers up to $chunk_size rows per
    callback (requires libpq >= 17), reducing per-callback overhead for
    large result sets. Same call-timing constraint and same trailing
    empty-rows completion sentinel.

  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. Blocks the event
    loop for one network round trip; prefer "cancel_async" on libpq >= 17.
    Returns "undef" on success or an error string on failure.

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

    Sends a non-blocking cancel request using the "PQcancelConn" API
    (requires libpq >= 17). The callback receives "(1)" on success or
    "(undef, $errmsg)" on failure. Croaks if a cancel is already in
    progress.

  pending_count
        my $n = $pg->pending_count;

    Number of callbacks currently in the queue (queries sent but not yet
    delivered).

  keep_alive
        $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.