NAME
DBIO::PostgreSQL::Diff::Table - Diff operations for PostgreSQL tables
VERSION
version 0.900007
DESCRIPTION
Represents a table-level diff operation: CREATE TABLE ... (with full column definitions for new tables), DROP TABLE, or ALTER TABLE ... SET LOGGED / SET UNLOGGED for a table that is kept differently. Instances are produced by "diff" and consumed by DBIO::PostgreSQL::Diff.
Diff::Column handles column ADDs for existing tables only; new tables get their full column list inlined in the CREATE TABLE statement produced here.
The tables section of the model holds every kind of relation, told apart by kind (DBIO::PostgreSQL::Introspect::Tables). This class creates ordinary tables only (r, and what a model built by hand gives no kind). Views and materialized views are DBIO::PostgreSQL::Diff::View's. A foreign table, a partitioned table, a partition and a table that inherits can be dropped here but not created: see "diff".
ATTRIBUTES
schema_name
PostgreSQL schema containing the table.
table_name
The table name.
table_info
Hashref of table metadata from introspection (kind, rls_enabled, etc.).
columns
ArrayRef of column hashrefs for new tables (populated when action is create), so that as_sql can emit a complete CREATE TABLE with all column definitions rather than an empty shell.
METHODS
diff
my @ops = DBIO::PostgreSQL::Diff::Table->diff(
$source, $target, $source_cols, $target_cols, $source_foreign_keys,
$target_foreign_keys, $source_outside_dependents);
Compares two table hashrefs (keyed by schema.table) and returns operations for tables present only in target (create) or only in source (drop). For new tables, passes column metadata so as_sql can emit a complete CREATE TABLE with full column definitions (types, nullability, defaults, identity). Diff::Column only handles ALTER for existing tables.
Views and materialized views are passed over; DBIO::PostgreSQL::Diff::View creates and drops them.
A table is dropped with DROP TABLE and a foreign table with DROP FOREIGN TABLE, neither with CASCADE: what the model holds on the table (its indexes, triggers, policies, its own constraints and the sequences its columns own) goes with it, the foreign keys that point at it from kept tables and the views that read it are dropped by the diff ahead of it ("ORDER OF OPERATIONS" in DBIO::PostgreSQL::Diff), and a table that inherits from it, or whose foreign key points at it, is dropped first (the keys of tables that point at each other, in a circle, are dropped ahead of them: "dropped_together" in DBIO::PostgreSQL::Diff::ForeignKey). A partition that goes together with the partitioned table it belongs to gets no statement: the DROP TABLE of that table takes its partitions, and one for a partition after it would name a table that is gone.
What stands on the table and is not in the model -- the view or materialized view of a schema outside pg_schemas that reads it, a foreign key of a table outside them, a partition or inheriting table there -- is read into the outside_dependents section (the seventh argument, the section of the source model) and refused: the diff dies with refusing to diff: ..., naming each such object, and no statement is written (DBIO::PostgreSQL::Diff::Dependents). A dependent nobody could name, such as a policy of another table that reads this one, stops the DROP TABLE itself; the transaction apply runs in leaves the database as it was.
An ordinary table is created UNLOGGED where the target has it so (persistence u), and one both sides have that is logged on the one and unlogged on the other gets an operation of the action set_persistence: ALTER TABLE ... SET UNLOGGED or SET LOGGED. PostgreSQL takes that for an ordinary table and for a partition. A target entry that has no persistence -- a model built by hand -- asks for nothing. The statements come in the order of the foreign keys the database has (the fifth argument, the foreign_keys section of the source model): going to UNLOGGED the table that holds a key before the table it references, going to LOGGED the referenced one first -- PostgreSQL refuses the statement in the other order. Tables not tied by a key stay in the order of their names. Two tables that reference each other and change together have no order the server takes, and the diff is refused with a statement-less message naming them and the way out (drop one key, diff again, add it back).
These are refused, with refusing to diff: ... and no statement:
a table to create whose name differs only in upper and lower case from one to drop in the same schema --
UserAccountin the target,useraccountin the database (DBIO::PostgreSQL::Diff::CaseOnly). The two are most likely one table, andDROP TABLEtakes its rows. The message names both, for every such table at once, and the way out:ALTER TABLE public.useraccount RENAME TO "UserAccount". The same holds for a foreign table, a partitioned table and a materialized view (ALTER FOREIGN TABLE,ALTER MATERIALIZED VIEW), each among its own kind; this is asked ahead of everything else, so such a table is not answered with "cannot create it". A view is not asked about: it holds nothing, and DBIO::PostgreSQL::Diff::View drops and creates it.a relation that is of one kind in the source and of another in the target -- a table where the target has a view of that name, a view where it has a materialized view. Making one into the other means dropping it, and with a table its rows.
a foreign table or a partitioned table that only the target has. The model holds the columns of such a table, but not the server and options of the one or the partitioning of the other;
CREATE TABLEwith those columns makes an ordinary table of that name.a partition that only the target has, for the same reason: the model does not hold its bounds.
a table that only the target has and that inherits from others (
inherits). The diff has no statement for it;CREATE TABLEwith its columns makes an ordinary table that has the inherited columns as its own. Writing it right takes more thanINHERITS (...): a default or aNOT NULLthe table has of its own on an inherited column can only be given in the statement by defining the column again, and a column defined again stays behind when the table above drops it.a table that is a partition, or inherits, on the one side and not on the other, or of another table. Attaching a partition needs its bounds, and a table that is made to inherit needs the columns first. A model that has neither
partition_ofnorinheritsfor the table says nothing, and is not asked.a relation that is logged on the one side and unlogged on the other and is no ordinary table -- PostgreSQL 18 has no unlogged partitioned table and no unlogged materialized view, and no statement that makes one -- and a table to create that is temporary, which no model read from the catalog has.
These refusals about partitions and inheritance stay as they are until a result class can declare them: no key of DBIO::PostgreSQL::Result names a partitioned table, its bounds or the tables a table inherits from, so the diff has nothing to build such a table from.
qualified_name
my $fqn = $op->qualified_name; # 'auth.users'
Returns the schema-qualified table name as a reader sees it: the two names joined with a dot, unquoted. It is what "summary" prints and is not SQL -- "as_sql" quotes each name for itself ("quote_qualified" in DBIO::PostgreSQL::Util).
as_sql
Returns the SQL for this operation. For create, emits a complete CREATE TABLE with all column definitions inline (type, nullability, default, identity, generation). A default that calls a sequence is written as the catalog has it; the sequence is created ahead of the table and given to its column behind it (DBIO::PostgreSQL::Diff::Sequence, DBIO::PostgreSQL::Diff::SequenceOwner). Diff::Column handles column ADDs for existing tables, CREATE UNLOGGED TABLE for an unlogged one. For set_persistence, ALTER TABLE ... SET LOGGED or SET UNLOGGED, as the persistence of its table_info says. For drop, DROP TABLE ..., or DROP FOREIGN TABLE ... for a foreign table, each without CASCADE.
Schema, table and column names are written as identifiers by the server's rule ("quote_ident" in DBIO::PostgreSQL::Util), so a Mixed-Case or reserved name reaches the object it names. Column types and defaults come from the catalog (format_type, pg_get_expr) and are written as given.
A generated column is written GENERATED ALWAYS AS (expr) STORED or, for a virtual one (PostgreSQL 18), ... VIRTUAL ("generated_kind" in DBIO::PostgreSQL::Introspect). The catalog keeps its expression where it keeps a default, so the model has it in default_value; it is not a default and is not written as one.
For an action this class does not know it dies ("throw" in DBIO::PostgreSQL::Diff::NoStatement), and for a set_persistence whose table_info names neither of the two.
summary
Returns a one-line description such as +table: auth.users, or ~table: auth.sessions (unlogged) for a table that is kept differently.
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.