NAME

DBIO::PostgreSQL::EV::TransactionContext - Pinned connection context for an async PostgreSQL transaction

VERSION

version 0.900007

DESCRIPTION

The pinned-connection context DBIO::PostgreSQL::EV::Storage hands to a txn_do_async coderef -- see "_txn_context_class" in DBIO::PostgreSQL::EV::Storage.

Everything it does is inherited from DBIO::Storage::Async::TransactionContext, the generic context core ships since ADR 0030 §4: storage, txn_conn, pool, in_txn, the non-releasing _query_async, the five *_async CRUD methods pinned through core's _run_crud_pinned ("_run_crud" in DBIO::Storage::Async) and their blocking ->get siblings, the sql_maker / debug / pipeline / txn_do_async delegations, and _context_active / _invalidate (ADR 0045), which context-bound DBIO::ResultSet / DBIO::Row / DBIO::ResultSetColumn *_async ops consult before routing onto the context.

The blocking siblings wait through "await" in DBIO::PostgreSQL::EV::Future, and the coderef that calls them runs inside the BEGIN's callback on the pinned connection. Every one of them sends its statement on that connection, and a wait for it there would make EV::Pg hand the result to the BEGIN's callback and spin, so each is refused: it dies with "Blocking wait refused: ...", which fails the coderef. Use the *_async methods in the coderef and chain with then.

A blocking call on the storage in the coderef -- $storage->select where $ctx->select_async was meant -- does not run on the transaction's connection: it takes another one from the pool, and the transaction keeps its own until the coderef has returned. With pool_size => 1, or with every connection held by a callback the call is nested in, no connection can come back while it waits, and it is refused the same way: it dies with "Blocking wait refused: ...", is never sent, and the transaction is rolled back ("await" in DBIO::PostgreSQL::EV::Future).

The pinned connection runs its statements one at a time, in the order they were issued ("_query_async_pinned" in DBIO::PostgreSQL::EV::Storage). A coderef that dies -- or is refused a blocking wait -- while one of its statements is still running therefore rolls back cleanly: core's ROLLBACK goes out once that statement has its result, and the connection goes back to the pool IDLE. Several *_async calls on the context may be issued without waiting for each other; they run one after the other.

Every statement the context hands out counts, awaited or not: core waits for all of them before COMMIT, and when one failed it sends ROLLBACK instead and the transaction fails with that statement's error -- also when the coderef caught the failure ("txn_do_async" in DBIO::Storage::Async). A statement the context never saw -- one in a pipeline batch whose coderef dropped its error, or one sent on "txn_pg" past the context -- still aborts the transaction on the server, and PostgreSQL answers the COMMIT with ROLLBACK. The transport reports that ("_txn_commit_rolled_back" in DBIO::PostgreSQL::EV::Storage), and the transaction fails with "COMMIT was answered with ROLLBACK" instead of resolving as if it had committed. From the moment COMMIT or ROLLBACK is sent the context refuses every further statement: it would run outside the transaction.

This class adds exactly one thing: the "txn_pg" alias below. The pinning policy this context implements is recorded in ADR 0002; the duplicated-context half of that ADR is superseded by core ADR 0030 §4.

The pinned connection is passed to new under the core constructor key txn_conn, which "_txn_conn_accessor" in DBIO::PostgreSQL::EV::Storage names and core's txn_do_async builds the context with. The constructor dies without txn_conn.

ATTRIBUTES

txn_pg

my $pg = $ctx->txn_pg;

Alias for the inherited "txn_conn" in DBIO::Storage::Async::TransactionContext: the pinned EV::Pg connection handle for the duration of this transaction. The name says which kind of handle is pinned, and it is load bearing: t/21-deploy-async-live.t reaches for it to drive _execute_ddl_async on the pinned connection. txn_conn is the name core's own code reaches for -- deploy_async's transactional branch among them -- so both answer the same handle.

AUTHOR

DBIO Authors

COPYRIGHT AND LICENSE

Copyright (C) 2026 DBIO Authors

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.