NAME
DBIO::PostgreSQL::Age::Extension - Apache AGE as a DBIO database extension: graph schemas are not the application's model
VERSION
version 0.900007
SYNOPSIS
package MyApp::DB;
use DBIO Schema => -pg;
__PACKAGE__->pg_extensions('age');
DESCRIPTION
The extension class of Apache AGE (ADR 0066 of DBIO core). A schema that declares age in pg_extensions has this class in its list of extensions; the driver (DBIO::PostgreSQL) resolves the name age to it, runs it inside deploy and registers its storage layer. Loading a component does not put AGE on the list, and a schema that does not declare age has none of these rules.
Graph schemas are known to the model and are never dropped. create_graph makes a PostgreSQL schema (same name as the graph), one table per label with its indexes and sequences, and an _age_cache_invalidate trigger on each. None of it has a pg_depend row to the age extension, so the driver's member filter does not hide it, and a deploy without pg_schemas would diff it into DROP SCHEMA ... CASCADE. This class tells the protocol which schemas those are.
The class answers:
"inspect" -- the graphs of
ag_catalog.ag_graph, the extension's state, kept read-only in the model;"claims" --
[ schema => $graph_schema ]for each graph; the driver's cascade takes the label tables, their columns, indexes, triggers, sequences, functions and types with it;"activation" --
LOAD 'age'andag_catalogon thesearch_path, as data;"storage_layer" -- DBIO::PostgreSQL::Age::Storage, the runtime surface (
cypher,create_graph, ...), which the driver registers for a declaredage.
AGE and PostGIS. The two rule sets are disjoint: AGE takes whole objects out of the model (phase 1), PostGIS adds attributes to objects that stay (phase 2). Phase 2 sees the model after the claims, so a geometry column that lives in a graph schema is gone before PostGIS annotates; no code in either class is needed for that, and the result does not depend on the order of the two. AGE has no column rules today. When it gets one, it answers undef for a column whose type belongs to an active postgis peer, read from $ctx->{peers}{postgis}. The order independence is checked by DBIO::Test::ExtensionSet (t/50-extension-set.t).
An AGE extension that is not installed has nothing to claim: the probe of ag_catalog.ag_graph finds no table and the state is empty. The probe is a plain catalog read; it needs no LOAD 'age' in the session.
METHODS
extension_interface
Interface version 1 of DBIO::Extension.
name
age, the name in pg_extension.extname.
driver
DBIO::PostgreSQL. An assertion checked after the DSN decided the driver; the extension never determines it (ADR 0032 section 7).
inspect
Phase 0. Reads ag_catalog.ag_graph over $ctx->{dbh} when to_regclass finds it and returns
{ graphs => [ { name => 'social', namespace => 'social' }, ... ] }
in the order of the graph names; namespace is the name of the PostgreSQL schema of the graph. Without the table (extension not installed) the list is empty.
claims
Phase 1. [ schema => $namespace ] for each graph of the state. The cascade belongs to the driver.
activation
{ load => 'age', search_path => ['ag_catalog'] }. The driver turns it into LOAD 'age' and the search_path of a new connection, with the namespace of the connection first.
storage_layer
DBIO::PostgreSQL::Age::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.