Foreign keys keep references honest

Tue, 25 May 2027 00:00:00 +0000

A foreign key makes a relationship enforceable during ordinary database writes. A task can reference an existing project, and the database can reject an unknown project identifier even when an import or a new application code path forgets to check it. The constraint defines referential integrity; it does not decide whether the selected project is the correct one for the business operation.

State the relationship precisely

A referencing key points to eligible unique columns in the parent table, commonly its primary key. Several child rows may reference the same parent, so a foreign key alone describes neither one-to-one cardinality nor a requirement that every parent have children. Add the separate uniqueness or other rules that the actual relationship requires instead of inferring them from the reference.

Nullability is an independent decision. A single-column foreign key normally permits SQL NULL, representing no reference. Add NOT NULL when every child must have a parent. For composite keys, PostgreSQL’s default MATCH SIMPLE allows a row to avoid matching when any referencing component is null; MATCH FULL instead requires all components to be null or all to match. A partially filled composite reference is therefore not automatically invalid under the default.

Scope belongs in the key too. If identifiers are only unique within a tenant, reference a suitable tenant-and-identifier key rather than assuming a matching identifier in another tenant is acceptable. Even a correctly scoped foreign key is not an authorization check: an existing project can still be the wrong project for the current user or workflow.

Parent deletion needs a policy

NO ACTION is PostgreSQL’s default delete action. With the normal immediate checking mode, deleting a referenced parent fails unless the resulting statement satisfies the constraint. A deferrable NO ACTION constraint can postpone the check; RESTRICT does not permit that deferral of the delete restriction. The two names should not be treated as unconditional synonyms.

CASCADE removes referencing child rows when the parent is deleted. It fits a component that has no independent lifecycle, but its reach can extend through several relationships. SET NULL retains the child while clearing its reference, which requires compatible nullability and other constraints. SET DEFAULT also must leave a valid reference; choosing a default does not waive referential integrity.

ON UPDATE separately describes what happens when referenced key values change. An update cascade copies the new key into referencing rows; it is not a request to overwrite unrelated child attributes. Choose actions according to ownership and retention requirements. Replacing a restrictive rule with cascade merely to silence an error can turn a useful integrity failure into unintended data deletion.

When it breaks

An application-side existence query can race with another transaction deleting the parent. The database constraint coordinates the actual write, so keep it as the authoritative relationship check rather than relying only on the earlier read. Privileged operations that disable enforcement, or migrations that have not validated old rows, are separate states and cannot be assumed to satisfy a fully enforced, validated constraint.

The write cost is also workload-dependent. Parent deletion can require finding many children, taking locks, and executing cascades. PostgreSQL indexes the eligible referenced key but does not automatically create an index on the child reference columns. Review those access paths and the size of the deletion graph. A declared relationship does not guarantee join elimination or make every join inexpensive.

Check it quickly

Save this as foreign-key-actions.sql and run psql -X -v ON_ERROR_STOP=1 -f foreign-key-actions.sql in a disposable PostgreSQL 18 database. The fixture uses temporary tables for tasks, project-owned files, and retained history, with different delete actions. Rollback removes all test objects and changes.

\set ON_ERROR_STOP on
BEGIN;
CREATE TEMP TABLE projects (id integer PRIMARY KEY);
CREATE TEMP TABLE tasks (id integer PRIMARY KEY,project_id integer REFERENCES projects ON DELETE NO ACTION);
CREATE TEMP TABLE files (id integer PRIMARY KEY,project_id integer REFERENCES projects ON DELETE CASCADE);
CREATE TEMP TABLE audit_history (id integer PRIMARY KEY,project_id integer REFERENCES projects ON DELETE SET NULL);
INSERT INTO projects VALUES (1),(2);
INSERT INTO tasks VALUES (10,1),(11,NULL);
INSERT INTO files VALUES (20,1);
INSERT INTO audit_history VALUES (30,1);
DO $$ BEGIN
 INSERT INTO tasks VALUES (12,999);
 RAISE EXCEPTION 'dangling reference accepted';
EXCEPTION WHEN foreign_key_violation THEN RAISE NOTICE 'missing project rejected';
END $$;
DO $$ BEGIN
 DELETE FROM projects WHERE id=1;
 RAISE EXCEPTION 'referenced project deleted';
EXCEPTION WHEN foreign_key_violation THEN RAISE NOTICE 'NO ACTION blocked parent deletion';
END $$;
DO $$ BEGIN
 IF (SELECT count(*) FROM files) <> 1 OR
 (SELECT project_id FROM audit_history WHERE id=30) IS DISTINCT FROM 1 THEN
 RAISE EXCEPTION 'failed deletion left partial side effects';
 END IF;
END $$;
DELETE FROM tasks WHERE id=10;
DELETE FROM projects WHERE id=1;
SELECT * FROM tasks;
SELECT * FROM audit_history;
SELECT count(*) AS remaining_files FROM files;
DO $$ BEGIN
 IF (SELECT array_agg(id ORDER BY id) FROM projects) IS DISTINCT FROM ARRAY[2] THEN
 RAISE EXCEPTION 'wrong surviving project';
 END IF;
 IF (SELECT count(*) FROM files) <> 0 OR
 (SELECT count(*) FROM audit_history WHERE id=30 AND project_id IS NULL) <> 1 OR
 (SELECT count(*) FROM tasks WHERE id=11 AND project_id IS NULL) <> 1 THEN
 RAISE EXCEPTION 'wrong delete action or null handling';
 END IF;
END $$;
ROLLBACK;

PostgreSQL 18.6 rejected the task pointing to project 999, while accepting task 11 with a null reference. The first deletion of project one failed because task 10 still referenced it. That failed statement did not partially remove the other dependent data.

After explicitly removing task 10, the parent deletion succeeded. Its file disappeared through CASCADE, history row 30 remained with a null project, and the unrelated null-reference task remained. Project two survived without any children. Assertions verify these distinct outcomes, showing that “references stay valid” and “children must be deleted” are different contracts. Use the same lifecycle examples when reviewing schema changes with application owners.

Sources