NAME

DBIO::PostgreSQL::Diff::ForeignKey - Diff operations for PostgreSQL foreign keys

VERSION

version 0.900007

DESCRIPTION

Represents a foreign key diff operation: ALTER TABLE ... ADD CONSTRAINT ... FOREIGN KEY, DROP CONSTRAINT, and with the option "not_valid" the VALIDATE CONSTRAINT that follows an ADD ... NOT VALID.

The install writes a foreign key for a belongs_to of a class with pg_fk_constraints_from_rels, with the ON DELETE and ON UPDATE it declares (DBIO::PostgreSQL::DDL). The target model of a deploy is read from a database that install built, so it holds that constraint under the name the install gave it (<table>_<column>_fkey), and the diff takes the name from there: install and diff write one constraint.

DEFERRABLE

The model keys deferrable and initially_deferred are read from pg_constraint.condeferrable and condeferred, written by the install for the attributes of the same names of a belongs_to, written by this class (DEFERRABLE INITIALLY IMMEDIATE, DEFERRABLE INITIALLY DEFERRED, nothing for a key that is not deferrable) and compared: a key that changes either is dropped and created again. A model that has only the older is_deferrable is read as deferrable.

ATTRIBUTES

table_key

The schema.table key of the table that holds the key. It is where the model files the table, and what "summary" prints; it is not SQL.

schema_name

The schema of that table.

table_name

The name of that table. "as_sql" writes the table from schema_name and table_name, each quoted for itself; the key cannot be taken apart again.

constraint_name

The name of the constraint.

fk_info

The entry of DBIO::PostgreSQL::Introspect::ForeignKeys: local_columns, remote_schema, remote_table, remote_columns, on_delete, on_update, match, on_delete_columns, deferrable, initially_deferred, is_valid.

replaced

True for the drop that is the first half of a drop and create of a key whose definition changed. It stays ahead of its create; any other drop is a removal and runs with the others, at the end of the diff.

not_valid

True for a create that is written NOT VALID. See "with_validation".

ahead_of_table

True for the drop of a key between tables that are dropped in the same diff and point at each other in a circle: no order of the DROP TABLEs takes them.

existing_table

True for a create on a table the database has. The key of a table the diff creates is created on an empty table.

METHODS

diff

my @ops = DBIO::PostgreSQL::Diff::ForeignKey->diff(
    $source_fks, $target_fks, $source_tables, $target_tables,
);

$source_fks and $target_fks are the foreign_keys sections of the two models, $source_tables and $target_tables their tables sections.

Keys are matched by constraint name. A key both have is compared in the form the introspection gives it: its columns, the table and schema it references, on_delete and on_update (the server's default NO ACTION and no word at all are one), match (SIMPLE, the default, or FULL) and on_delete_columns (the list of ON DELETE SET NULL (columns)). A key that differs is dropped and created again, the drop marked "replaced". deferrable and initially_deferred are compared too ("DEFERRABLE").

A key both have that is the same key but NOT VALID in the database (is_valid false: pg_constraint.convalidated) while the target's is valid (a model without the field holds a valid key) gets one ALTER TABLE ... VALIDATE CONSTRAINT, no drop and no create. If the rows break it the upgrade ends at that statement, naming the key; the statement runs in a transaction of its own ("with_validation"). The option "with_validation" adds nothing to it. A key that is not valid in the target too, or valid in the database, is no change.

The install cannot declare MATCH FULL or a column list: belongs_to has no attribute for them. A key made so by pg_extra_ddl is read back from the database the install built and "as_sql" writes both in the create.

A key only the target has is created, also on a table the diff creates. A key only the database has is dropped: the target is what the schema declares, and a key it does not declare is not kept. The summary says so ("summary"). The key of a table that is dropped goes with the table and gets no statement, nor does a key whose table the target lacks, with one exception: a key between two tables that are both dropped and lie in a circle of such keys is dropped ahead of them (ahead_of_table), since the server does not drop a table while a key of another table points at it, and tables that point at each other have no order ("dropped_together"). A key of a table that stays into a table that is dropped is dropped.

The caller does not call this for a target model without a foreign_keys section (DBIO::PostgreSQL::Diff): a model built by hand that says nothing of foreign keys declares none.

dropped_together

my @keys = DBIO::PostgreSQL::Diff::ForeignKey->dropped_together(
    $source_fks, $source_tables, $target_tables);

The keys of the database that run between two tables the diff drops (the table is in $source_tables and not in $target_tables), not a table to itself. Each is a hashref with holder and referenced (table keys), info (the entry of the section) and cyclic, true where the referenced table can reach the holder again by such keys. The server does not drop a table while a key of another table points at it, so DBIO::PostgreSQL::Diff::Table drops the holder ahead of the table it references; a key in a circle has no such order and is dropped by this class ahead of the tables (ahead_of_table).

split_outside

my ($source, $target, @kept) = DBIO::PostgreSQL::Diff::ForeignKey->split_outside(
    $source_fks, $target_fks, $source_tables, $target_tables,
);

A key the database has whose referenced table is in neither model is not the deploy's: the table is outside it (another schema, one pg_schemas does not name), and the install of the target, built in a database that lacks that table, cannot declare the key. Returns both sections without such keys (the target's key of the same name is not compared with it), and for each one an operation with the action kept. It is no change: it has no statement and does not belong in operations, the diff lists it in its summary (=fk: NAME (on TABLE -> REFERENCED) -- kept (target outside the deploy)) so that it is seen. A table that only one model has is inside the deploy (it is created or dropped), so a key into it is compared and dropped as any other.

A key whose name the target declares too, on the same table but onto another table, is not kept: the target redefines it, and the diff drops the database's and creates the target's (a replacement, not a key left standing).

with_validation

my @ops = DBIO::PostgreSQL::Diff::ForeignKey->with_validation(@ops);

The option foreign_keys_not_valid of DBIO::PostgreSQL::Diff and DBIO::PostgreSQL::Deploy. Marks every create on a table the database has "not_valid", so that ADD CONSTRAINT does not read the rows that are there, and returns the operations with one VALIDATE CONSTRAINT added for each, behind all of them. Without the option the key is an ordinary ADD CONSTRAINT.

apply runs the statements of a diff in one transaction, except each VALIDATE CONSTRAINT: the storage reports it as not transactional ("_ddl_statement_is_transactional" in DBIO::PostgreSQL::Storage), so it runs after the COMMIT of the ADD CONSTRAINT in a transaction of its own. The lock of the add is released before the rows are read, and rows that break the key end apply with the error while the key stays NOT VALID. The key is not left NOT VALID for good: the next diff reads convalidated and adds the VALIDATE CONSTRAINT again, which fails on rows that break the key until they are cleaned up.

as_sql

The ALTER TABLE statement. The wording of ADD CONSTRAINT is the install's: FOREIGN KEY (columns) REFERENCES table (columns), then MATCH FULL when the key is, then ON DELETE and ON UPDATE unless the action is NO ACTION, which is what no clause means; ON DELETE SET NULL and SET DEFAULT carry their column list (PostgreSQL 15) when the key has one; a deferrable key then says DEFERRABLE INITIALLY IMMEDIATE or DEFERRABLE INITIALLY DEFERRED. NOT VALID closes it when "not_valid" is set. Constraint, tables and columns are identifiers by the server's rule ("quote_ident" in DBIO::PostgreSQL::Util).

For an action this class does not know it dies ("throw" in DBIO::PostgreSQL::Diff::NoStatement).

summary

+fk: NAME (on TABLE -> REFERENCED) for a key to create, NOT VALID behind it when it is written so; ~fk: NAME (on TABLE) validate for the VALIDATE CONSTRAINT.

A key that is dropped says why. One the schema does not declare, which the diff drops because the target does not have it, is marked -- not declared by the schema, dropped, so that it does not pass unseen; the drop of a key that is created again is marked as that.

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.