view release on metacpan or  search on metacpan

lib/DBIO/PostgreSQL/EV/Storage.pm  view on Meta::CPAN

supplied data to build the returned-columns hashref (ADR 0031 §3).

=head2 future_class

Returns C<'Future'> -- uses L<Future.pm|Future> from CPAN. Plain
L<Future/Future> C<< ->then >> callbacks auto-wrap a non-Future return value
into a resolved Future (ADR 0031 §4), so ResultSet/Row C<< *_async >>
callbacks that return plain values resolve without an explicit
C<< Future->done(...) >> wrap.

=head2 transport_capabilities

  my @caps = DBIO::PostgreSQL::EV::Storage->transport_capabilities;

Class method (see L<DBIO::Storage::Async/transport_capabilities>). Declares the
wire capabilities this transport really provides, so
L<DBIO::Storage::DBI/_async_storage> lets an async extension layer that requires
any of them compose onto it (and croaks naming the gap otherwise, rather than
silently dropping a feature). This transport provides:

=over 4

=item * C<on_connect_replay> -- its pool (L<DBIO::PostgreSQL::EV::Pool>, a
L<DBIO::Storage::PoolBase>) drives core's
L<DBIO::Storage::Async/_setup_pool_connection> on every freshly-spawned
connection, and L</_run_pool_connect_statement> replays the owning sync
storage's C<on_connect_do>/C<on_connect_call> against it (karr #68).

=item * C<listen> / C<notify> -- LISTEN/NOTIFY (L</listen>, L</unlisten>,
L</notify>).

=item * C<copy> -- COPY FROM STDIN bulk load (L</copy_in>).

=item * C<pipeline> -- libpq pipeline mode (L</_pipeline_enter> /
L</_pipeline_sync> / L</_pipeline_exit> under the inherited scaffold).

=back

=head2 connect_info

  $storage->connect_info([ \%conninfo, \%opts ]);

Set connection parameters. C<%conninfo> is passed to L<EV::Pg> as libpq
connection parameters (host, dbname, user, ...). When the embedding sync
storage feeds its own DBI-form connect info
(C<< ['dbi:Pg:...', $user, $pass, \%attrs] >>) it is translated into the async
C<< [ \%conninfo, \%opts ] >> shape first. AccessBroker connect info
(C<< [ $broker ] >>) is detected and wired to the per-spawn credential provider
(the base broker seam), exactly as the sync path does.

This override (rather than the inherited base C<connect_info>) is retained
because the EV transport (a) folds the DBI-form DSN into libpq conninfo inline
and (b) also tears down the dedicated LISTEN connection on reconnect.

=head2 _async_broker_conninfo

  my $conninfo = $storage->_async_broker_conninfo($mode);

AccessBroker seam (see L<DBIO::Storage::Async/ACCESSBROKER CONSUMPTION>): return
one fresh, storage-native libpq conninfo hash for a single new pool connection,
built from the current broker credentials via the inherited normalisation.

=head2 pool

Returns the L<DBIO::PostgreSQL::EV::Pool> connection pool, created lazily on
first access. The pool is wired with C<< storage => $self >> so its
core-shared spawn path (L<DBIO::Storage::PoolBase/_spawn_connection>) replays
the owning sync storage's connect actions on each new connection via
L</_run_pool_connect_statement> (karr #68). Fed the per-spawn
C<conninfo_provider> when an AccessBroker is attached, otherwise the static
conninfo string.

=head2 _txn_context_class

The pinned-connection transaction context the inherited
L<DBIO::Storage::Async/txn_do_async> hands to its coderef:
L<DBIO::PostgreSQL::EV::TransactionContext>.

=head2 _txn_conn_accessor

The constructor key the pinned connection is passed under -- C<pg>, matching
L<DBIO::PostgreSQL::EV::TransactionContext>.

=head2 _transform_sql

Transport-internal SQL shaping (core #70 / ADR 0032). Rewrite C<?> placeholders
to PostgreSQL positional C<$N>, skipping quoted literals / identifiers and the
JSONB C<@?> operator. Called first by L</_query_async> / L</_query_async_pinned>
on the raw C<sql_maker> output; idempotent on already-C<$N> SQL (no bare C<?>
to touch), so a C<$N> passthrough stays intact.

=head2 _query_async

Transport seam. Execute a query on a freshly-acquired pooled connection,
releasing it once the Future is ready. Returns a L<Future> of the raw result
rows (list of column arrayrefs for a result set, or the affected-row count for
plain DML -- ADR 0031 §3), exactly what the inherited C<_run_crud> expects.

Receives SQL in the C<sql_maker> C<?>-placeholder dialect and shapes it into
PostgreSQL's positional C<$N> B<internally> (via L</_transform_sql>) before it
reaches libpq -- the core #70 / ADR 0032 seam contract.

=head2 _query_async_pinned

Transport seam. Like L</_query_async> but runs on the supplied pinned
connection and does B<not> release it -- used for queries inside a pinned
transaction. Shapes the incoming C<?>-dialect SQL internally via
L</_transform_sql> exactly as L</_query_async> does.

=head2 _run_pool_connect_statement

  $storage->_run_pool_connect_statement($conn, $sql, $attrs, @bind);

Native-backend override of the core connect-action runner seam
(L<DBIO::Storage::Async/_run_pool_connect_statement>). The base default drives a
blocking DBI C<do> and croaks on a non-DBI connection; an EV::Pg handle is
neither a C<< { dbh => $dbh } >> wrapper nor a do-capable DBI handle, so this
override drives the statement B<synchronously to completion> on that very
connection over the EV loop.

Called once per freshly-spawned pool connection from