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_catalog is 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 and create_graph keep working because ag_catalog stays on the path.

  • Without a namespace, ag_catalog goes 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 stripped

  • Integer / float scalar (e.g. 42, 3.14) — Perl number

  • Boolean (true, false) — JSON::MaybeXS true/false objects

  • Null (null) — undef

  • Map / list (e.g. {"name": "alice"}, [1, 2, 3]) — hashref / arrayref

  • Vertex / edge — same as the underlying map; the ::vertex / ::edge cast 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, properties are preserved as JSON keys.

  • Path — arrayref of decoded vertices and edges (structure preserved, not unwrapped); the ::path annotation is stripped as well

  • SQL NULL (undef) — undef, without a warning

  • Numeric 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 number

  • A 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 / ::path annotation the value carried, never the value itself

  • Digit 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

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.