NAME
DBIO::PostgreSQL::Age::Storage - PostgreSQL storage with Apache AGE graph support
VERSION
version 0.900007
SYNOPSIS
# Loaded automatically via DBIO::PostgreSQL::Age component.
# Use connect_call_load_age to initialize AGE on each connection:
MyApp::Schema->connect(
$dsn, $user, $pass,
{ on_connect_call => 'load_age' },
);
my $storage = $schema->storage;
$storage->create_graph('social');
my $rows = $storage->cypher(
'social',
q{ MATCH (a:Person {name: $name})-[:KNOWS]->(b) RETURN b.name },
['friend'],
{ name => 'Alice' },
);
$storage->drop_graph('social', 1); # cascade
DESCRIPTION
A storage layer that adds Apache AGE graph database support -- connection initialization, graph lifecycle management, and Cypher query execution -- to a PostgreSQL storage. It is not a storage subclass: it is a plain method package composed over the resolved driver storage at connection time (see DBIO::Storage::Composed). DBIO::PostgreSQL::Age registers it via "register_storage_layer" in DBIO::Schema, so on $schema->connect the live storage isa both this layer and DBIO::PostgreSQL::Storage, and the methods below are callable on that composed storage. Because it is a layer, it stacks cleanly with other extension layers; its methods are disjoint from theirs. It defines no dbio_deploy_class: the deploy class is the driver's, and the model rules of AGE are in DBIO::PostgreSQL::Age::Extension, which names this layer through storage_layer.
Layer rules
Per the storage-layer composition model (DBIO core): this package does not use base a driver storage, defines no constructor, and calls only the documented public storage surface -- dbh_do and throw_exception for the graph methods, plus the connect-action seam _do_query for connect_call_load_age -- each resolved through the composed MRO to the driver base at runtime. _do_query is deliberate: it is the same seam connect_call_do_sql uses, and it is what routes the LOAD 'age' replay onto each freshly-spawned async pool connection; a bare $self->dbh->do would run against the sync dbh instead and defeat the replay. The pure helpers _cypher_sql_bind and decode_agtype are DB-free class-level helpers, shared by composition with the async layer (DBIO::PostgreSQL::Age::Storage::Async) so sync and async build identical SQL and decode identically.
All result columns from cypher() are declared as agtype — Apache AGE's JSON-superset type that represents vertices, edges, paths, and scalar values. Values are returned as strings and can be decoded with a JSON parser.
METHODS
connect_call_load_age
{ on_connect_call => 'load_age' }
Connection callback that loads the Apache AGE shared library into the session and adds ag_catalog to the connection's current search_path (added, not replaced). Where it goes depends on the connection:
With a tenant namespace (connect key
schema),ag_catalogis inserted behind the namespace entry, the first element of the path, so that unqualified DDL still lands in the namespace (PostgreSQL creates in the first existing schema of the path); cypher andcreate_graphkeep working becauseag_catalogstays on the path.Without a namespace,
ag_cataloggoes in front of the path, as before.
When ag_catalog is already an element of the path, at any position and quoted or not (the driver puts it behind the namespace for a declared pg_extensions('age')), the path stays unchanged: the driver's order is respected and nothing is doubled. Must be called before any graph operations.
create_graph
$storage->create_graph('social');
Creates a new Apache AGE graph with the given name.
drop_graph
$storage->drop_graph('social');
$storage->drop_graph('social', 1); # cascade
Drops the named graph. Pass a true second argument to cascade the drop to all vertices and edges within the graph.
cypher_async
create_graph_async
drop_graph_async
The async counterparts of "cypher", "create_graph" and "drop_graph", reachable on the live (composed) storage. Each dispatches through core's three-way async contract: on an async connection ({ async => 'future_io' }, 'ev', ...) they route to the embedded async backend (the composed DBIO::PostgreSQL::Age::Storage::Async layer, which does the real non-blocking work); under { async => 'immediate' } they run the sync method in-process and return an immediately-resolved Future with no event loop; on a plain sync connection they croak. This mirrors the core CRUD *_async methods ("select_async" in DBIO::Storage and friends) -- graph queries have a sync equivalent, so they degrade the same way rather than being backend-only.
Not transaction-pinned. On an async connection all three route to the embedded backend's pooled query seam, so calling one inside a "txn_do_async" in DBIO::Storage::Async body runs it 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. Transactional graph work belongs on the sync surface -- $schema->txn_do(sub { $schema->storage->cypher(...) }) runs on the transaction's own dbh. Full reasoning: "The graph methods are pool-only, not transaction-pinned" in DBIO::PostgreSQL::Age::Storage::Async.
decode_agtype
my $name = $storage->decode_agtype('"alice"'); # "alice"
my $age = $storage->decode_agtype('30'); # 30
my $v = $storage->decode_agtype(
'{"id": 1, "label": "Person", "properties": {"name": "alice"}}::vertex'
); # { id => 1, label => "Person", properties => { name => "alice" } }
my $rows = $storage->cypher(
'social',
q{ RETURN n },
['n'],
);
my $vertex = $storage->decode_agtype($rows->[0]{n}); # manual decode
Decodes a single agtype text value (as returned by cypher()) into native Perl data. Recognised shapes:
String scalar (quoted, e.g.
"alice") — string with quotes strippedInteger / float scalar (e.g.
42,3.14) — Perl numberBoolean (
true,false) —JSON::MaybeXStrue/false objectsNull (
null) —undefMap / list (e.g.
{"name": "alice"},[1, 2, 3]) — hashref / arrayrefVertex / edge — same as the underlying map; the
::vertex/::edgecast annotation AGE appends to every element (checked against AGE 1.8.0, also inside paths, lists and maps) is stripped before decoding, but never inside a string literal, so a property value may contain::vertex.id,label,start_id,end_id,propertiesare preserved as JSON keys.Path — arrayref of decoded vertices and edges (structure preserved, not unwrapped); the
::pathannotation is stripped as wellSQL
NULL(undef) —undef, without a warningNumeric cast (
1.5::numeric) — the cast is stripped (outside string literals, also inside lists and maps) and the value becomes a Perl number. A value a double cannot hold exactly (more than 15 significant digits, e.g.0.1234567890123456789::numeric) is returned as the exact string instead, scalar and inside a container alike; an integer that fits an IV stays an exact numberA value with the UTF8 flag (what DBD::Pg returns for a UTF-8 client encoding) is decoded as characters, a byte string as UTF-8 bytes; either way non-ASCII text arrives as the same characters
A map or list that is not valid agtype JSON throws a DBIO::Exception naming the kind (map or list) and the
::vertex/::edge/::pathannotation the value carried, never the value itselfDigit runs are matched once from their first digit, so the time taken grows linearly with the length of the value
Anything else — returned as-is so the caller can post-process it
cypher
my $rows = $storage->cypher(
'social',
q{ MATCH (a:Person)-[:KNOWS]->(b:Person) RETURN a.name, b.name },
[qw( person friend )],
);
# With Cypher parameters:
my $rows = $storage->cypher(
'social',
q{ MATCH (n:Person {name: $name}) RETURN n },
['node'],
{ name => 'Alice' },
);
# Auto-decode each cell into native Perl data:
my $rows = $storage->cypher(
'social',
q{ MATCH (n:Person {name: $name}) RETURN n },
['node'],
{ name => 'Alice' },
{ auto_decode => 1 },
);
# $rows->[0]{node} is now a hashref, not a string.
Executes a Cypher query against the named graph. $columns is an arrayref of result column names; all are declared as agtype. Returns an arrayref of hashrefs with one key per column. Like the graph name, every column name must be a plain identifier ([A-Za-z_][A-Za-z0-9_]*); anything else throws Invalid AGE column name, because the names are placed into the SQL as-is.
The Cypher text is embedded into the SQL as a dollar-quoted string. The quote tag ($dbio_age$, counted up to $dbio_age1$, ... if the text itself contains it) is chosen so that it does not occur in the Cypher text, so a $$ in a string literal is harmless. Values must still go through $params (see below) and never be interpolated into the Cypher text: the text is executed as written.
An optional $params hashref is JSON-encoded and passed as AGE's third argument to cypher() for parameterized queries.
Pass an optional fifth argument, a hashref of options, to control result handling:
auto_decode => 1— apply "decode_agtype" to every cell of every row before returning. Without this option, every cell is a raw agtype string and decoding is the caller's responsibility.
SEE ALSO
DBIO::PostgreSQL::Age - Schema component that activates this storage
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.