NAME
DBIO::PostgreSQL::Extension - The extension class of a PostgreSQL extension without rules, and the driver's table of the family's classes
VERSION
version 0.900007
SYNOPSIS
# A schema declares the extensions its database has; nothing else is written.
__PACKAGE__->pg_extensions('age', postgis => { schema => 'gis' }, 'citext');
# An extension outside the family names its class
__PACKAGE__->pg_extensions(vector => { class => 'MyApp::DB::Extension::Vector' });
DESCRIPTION
The extension classes of "pg_extensions" in DBIO::PostgreSQL (ADR 0066 of DBIO core). This class is the plain one: it has no rules, so an extension that is declared with it is installed and kept and nothing else is done for it (citext, pgcrypto, pg_trgm, ...). It derives from DBIO::Extension, whose defaults do nothing, and states only the interface version and the driver it belongs to. Its name is undef on purpose: one class serves every name the table and the declaration do not know, and the name of the list's entry stands ("name" in DBIO::Extension).
The table of the family
The driver names the classes the family ships; the class is loaded when the list is resolved (the first deploy that needs it), and a distribution that is not installed refuses with its name:
name class distribution
age DBIO::PostgreSQL::Age::Extension DBIO-PostgreSQL-Age
postgis DBIO::PostgreSQL::PostGIS::Extension DBIO-PostgreSQL-PostGIS
postgis_topology DBIO::PostgreSQL::PostGIS::Topology::Extension DBIO-PostgreSQL-PostGIS
postgis_topology is an engine extension of its own and gets a class of its own, in the distribution of PostGIS (the class name is the driver's choice and fixed here, for the distribution to follow). vector is not in the table: what the driver does for pgvector -- the column type, the inflation, the nearest-neighbour query -- is done by the result and result set components from the column's type, not by a rule of the deploy, and the driver has no rule of the deploy to move into a class. vector is therefore a plain extension. A class of its own for it (a dimension that changes is refused, say) is a class the application names: vector => { class => 'MyApp::DB::Extension::Vector' }, and the family can add it to the table when it ships one.
postgis_topology
Measured on PostgreSQL 18 with PostGIS 3.6 in a database of its own (t/149-postgis-topology-runtime-schemas-live.t keeps it true):
CREATE EXTENSION postgis_topologymakes the schematopology. Its tables (layer,topology) and its sequence are members of the extension (pg_dependdeptypee); the schema is not -- the extension depends on it, andDROP EXTENSIONleaves it behind.topology.CreateTopology('t1')makes a runtime schemat1with the tablesedge_data,face,node,relation, a viewedge, sequences and a trigger onrelation. None of them is a member of the extension, nor is the schema: they are ordinary objects of the database. A deploy sees them as model objects -- schema, tables, view, trigger, sequences -- exactly as it sees the tables of the application.DROP EXTENSION postgis_topologyis refused while a topology exists (a trigger oft1.relationdepends on a function of the extension), and it does not take the topology along.
What that means for a deploy with this version of the driver:
postgis_topology undeclared, unrestricted deploy: the diff drops the topology's objects as model objects (trigger, view, tables, then the extensions, then the schemas
t1andtopology), in an order that applies; it is in the summary, line by line. A restricted deploy keeps all of it.postgis_topology declared, unrestricted deploy:
t1is a schema the target model does not have, so the diff drops it with everything in it, data included. That is the danger. The plain class, which is whatpostgis_topologygets until the PostGIS distribution shipsDBIO::PostgreSQL::PostGIS::Topology::Extension, does not prevent it.
Recommendation for the distribution's class: inspect reads topology.topology (name per topology) when the extension is installed, and claims returns [ schema => $name ] for each -- the way AGE claims its graph schemas. The driver's cascade then takes the tables, view, trigger and sequences of the schema out of both models, and the deploy neither creates nor drops them. The schema topology itself needs no claim: the target model creates it with the extension and the diff leaves it alone. No code in the driver is needed for this beyond the table entry that is there.
METHODS
extension_interface
The interface version of DBIO::Extension, 1.
driver
DBIO::PostgreSQL, the assertion that is checked once the DSN has decided the driver ("check_driver" in DBIO::Extension::List).
family_class
my ($class, $distribution) = DBIO::PostgreSQL::Extension->family_class('postgis');
The table of the family: the class and the distribution that ships it for a name the family has a class for, the empty list for any other name. This is the class_table "_extension_list" in DBIO::PostgreSQL::Deploy hands to DBIO::Extension::List.
resolve_list
my $list = DBIO::PostgreSQL::Extension->resolve_list($schema);
my $list = DBIO::PostgreSQL::Extension->resolve_list($schema, check_driver => 0);
The one place that turns the declaration of a schema (class or instance; "pg_extensions" in DBIO::PostgreSQL, pg_extension_schemas, pg_extension_classes) into a DBIO::Extension::List: the family table, the option class, the plain class. Classes are loaded and their interface version is checked. Returns undef for a schema that declares none.
Unless check_driver is false the driver assertion of every class is checked as well ("check_driver" in DBIO::Extension::List); that is for a caller that runs after the driver is resolved -- the deploy, a new connection. Only the registration of the storage layers at connection passes false: the layer is chosen before the DSN has decided anything, and the assertion waits for the first use.
driver_helpers
The helpers every extension gets as $ctx->{driver}, see "Addresses" in DBIO::PostgreSQL::Deploy: quote_ident, quote_qualified, qualified_key and the address constructors schema, table, column and type.
AUTHOR
DBIO & DBIx::Class Authors
COPYRIGHT AND LICENSE
Copyright (C) 2026 DBIO Authors Portions Copyright (C) 2005-2025 DBIx::Class Authors Based on DBIx::Class, heavily modified.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.