NAME
DBIO::PostgreSQL::Age::Storage::Async - Floating async storage layer for Apache AGE (cypher_async)
VERSION
version 0.900007
SYNOPSIS
# Composed automatically for an Age schema opened in ANY async mode whose
# transport can replay LOAD 'age' -- future_io, ev, ....
my $schema = MyApp::Schema->connect(
$dsn, $user, $pass,
{ on_connect_call => 'load_age', async => 'future_io' }, # or 'ev'
);
my $async = $schema->storage->async; # the composed async backend
$async->create_graph_async('social')->then(sub {
$async->cypher_async(
'social',
q{ MATCH (n:Person {name: $name}) RETURN n },
['node'],
{ name => 'Alice' },
{ auto_decode => 1 },
);
})->then(sub {
my ($rows) = @_; # arrayref of hashrefs, one key per column, already decoded
...
});
DESCRIPTION
The floating async storage layer for Apache AGE. It is a plain method package -- not a transport and not a subclass of any transport. Core's storage-layer composition mirrors the registered sync Age layer onto its async sibling by convention (DBIO::PostgreSQL::Age::Storage -> ...::Async) and composes this package (C3) OVER whatever transport the connection's async mode resolves: DBIO::PostgreSQL::Storage::Async for future_io, DBIO::PostgreSQL::EV::Storage for ev. The composed backend isa both this layer and that transport, so cypher_async rides every capable transport without a per-transport class.
Required transport capability
AGE mandates LOAD 'age' (and putting ag_catalog on the search_path) on every pooled connection, replayed through core's pool on_connect seam. This layer therefore declares on_connect_replay as a "required_transport_capabilities"; core's capability gate croaks loudly if a schema tries to compose AGE over a transport that cannot replay connect actions, rather than silently losing the session setup. Both shipped PostgreSQL async transports advertise on_connect_replay.
Separate sync and async entry points
Graph queries have two entry points, on the two composed storages:
sync --
$schema->storage->cypher(...), on the composed sync storage (the DBIO::PostgreSQL::Age::Storage layer over DBIO::PostgreSQL::Storage, a DBIO::Storage::DBI), returns an arrayref of hashrefs.async --
$schema->storage->async->cypher_async(...), on the composed async backend (this layer over a DBIO::Storage::Async transport), returns a Future resolving to the same arrayref of hashrefs. As a convenience the composed sync storage also carries acypher_asyncdispatcher (see "cypher_async" in DBIO::PostgreSQL::Age::Storage):$schema->storage->cypher_async(...)routes to this backend on an async connection and degrades in-process under{ async => 'immediate' }, exactly like the core CRUD*_asyncmethods.
The sync and async surfaces stay separate by design: this layer is not a subclass of DBIO::PostgreSQL::Age::Storage, and it never use bases a storage. Welding the blocking DBI machinery (dbh, dbh_do, txn_do, the driver registry) onto an async transport is exactly what the layer model avoids -- the reason is unchanged, but the mechanism is now composition-by-core, not a parallel-inheritance adapter bolted to one transport. What crosses between the two surfaces is only the two pure, DB-free helpers of the sync layer -- the SQL builder _cypher_sql_bind and decode_agtype -- reused by composition, called as class-level helpers so both entry points build identical SQL and decode identically. auto_decode therefore behaves identically on both.
The graph methods are pool-only, not transaction-pinned
cypher_async, create_graph_async and drop_graph_async all run through the transport's pooled query seam _query_async, which takes a connection out of the pool for the statement and hands it back when the Future resolves. None of the three takes a connection or a context argument, so there is no way to hand them the connection a transaction is pinned to. A pinned seam does exist one level down -- $storage->_query_async_pinned($conn, $sql, $bind), the required transport seam core's own pinned CRUD runs on ("_query_async_pinned" in DBIO::Storage::Async), implemented by both transports this layer composes over -- but nothing on this layer reaches it. The cypher_async dispatcher on the composed sync storage ("cypher_async" in DBIO::PostgreSQL::Age::Storage) is the same path: on an async connection it routes to this pooled backend.
Inside a "txn_do_async" in DBIO::Storage::Async body a graph method therefore runs on a sibling pool connection, outside the transaction:
$schema->storage->txn_do_async(sub {
my ($ctx) = @_;
# WRONG: runs on a sibling pool connection OUTSIDE this transaction. It
# does not see the transaction's uncommitted writes, its own writes commit
# on their own, and a ROLLBACK does not take them back.
return $schema->storage->async->cypher_async(
'social', q{ CREATE (:Person {name: $name}) RETURN 1 }, ['ok'],
{ name => 'Alice' },
);
});
Nothing warns. The query succeeds, on the wrong connection. At the default pool_size of 5 it simply runs beside the transaction; with pool_size => 1 it does not run at all while the transaction is open -- the pool has no second connection to hand out, so the acquire is queued as a waiter that only a release can resolve, and txn_do_async releases its connection after the body's Future has resolved.
One layer up this is exactly the failure ADR 0045 closed for DBIO::ResultSet, DBIO::Row and DBIO::ResultSetColumn, by binding them to the pinned context explicitly ("with_context" in DBIO::ResultSet). The graph surface has no such binding, and cannot borrow that one. The object a txn_do_async coderef is handed -- DBIO::Async::TransactionContext on future_io, which inherits the generic DBIO::Storage::Async::TransactionContext, and DBIO::PostgreSQL::EV::TransactionContext on ev, which mirrors its surface rather than inheriting it; DBIO::Storage::Async::PipelineContext for a "pipeline" in DBIO::Storage::Async batch -- carries a fixed surface: the five CRUD *_async methods, their blocking twins, a pinned _query_async, and a handful of delegations. It does not carry cypher_async, because storage layers are composed onto the storage, never onto a context -- so $ctx->cypher_async(...) dies. Calling this layer's sub with the context as invocant is no way around that either: the body also needs future_class, and _cypher_sql_bind needs throw_exception, neither of which the transaction context answers.
So do not use the async graph methods inside txn_do_async or pipeline. Graph work that has to be transactional belongs on the sync surface, where $schema->txn_do(sub { $schema->storage->cypher(...) }) runs on the transaction's own dbh. Whether the async surface should grow a pinned path is an open design question rather than an oversight: the pinned seam is there, but offering the graph methods on the context the way core's CRUD is offered needs a context-extension seam in core first.
Session setup (LOAD 'age')
This layer does nothing locally for LOAD 'age' -- it defines no connect_call_load_age. The setup rides core's pool on_connect seam: a schema connected with { on_connect_call => 'load_age' } gives the pool an owning sync storage (the composed sync Age storage, which defines connect_call_load_age on its layer), and core replays that connect action synchronously against each freshly-spawned pool connection -- on whichever transport was composed under this layer. LOAD logic belongs to the composed sync Age storage alone.
The '?' placeholder seam
cypher_async / create_graph_async / drop_graph_async hand the transport plain ?-placeholder SQL. Shaping ? to the transport's wire dialect (e.g. DBD::Pg's positional $N) is the transport's concern, applied inside its _query_async (ADR 0032 '?'-seam). The dollar-quoted Cypher body and any $name Cypher parameter reference are not SQL placeholders and survive untouched; only a real ? is rewritten, and only by the transport.
Everything else -- the transport, the connection pool, the CRUD runner, transactions and the SQLMaker -- comes from whichever transport this layer is composed over.
METHODS
required_transport_capabilities
my @caps = DBIO::PostgreSQL::Age::Storage::Async->required_transport_capabilities;
# ('on_connect_replay')
Class method. The transport capabilities this async layer requires. Returns on_connect_replay because LOAD 'age' must replay on every pooled connection. Core's composition capability gate (see "transport_capabilities" in DBIO::Storage::Async) croaks naming this layer, the missing capability and the transport if AGE is composed over a transport that does not advertise it.
cypher_async
my $future = $async->cypher_async(
'social',
q{ MATCH (a:Person)-[:KNOWS]->(b:Person) RETURN a.name, b.name },
[qw( person friend )],
);
# With Cypher parameters:
my $future = $async->cypher_async(
'social',
q{ MATCH (n:Person {name: $name}) RETURN n },
['node'],
{ name => 'Alice' },
);
# Auto-decode each cell into native Perl data (identical to sync cypher):
my $future = $async->cypher_async(
'social',
q{ MATCH (n:Person {name: $name}) RETURN n },
['node'],
{ name => 'Alice' },
{ auto_decode => 1 },
);
The async counterpart of "cypher" in DBIO::PostgreSQL::Age::Storage. Builds the same SQL and binds via the shared _cypher_sql_bind and executes them over the composed transport, returning a Future that resolves to an arrayref of hashrefs (one key per $columns entry) -- exactly the shape sync cypher() returns.
$params, if given, is JSON-encoded and passed as AGE's third cypher() argument. With { auto_decode => 1 } every cell is passed through "decode_agtype" in DBIO::PostgreSQL::Age::Storage inside the Future chain, so the resolved arrayref is already decoded -- identical semantics to sync auto_decode, just async. Without it every cell is a raw agtype string and decoding is the caller's responsibility.
Not transaction-pinned. Like its two siblings this method always runs on a pooled connection: inside a "txn_do_async" in DBIO::Storage::Async body it executes on a sibling connection outside that transaction, and inside a "pipeline" in DBIO::Storage::Async batch it is not batched onto the bracketed connection -- in both cases silently. See "The graph methods are pool-only, not transaction-pinned".
create_graph_async
my $future = $async->create_graph_async('social');
Async counterpart of "create_graph" in DBIO::PostgreSQL::Age::Storage: a thin wrapper that runs ag_catalog.create_graph(?) over the composed transport. Returns a Future.
Not transaction-pinned. Like its two siblings this method always runs on a pooled connection: inside a "txn_do_async" in DBIO::Storage::Async body it executes on a sibling connection outside that transaction, and inside a "pipeline" in DBIO::Storage::Async batch it is not batched onto the bracketed connection -- in both cases silently. See "The graph methods are pool-only, not transaction-pinned".
drop_graph_async
my $future = $async->drop_graph_async('social');
my $future = $async->drop_graph_async('social', 1); # cascade
Async counterpart of "drop_graph" in DBIO::PostgreSQL::Age::Storage: a thin wrapper that runs ag_catalog.drop_graph(?, ?) over the composed transport. Pass a true second argument to cascade the drop. Returns a Future.
Not transaction-pinned. Like its two siblings this method always runs on a pooled connection: inside a "txn_do_async" in DBIO::Storage::Async body it executes on a sibling connection outside that transaction, and inside a "pipeline" in DBIO::Storage::Async batch it is not batched onto the bracketed connection -- in both cases silently. See "The graph methods are pool-only, not transaction-pinned".
SEE ALSO
DBIO::PostgreSQL::Age::Storage - the sync storage layer with
cypher()DBIO::PostgreSQL::Storage::Async - the
future_iotransport this layer composes overDBIO::PostgreSQL::EV::Storage - the
evtransport this layer composes overDBIO::PostgreSQL::Age - Schema component that activates AGE
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.