Foreign Key

Defines a foreign key on a table

Properties

Property	Type	Required	Description
name	string	—	The foreign key name.
sql	string	—	User-provided raw SQL snippet.
columns	array of string	—	The columns in the table that the foreign key enforces the value of. Minimum items: 1.
references	object	—	Defines the information about the foreign key table and columns.
match_type	FULL | PARTIAL | SIMPLE	—	A value inserted into the referencing column(s) is matched against the values of the referenced table and referenced columns using the given match type. There are three match types: FULL, PARTIAL, and SIMPLE (which is the default). FULL will not allow one column of a multicolumn foreign key to be null unless all foreign key columns are null; if they are all null, the row is not required to have a match in the referenced table. SIMPLE allows any of the foreign key columns to be null; if any of them are null, the row is not required to have a match in the referenced table. PARTIAL is not yet implemented.
on_delete	NO ACTION | RESTRICT | CASCADE | SET NULL | SET DEFAULT	—	Action to take on delete of the column value in the referenced table.
on_update	NO ACTION | RESTRICT | CASCADE | SET NULL | SET DEFAULT	—	Action to take on update of the column value in the referenced table.
deferrable	boolean	—	This controls whether the constraint can be deferred. A constraint that is not deferrable will be checked immediately after every command.
initially_deferred	boolean	—	Initial Constraint Check Behavior.
period	string	—	The range column named after PERIOD in a temporal foreign key (PostgreSQL 18+), on the referencing side. Both sides must name one.
enforced	boolean	—	false renders NOT ENFORCED (PostgreSQL 18+), which stops the constraint being checked. PostgreSQL records a not-enforced constraint as not validated as well. Absent means enforced, the default.
not_valid	boolean	—	true renders NOT VALID: rows already in the table were never checked, only new ones are. The state holds only when the constraint is added with ALTER TABLE, so the build writes it that way. Absent means valid, the default.

references

Defines the information about the foreign key table and columns

Property	Type	Required	Description
name	string	yes	The name of the foreign key table.
columns	array of string	yes	The columns in the table in the foreign key table. Minimum items: 1.
period	string	—	The range column named after PERIOD in a temporal foreign key (PostgreSQL 18+), on the referenced side.

Mutually exclusive forms

Exactly one of these must hold:

• sql, without columns or references or on_delete or on_update or deferrable or initially_deferred
• columns, without sql

No other properties are accepted.

---

Source: schemata/foreign_key.yml · Resolved JSON Schema: foreign_key.json