NAME

DBIO::PostgreSQL::Deploy - Deploy and upgrade PostgreSQL schemas via test-deploy-and-compare

VERSION

version 0.900007

DESCRIPTION

DBIO::PostgreSQL::Deploy orchestrates the deployment and upgrade of PostgreSQL schemas using a test-deploy-and-compare strategy. The shared orchestration (install, diff, apply, upgrade) and the temporary-database dance are inherited from DBIO::Deploy::Base::TempDatabase; this class supplies only the genuinely PostgreSQL-specific seams (the CREATE DATABASE / DROP DATABASE dialect and the schema_filter passed to the introspector).

For upgrades, the strategy is:

1. Introspect the live database via pg_catalog
2. Create a temporary database
3. Deploy the desired schema (from DBIO classes) into the temp database
4. Introspect the temp database via pg_catalog
5. Compute the diff between the two models using DBIO::PostgreSQL::Diff
6. Drop the temp database

The temporary database is an empty database made from template0 with the encoding and the collation of the live database ("_create_temp_db"). Before the install DDL runs it is checked to hold nothing but the schema public and the extension plpgsql ("_check_database_empty"); anything else stops the deploy, naming the objects, and the temporary database is dropped. The target model is therefore only what the schema declares: an extension that lives in the database and is not declared appears in the diff as undeclared, as before.

This means PostgreSQL is comparing with itself — the diff is always accurate regardless of how complex the schema features are.

my $deploy = DBIO::PostgreSQL::Deploy->new(
    schema => MyApp::DB->connect($dsn),
);

# Fresh install
$deploy->install;

# Upgrade (test-deploy + compare + apply)
$deploy->upgrade;

# Or in steps:
my $diff = $deploy->diff;
print $diff->summary;
$deploy->apply($diff) if $diff->has_changes;

# A diff that drops something, or changes a column's type in a way that
# may alter stored values, runs only when it is released:
$deploy->upgrade(allow_destructive => 1);
$deploy->apply($diff, dry_run => 1);    # executes nothing, returns the diff

The schema need not load the DBIO::PostgreSQL component. The declarations Deploy reads itself -- pg_extensions for the extension check and pg_schemas for the introspector's schema_filter -- are answered the way "install_ddl" in DBIO::PostgreSQL::DDL answers its own: by the component's defaults when the schema lacks them. A schema without the component therefore deploys and diffs exactly like a component-loaded one that declares nothing.

Declaring pg_schemas makes the deploy restricted: it introspects only those schemas, and because extensions are database-level it creates declared extensions that are missing but drops none. An unrestricted deploy drops every extension the schema does not declare. See "diff".

A schema connected with the connect key schema ("ONE SCHEMA CLASS IN SEVERAL NAMESPACES" in DBIO::PostgreSQL) restricts the deploy made for it to the namespace of that connection, whatever pg_schemas the class declares:

my $schema = MyApp::DB->connect($dsn, $user, $pass, { schema => 'tenant_a' });
my $deploy = $schema->pg_deploy;

$deploy->install;    # creates tenant_a when it is not there, installs into it
$deploy->upgrade;    # compares tenant_a, and nothing beside it

The restriction is this object's. A deploy of the same class over a connection to tenant_b is restricted to tenant_b, at the same time.

ATTRIBUTES

manage_extensions_when_restricted

my $deploy = DBIO::PostgreSQL::Deploy->new(
    schema                            => $schema,
    manage_extensions_when_restricted => 1,
);

Boolean, default false. A deploy restricted by "pg_schemas" in DBIO::PostgreSQL drops no extension (see "diff"), since extensions are database-level and may belong to another application in the same database. Set this to make "diff" drop the extensions the schema does not declare even so; declared ones are created and updated either way. It changes nothing for an unrestricted deploy, which always drops them. Only diff reads it: introspection stays restricted to pg_schemas.

foreign_keys_not_valid

my $deploy = DBIO::PostgreSQL::Deploy->new(
    schema                 => $schema,
    foreign_keys_not_valid => 1,
);

Boolean, default false. Without it the diff creates a foreign key with an ordinary ALTER TABLE ... ADD CONSTRAINT ... FOREIGN KEY, which reads every row of the table. With it the key is added NOT VALID, which reads none, and a VALIDATE CONSTRAINT for each follows as a step of its own, behind all of them ("with_validation" in DBIO::PostgreSQL::Diff::ForeignKey). A key of a table the diff creates is added as ever. apply commits the ADD CONSTRAINT with the rest of the diff and runs each VALIDATE CONSTRAINT after that COMMIT in a transaction of its own, so the lock of the add is not held over the reading of the rows. Rows that break a key end apply with the error, and the key stays NOT VALID. The key is not left NOT VALID for good: the diff reads convalidated, so the next diff (and upgrade) finds a key that is not valid and adds a VALIDATE CONSTRAINT for it; rows that break it make that upgrade fail until they are cleaned up. Only diff (and so upgrade) reads it.

METHODS

install_schema

$deploy->install_schema('tenant_42');

Creates a single PostgreSQL schema (namespace) using CREATE SCHEMA IF NOT EXISTS, and nothing in it. The name is taken exactly and written as an identifier by the server's rule ("quote_ident" in DBIO::PostgreSQL::Util): Tenant42 creates the schema Tenant42, not tenant42.

To install the schema class into a namespace of its own -- one per tenant -- connect with the connect key schema and call "install", which creates the namespace as well:

MyApp::DB->connect($dsn, $user, $pass, { schema => 'tenant_42' })
  ->pg_deploy->install;

install

$deploy->install;

Overrides "install" in DBIO::Deploy::Base to check the declared extensions ("pg_extensions" in DBIO::PostgreSQL) against the server first, then runs the inherited install. See "_check_extensions_available".

_deploy_and_introspect_temp

my $model = $self->_deploy_and_introspect_temp($temp_db);

Overrides "_deploy_and_introspect_temp" in DBIO::Deploy::Base::TempDatabase to check the declared extensions before the install DDL runs in the temporary database. Without this, a declared extension that is missing on the server fails the temp deploy with a cryptic follow-on error (e.g. type "vector" does not exist from a later CREATE TABLE) instead of naming the extension.

_check_temp_db_empty

$self->_check_temp_db_empty($temp_db);

Opens a connection of its own to the temporary database (via "_temp_connect_info" in DBIO::Deploy::Base::TempDatabase, an error of the connect shown with the password masked), runs "_check_database_empty" on it and closes it, before the install DDL runs. It is called from "_deploy_and_introspect_temp", whose error "_build_target_model" in DBIO::Deploy::Base::TempDatabase follows by dropping the temporary database.

_check_database_empty

$self->_check_database_empty($dbh);

Introspects the database behind $dbh without a schema filter and dies with a DBIO::Exception naming every object "_foreign_objects" finds. Returns when the database is empty.

_foreign_objects

my @found = $self->_foreign_objects($model);

The objects of an introspected model that an empty database made from template0 does not hold: every schema but public, every extension but plpgsql, and every type, relation, sequence and function. Each is a description such as table public.t, in that order of kinds and by name. Empty for the model of an empty database. A pure function of the model.

_installed_extension_schemas

my $held = $self->_installed_extension_schemas;   # { citext => 'ext' }

The schemas the live database holds the declared extensions in, for those a temporary database is to put in the same place: installed, in a schema other than public, and neither given a schema by "pg_extensions" in DBIO::PostgreSQL nor fixed by the control file (those two decide, as ever). An extension in the namespace of a connection that names one is left out as well -- the install script refuses an extension there -- and so is one that is not installed. {} when nothing is declared, and then nothing is read.

_execute_ddl

$deploy->_execute_ddl($dbh, $sql);

Core's, with one addition for the temporary database. The install script does not write "pg_search_path" in DBIO::PostgreSQL; a connection of the schema has it as its search_path instead. The handle of the temporary database is a plain DBI connection that no storage sets up, so before the script runs on it the declared path is set on it -- by the rule of "_declared_search_path" in DBIO::PostgreSQL::Storage -- and an object without a pg_schema lands in the schema it lands in on the live database. Otherwise the diff would compare a table in the first schema of the path (live) with one in public (target) and drop the one to create the other. The handle of the live connection is not touched, and a schema that declared no path, or whose connection names its namespace (the script carries that path), sends nothing. Behind a DBIO::Replicated::Storage the hooks are asked of the driver storage of its master (_driver_storage), which the replicated storage does not forward them to.

_extension_control_schemas

my $fixed = $self->_extension_control_schemas;   # { age => 'ag_catalog' }

The schemas the control files of the declared extensions fix, read over the live connection from pg_catalog.pg_available_extension_versions (column schema) for the version CREATE EXTENSION installs, the default one. Only an extension that has one is in the answer: age (ag_catalog), postgis_topology (topology), postgis_tiger_geocoder (tiger), pg_cron and plpgsql (pg_catalog) -- the server answers, no list is built in. {} when nothing is declared, and then nothing is read.

A declared schema other than the fixed one dies, naming the extension and both schemas ("refuse_control_schema" in DBIO::PostgreSQL::DDL): the server would refuse the CREATE EXTENSION, and this is said before the first statement and before the temporary database of a diff is made.

_install_ddl

The install script (core's _install_ddl), with the schemas the control files fix ("_extension_control_schemas") passed to "install_ddl" in DBIO::PostgreSQL::DDL -- for the install and for the temporary database of a diff alike. For the temporary database only, the schemas the live database holds the extensions in ("_installed_extension_schemas") go along as extension_installed_schemas; install against the live database passes none.

_check_extensions_available

$deploy->_check_extensions_available;

Checks every extension declared via $schema->pg_extensions against pg_catalog.pg_available_extensions on the live connection and dies with an actionable DBIO::Exception naming the missing extension(s) and the fix (the names are written as identifiers by the server's rule, and read from the catalog by bind), instead of letting the deploy fail later with a cryptic type error. No-op when nothing is declared. Availability is cluster-wide, so the live connection answers for the temporary database too.

_missing_extension_message

my $msg = DBIO::PostgreSQL::Deploy->_missing_extension_message('vector');

Pure function: builds the actionable error text for the given missing extension names. Kept separate from the catalog query so it is testable offline.

_new_introspect

my $intro = $self->_new_introspect($dbh);

Factory for the introspector. No introspector class is made for an extension: what an extension knows about the model reaches the deploy through the list ("EXTENSIONS").

The base class only passes dbh; here we also forward the schema_filter derived from the connected schema's pg_schemas so introspection stays scoped to the schemas this driver manages.

And qualified_names ("qualified_names" in DBIO::PostgreSQL::Introspect), the default of the introspector, set here as well so that a subclass cannot lose it: both databases of a diff -- the live one, read in the caller's session, and the temporary one, read in the session that installed it -- are read under an empty search_path. PostgreSQL writes a name without its schema whenever the asking session's search_path finds it, so read each under its own, one trigger, index, function or column type was two texts, and the diff of a schema just installed dropped and created them again in every session but the one that installed it. The statements of a diff are those texts as well, and are run in the caller's session: with the schema in every name they reach the objects the temporary database meant.

An extension the database has in a schema of its own (CREATE EXTENSION citext WITH SCHEMA ext) that pg_extensions does not give that schema, and whose control file fixes none, is installed by the temporary database in that same schema ("_installed_extension_schemas"). Otherwise it would have it in public, a column of one of its types would be ext.citext here and public.citext there, and the diff would have an ALTER COLUMN ... TYPE public.citext the database cannot run. A declared schema (pg_extensions(citext => { schema => 'ext' })) and the one a control file fixes decide first, as before; a declared schema the database does not have is moved to (point 8). An extension the database does not have yet is created in public.

_build_target_model

my $model = $self->_build_target_model;

The inherited model of the temporary database ("_build_target_model" in DBIO::Deploy::Base::TempDatabase), with the schemas "pg_extensions" in DBIO::PostgreSQL declared marked ("_mark_extension_schemas").

_mark_extension_schemas

$model = $self->_mark_extension_schemas($model);

Sets declared_schema on the entry of each extension in the extensions section of $model for which "pg_extension_schemas" in DBIO::PostgreSQL names a schema, and returns the model. The temporary database has every extension in some schema, declared or not, and the model cannot tell which was meant; "diff" in DBIO::PostgreSQL::Diff::Extension compares only the declared ones, so an extension a list names is left where the database has it.

Every declared extension gets install_schema as well: its declared schema, else the schema the database holds it in when the temporary database put it there ("_installed_extension_schemas"), else public. An extension whose control file fixes a schema ("_extension_control_schemas") gets control_schema instead, and its CREATE EXTENSION is written without the clause: the server installs it there, creating the schema, and refuses WITH SCHEMA for one that is not there yet. That is the schema a CREATE EXTENSION of the diff names ("as_sql" in DBIO::PostgreSQL::Diff::Extension) -- the session that applies the diff has some other schema first in its search_path (the namespace of a connection with the connect key schema, ag_catalog after the activation of age), and an unqualified CREATE EXTENSION would land there. install_schema moves nothing: an extension both sides have, installed in another schema than public and declared without one, stays where it is.

On a connection that names its namespace (connect key schema) the deploy sees that namespace alone ("_schema_filter"), so the diff cannot tell whether the schema of a declared extension exists, and a diff before the first install would write a CREATE EXTENSION ... WITH SCHEMA the server refuses. The entry gets create_schema then -- set when the schema it is created in is not public -- and its create is written behind a creation of that schema that looks it up in pg_namespace first ("as_sql" in DBIO::PostgreSQL::Diff::Extension).

_mark_namespace

$model = $self->_mark_namespace($model);

On a connection that names its namespace (connect key schema) sets create_if_missing on the namespace's entry in the schemas of the target model, so that the diff creates it with a lookup in pg_namespace instead of a CREATE SCHEMA that needs CREATE on the database even for a namespace that is there ("create_schema_if_missing" in DBIO::PostgreSQL::Util). Any other connection: the model is returned as it was.

_schema_filter

my $filter = $self->_schema_filter;   # ArrayRef or undef

The schemas (namespaces) this deploy is restricted to. For a schema connected with the connect key schema that is the namespace of its connection and no other -- read from the storage of this schema object, so two connections of one class answer each for itself. Otherwise it is the schema's "pg_schemas" in DBIO::PostgreSQL, or undef when none are declared. A defined answer makes the deploy restricted -- it scopes the introspector (see "_new_introspect") and keeps "diff" from dropping extensions.

diff

my $diff = $deploy->diff;
my $diff = $deploy->diff({ foreign_keys_not_valid => 1 });

Overrides "diff" in DBIO::Deploy::Base. The optional hash reference holds the options of the diff class, handed to its new ("diff_options" in DBIO::PostgreSQL::Diff: foreign_keys_not_valid); any other key throws. The attribute "foreign_keys_not_valid" of the deploy supplies that option when the caller gives none; a value the caller gives stays. An unrestricted deploy (no "pg_schemas" in DBIO::PostgreSQL declared) owns the whole database and returns the inherited diff unchanged: an extension the schema does not declare is dropped.

A deploy restricted by pg_schemas, or by the namespace of its connection ("_schema_filter"), does not own the database's extensions -- they are database-level, outside every schema it manages, and may belong to another application in the same database. Its diff still creates declared extensions that are missing and updates their versions, but it drops no extension. The source and target models are left as introspected; only the DROP EXTENSION operations are withheld. With "manage_extensions_when_restricted" set, they are not.

Either way the operations are built here, not on first use: a change DBIO::PostgreSQL::Diff refuses (refusing to diff: ..., see "WHAT IS REFUSED" in DBIO::PostgreSQL::Diff) makes diff die, not a later as_sql or apply.

_check_before_apply

$self->_check_before_apply($diff);

The driver's part of "apply" in DBIO::Deploy::Base, which this class inherits together with upgrade (the same code, not a copy): once the diff is released -- refusals, and allow_destructive for a drop or a column type change that may alter stored values ("lossy" in DBIO::PostgreSQL::Diff::Column) -- and before the first statement, it takes one look at the live rows ("_refuse_unfillable"): what the server would refuse half way through the diff for the rows already in a table is refused before the first statement runs. The statements are rendered and run by the default _execute_diff; an operation that has no statement refuses there, ahead of the first one.

_refuse_unfillable

$self->_refuse_unfillable($diff, $dbh);

Looks at the rows of the live tables and dies with a DBIO::Exception naming table and column, ahead of the first statement of $diff:

  • a column the diff adds that is NOT NULL without a default (not an identity or a generated column; serial has a default in the model) to a table that holds rows: PostgreSQL refuses to add the column S.T.C: it is NOT NULL without a default, and table S.T holds rows ...;

  • a column that becomes NOT NULL in a table that has a NULL in it: PostgreSQL refuses to make the column S.T.C NOT NULL: table S.T holds rows where it is NULL.

An empty table, and a table with no NULL in the column, pass. A table the diff itself creates is not looked at: it has no rows.

_resolve_extension_list

my $list = $self->_resolve_extension_list;   # DBIO::Extension::List, or undef

The declared list of extensions resolved to classes, without the installed state and without the database: the classes are loaded, their interface version and driver checked. undef when the schema declares none. A distribution that is not installed, a class that does not load, a wrong interface version and a class of another driver throw here (DBIO::Extension::List).

_extension_list

my $entries = $self->_extension_list;

The hook of "_extension_list" in DBIO::Deploy::Base: the entries of "_resolve_extension_list" with the installed state attached, read from pg_catalog.pg_extension over the live connection (installed, version, schema; installed is 0 for a declared extension the database does not have). [] when the schema declares none, and then nothing is read.

_installed_extensions

my $state = $self->_installed_extensions(\@names);
# { postgis => { installed => 1, version => '3.4.2', schema => 'gis' },
#   age     => { installed => 0 } }

Reads pg_catalog.pg_extension over the live connection for the given names and answers the installed state of each: installed, and for an installed one version and schema (the schema the extension depends on). Every name asked is in the answer.

_extension_driver_helpers

The helpers every extension gets as $ctx->{driver}: quote_ident, quote_qualified, qualified_key and the address constructors schema, table, column and type ("Addresses").

_extension_connection_schema

The namespace of the connection ("ONE SCHEMA CLASS IN SEVERAL NAMESPACES" in DBIO::PostgreSQL), or undef, for $ctx->{connection_schema}.

_extension_restricted

True when "_schema_filter" answers, for $ctx->{restricted}.

_apply_extension_claims

$self->_apply_extension_claims($model, \@addresses);

Removes the claimed objects from the model with their cascade ("Claims and their cascade").

_apply_extension_annotations

$self->_apply_extension_annotations($model, \@triples);

Sets the attributes on the objects of the model ("Annotations").

_apply_extension_states

$self->_apply_extension_states($model, \%states);

Puts the states under $model->{extension_states}, locked ("State").

_temp_dsn

my $temp_dsn = $self->_temp_dsn($dsn, $temp_db);

The DSN of the temporary database: the live $dsn with its database name replaced by $temp_db, or with it added when there is none. The DSN is read by the rule of "dsn_names_target" in DBIO::PostgreSQL::Util -- parameters separated by whitespace or ; outside single quotes, a value bare or in single quotes with a backslash as the escape, db and database for dbname, a leading dbi:Pg(attributes): kept -- so every other parameter (host, port, sslmode, ...) stays as it was written, in a DSN with blanks as separators and with a quoted value that holds a ; alike. The name is written by "quote_dsn_value" in DBIO::PostgreSQL::Util. A libpq URI (postgresql://...) gets the name as its path, any dbname parameter of its query removed.

The result is checked by dsn_names_target before it is returned. A DSN that cannot be read as parameters throws, the message naming no value.

_create_temp_db

my $name = $self->_create_temp_db($dbh);

Creates an empty database from template0 (CREATE DATABASE ... TEMPLATE template0), with the encoding and the collation of the live database: its ENCODING, LC_COLLATE and LC_CTYPE and, where the server has them, LOCALE_PROVIDER with ICU_LOCALE or BUILTIN_LOCALE and ICU_RULES, all read from pg_database ("_locale_catalog_sql", "_create_database_sql"). template0 cannot be connected to and is never changed, so the temporary database holds nothing but what the install DDL puts there, and the target model is only what the schema declares ("_check_temp_db_empty").

PostgreSQL CREATE DATABASE cannot run inside a transaction block, so the dbh must be in autocommit mode (core hands out such a handle). A handle with AutoCommit off dies before any statement runs; its transaction is neither committed nor changed. Returns the new database name (temp_db_prefix . $$ . '_' . time() . '_' . 8 hex digits). The last part is random (Crypt::URandom), so the name cannot be known ahead; a prefix that leaves the name longer than 63 bytes is refused.

_locale_catalog_sql

my $sql = $self->_locale_catalog_sql($server_version);

The query for the row "_create_database_sql" takes: the encoding, collation and locale of current_database() in pg_database. It names only the columns the server has (datlocprovider from 15, daticulocale from 15 and datlocale from 17, daticurules from 16); the others are NULL. $server_version is $dbh->{pg_server_version}.

_create_database_sql

my $sql = $self->_create_database_sql($name, $server_version, $row);

The CREATE DATABASE statement of the temporary database $name, a pure function of the server version and the row of "_locale_catalog_sql" (keys encoding, collate, ctype, provider, locale, icu_rules). It is always TEMPLATE template0 with ENCODING, LC_COLLATE and LC_CTYPE. From PostgreSQL 15 it names the LOCALE_PROVIDER too, with ICU_LOCALE for icu and, for builtin (17), BUILTIN_LOCALE; from 16 ICU_RULES where the database has rules. Every value from the catalog is written as a literal ("quote_literal" in DBIO::PostgreSQL::Util).

_drop_temp_db

$self->_drop_temp_db($dbh, $name);

Drops the temporary database. The dbh must be in autocommit mode; a handle inside a transaction dies before any statement runs (symmetric to "_create_temp_db").

EXTENSIONS

The database extensions a schema has are a declared list the deploy runs (ADR 0066 of DBIO core). This class is the driver's side of it; the protocol itself -- the phases, the merges and their refusals -- is core's ("diff" in DBIO::Deploy::Base, DBIO::Extension::Protocol), and the classes of the extensions are the family's (DBIO::Extension, DBIO::PostgreSQL::Extension).

The form of the declaration

The list is "pg_extensions" in DBIO::PostgreSQL and nothing else; an extension is not pulled in by loading a component.

__PACKAGE__->pg_extensions('age', postgis => { schema => 'gis' }, 'citext');
__PACKAGE__->pg_extensions(vector => { class => 'MyApp::DB::Extension::Vector' });

A name the family has a class for gets it from the fixed table of DBIO::PostgreSQL::Extension (age, postgis, postgis_topology); the option class names the class of an extension outside the family and wins; any other name gets the plain class, which has no rules. The class is loaded and its interface version and driver checked when the list is resolved ("_extension_list"): at "install", and at "diff". A distribution that is not installed refuses, naming it.

Installed state

The installed state of each declared extension is read from pg_catalog.pg_extension over the live connection and attached to its entry: installed, version, schema. It is what the rules see in $ctx->{self} and $ctx->{peers}. An extension that is installed but not declared is not in the list; the member filter of DBIO::PostgreSQL::Introspect still keeps its objects out of the model.

What a deploy does with an extension

Creating, updating and dropping the extension is the existing diff of DBIO::PostgreSQL::Diff::Extension; the protocol adds to it, it does not replace it. A declared extension that is missing is created, a declared one with another version is updated, one declared with a schema is moved or refused ("pg_extensions" in DBIO::PostgreSQL). An installed extension that is not declared is dropped by an unrestricted deploy and kept by a restricted one ("diff", "manage_extensions_when_restricted"), whatever rules it has: the list only holds what is declared, so an undeclared extension's rules do not run. The deploy is restricted for the protocol ($ctx->{restricted}) when "_schema_filter" answers, i.e. with pg_schemas or the namespace of the connection.

Addresses

An address names an object of the model. The deploy knows four kinds; an address of another kind is refused, naming it.

[ schema => $name ]                 a schema (namespace)
[ table  => $key ]                  a table, view or any relation, by the key of the model
[ column => $table_key, $column ]   one column of a table
[ type   => $key ]                  an enum, composite or range type, by the key of the model

A key is where the model files an object, schema.name ("qualified_key" in DBIO::PostgreSQL::Introspect); the helpers in $ctx->{driver} build them: quote_ident, quote_qualified, qualified_key($schema, $name), and the address constructors schema($name), table($key) or table($schema, $name), column($table_key, $column) or column($schema, $table, $column), type($key) or type($schema, $name).

Claims and their cascade

An extension claims an address when the object is its own and not the application's (AGE: the schema of a graph). Claiming removes the object from the model, on both sides of a diff, so the diff neither creates nor drops it. An address the model does not hold is passed over: claiming is idempotent.

  • A claimed schema takes the schema, every table of it with what the table cascades (below), and every type, function and sequence of it.

  • A claimed table takes the table and its columns, indexes, triggers, policies, foreign keys, CHECK constraints and the sequences that belong to its columns (identity columns included).

  • A claimed column takes the column and the sequences that belong to it. Indexes and constraints over it are the extension's to claim by their table.

  • A claimed type takes the type.

What is not followed: a foreign key of another table that points at a claimed table, a view outside the claimed object that reads it, and a view's depends_on entry. They stay as the database has them.

Annotations

An annotation is [ $address, $attribute, $value ]: the attribute is set on the model's entry of the object (the column's hash, the table's, the type's or the schema's), where the diff's refusals and the rules of the next phase can read it (old_info and new_info of a verdict carry them). It is set on both sides of a diff. An object the model does not hold is passed over, since one side of a diff may not have it yet. An attribute that the model already carries with another value is refused, naming object and attribute: an extension adds to an object, it does not rewrite what the introspection read. Two extensions that give one attribute two values are refused by the protocol.

State

What an extension's inspect returned is put into the model as $model->{extension_states}{$name}, read-only all the way down (hashes locked with Hash::Util, arrays and their elements read-only); the section extensions that the introspection fills is not touched. A deploy never creates or drops it.

Verdicts

A change of the type of a column is asked of the extensions before it is written ("diff" in DBIO::PostgreSQL::Diff::Column): { using => $expr } is written as the USING of the statement, in place of the cast the diff would write, and { refuse => [...] } refuses the diff with every message.

Not here

The activation of the extensions per connection (LOAD, the search_path, "_apply_connection_schema" in DBIO::PostgreSQL::Storage) and the registration of the storage layers the classes name ("connection" in DBIO::PostgreSQL) are the connect path's and the storage's, not the deploy's. The install script of a connection that names its namespace sets the search_path of "connection_search_path" in DBIO::PostgreSQL::Util at its head, without the activation entries: an install needs none of them, and the extension's activation is not asked outside a connection.

SEE ALSO

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.