NAME

DBIO::PostgreSQL::Diff::Extension - Diff operations for PostgreSQL extensions

VERSION

version 0.900007

DESCRIPTION

Represents an extension-level diff operation: CREATE EXTENSION IF NOT EXISTS, DROP EXTENSION, ALTER EXTENSION ... UPDATE TO (version change) or ALTER EXTENSION ... SET SCHEMA (schema change). Extensions are compared by name; version differences produce an update operation, and a declared schema the extension is not in produces a move.

ATTRIBUTES

extension_name

The PostgreSQL extension name (e.g. pgcrypto, postgis).

extension_info

Extension metadata hashref (version, schema_name, relocatable, requires). In the target model it also carries declared_schema where "pg_extensions" in DBIO::PostgreSQL named a schema for the extension, and install_schema -- the schema a create names: the declared one, else public; or, for an extension whose control file fixes its schema, control_schema and no clause: the server installs it there ("_mark_extension_schemas" in DBIO::PostgreSQL::Deploy). create_schema is set on a connection that names its namespace when that schema is not public: a create then creates the schema first.

old_version

For an update operation: the version the source has, an empty string where it carries none. Read by "summary". Not set for create and drop.

new_version

For an update operation: the version the target has, which "as_sql" writes into ALTER EXTENSION ... UPDATE TO. Not set for create and drop.

old_schema

For a move operation: the schema the source has the extension in. Read by "summary".

new_schema

For a move operation: the declared schema, which "as_sql" writes into ALTER EXTENSION ... SET SCHEMA. A create operation takes its schema from declared_schema of "extension_info".

METHODS

diff

my @ops = DBIO::PostgreSQL::Diff::Extension->diff($source, $target);

Compares extension hashrefs. Produces create, update (version changed), or drop operations.

The operations come in the order the extensions depend on one another, which each entry states in requires ("fetch" in DBIO::PostgreSQL::Introspect::Extensions): an extension is created or updated after every extension it requires, and dropped before every one of them. PostgreSQL accepts no other order -- CREATE EXTENSION postgis_topology without postgis fails with required extension "postgis" is not installed, DROP EXTENSION postgis ahead of postgis_topology with cannot drop extension postgis because other objects depend on it. Extensions with no dependency between them, and those of a model that carries none, come by name.

Schema. Only a schema the target declares is compared: a target entry with declared_schema (what "pg_extensions" in DBIO::PostgreSQL was given with name => { schema => ... }). An extension the source has in another schema is moved there by ALTER EXTENSION ... SET SCHEMA if the source says it is relocatable (relocatable). One that is not -- postgis, age -- is refused, here, as the operations are built: refusing to diff: ..., naming the extension, both schemas and the way out, and no statement for anything ("WHAT IS REFUSED" in DBIO::PostgreSQL::Diff). An entry without declared_schema is never moved, wherever the target model, read from the temporary database, has it: the list form of pg_extensions names no place. The move comes after the update of the same extension.

as_sql

Returns the SQL for this operation. The extension name is an identifier by the server's rule ("quote_ident" in DBIO::PostgreSQL::Util) -- uuid-ossp is no statement without its quotes -- and so is a schema, the version a literal ("quote_literal" in DBIO::PostgreSQL::Util). A create writes WITH SCHEMA for an extension whose extension_info has a declared_schema or, without one, an install_schema; one with a control_schema only is written without (the server installs it in that schema). With create_schema in extension_info -- the deploy of a connection that names its namespace cannot see the schema of the extension -- the statement is behind a creation of that schema that looks it up in pg_namespace first ("create_schema_if_missing" in DBIO::PostgreSQL::Util). For an action this class does not know it dies ("throw" in DBIO::PostgreSQL::Diff::NoStatement).

summary

Returns a one-line description:

+extension: pgcrypto (1.3)                  a create: the version, and the schema where one is declared
~extension: postgis (3.3 -> 3.4)            an update
~extension: vector (schema public -> ext)   a move
-extension: citext (1.6, schema public; not declared, DROP EXTENSION takes the objects it owns)

A drop is an installed extension the schema does not declare (ADR 0066, decision 4): only an unrestricted deploy drops one ("diff" in DBIO::PostgreSQL::Deploy), and a restricted deploy keeps it and does not name it. The summary says what DROP EXTENSION does -- it takes the objects the extension owns -- and nothing more: what an extension made at runtime (the graph schemas of AGE, the topology schemas of PostGIS Topology) is no member of it, see "postgis_topology" in DBIO::PostgreSQL::Extension; where the diff has those objects in its model they are operations of their own, next to this one.

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.