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' and ag_catalog on the search_path, as data;

  • "storage_layer" -- DBIO::PostgreSQL::Age::Storage, the runtime surface (cypher, create_graph, ...), which the driver registers for a declared age.

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.