NAME

DBIO::PostgreSQL::Age - Apache AGE graph database support for DBIO::PostgreSQL

VERSION

version 0.900007

SYNOPSIS

package MyApp::Schema;
use DBIO 'Schema', -pg;
__PACKAGE__->pg_extensions('age');
__PACKAGE__->load_components('PostgreSQL::Age');

my $schema = MyApp::Schema->connect(
  $dsn, $user, $pass,
  { on_connect_call => 'load_age' },
);

$schema->storage->create_graph('social');

my $rows = $schema->storage->cypher(
  'social',
  q{ MATCH (a:Person)-[:KNOWS]->(b:Person) RETURN a.name, b.name },
  [qw( person friend )],
);

DESCRIPTION

DBIO::PostgreSQL::Age is the overview of the Apache AGE support in DBIO::PostgreSQL. Apache AGE is a PostgreSQL extension that adds openCypher graph query capabilities via the cypher() SQL function.

The extension is declared in the list. A schema says that its database has AGE with __PACKAGE__->pg_extensions('age') (ADR 0066 of DBIO core). The driver resolves the name to DBIO::PostgreSQL::Age::Extension, which holds everything the model needs to know about AGE (the graph schemas), names the activation of a connection (LOAD 'age', ag_catalog on the search_path) and names the storage layer DBIO::PostgreSQL::Age::Storage with the runtime surface (graph lifecycle and Cypher). The schema names its driver (use DBIO 'Schema', -pg); this component declares none, and neither does the extension class.

Open until the driver resolves the list. Today this component still registers DBIO::PostgreSQL::Age::Storage as a storage layer (via "register_storage_layer" in DBIO::Schema), and load_age (below) is still the connection callback; the driver registers the layer of every declared extension that names one and composes the activation of the list in the connect path (ADR 0066 section 3). Both go from here when it does.

METHODS

connection

Overrides "connection" in DBIO to register DBIO::PostgreSQL::Age::Storage as a storage layer ("register_storage_layer" in DBIO::Schema) before connecting, so it is composed over the resolved driver storage rather than replacing it. This is what lets AGE stack with other PostgreSQL storage-layer extensions and ride every async transport its layer is composed onto.

CONNECTION SETUP

Apache AGE requires LOAD 'age' and ag_catalog on the search_path on each database connection before any graph operations; load_age puts ag_catalog in front of the existing path instead of replacing it. Use the load_age connection callback:

MyApp::Schema->connect(
  $dsn, $user, $pass,
  { on_connect_call => 'load_age' },
);

DEPLOYING BESIDE AGE

Graphs are not part of the schema model of DBIO::PostgreSQL: they are made with "create_graph" in DBIO::PostgreSQL::Age::Storage (and loaded with Cypher), not by $schema->deploy. But the objects create_graph leaves in the database -- the graph's schema, a table per label, sequences, the _age_cache_invalidate triggers -- have no pg_depend row to the extension, so a plain deploy without pg_schemas would diff them into DROP SCHEMA ... CASCADE.

Graph schemas are known to the model and are never dropped. With

__PACKAGE__->pg_extensions('age');

the list of the schema holds DBIO::PostgreSQL::Age::Extension: its inspect reads ag_catalog.ag_graph, its claims name each graph schema ([ schema => $name ]), and the driver removes the claimed schemas with their tables, columns, indexes, triggers, sequences, functions and types from both sides of the diff. The declaration also makes the temporary database the target model is built in create the extension. pg_schemas remains possible on top and does what it does for DBIO::PostgreSQL::Deploy.

Beside DBIO::PostgreSQL::PostGIS the protocol keeps the result independent of the order of the declaration: AGE takes whole objects out (phase 1), PostGIS annotates the columns that stay (phase 2), see "DESCRIPTION" in DBIO::PostgreSQL::Age::Extension. DBIO::PostgreSQL::Age::Deploy and DBIO::PostgreSQL::Age::Introspect are stubs; no deploy class is chained any more.

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.