Foreign keys

A foreign key makes a uuid column point at a row in another table. Postgres then guarantees that every non-null value in the column matches the id of an existing row.

Rules

The column must have type uuid.
It always references the other table’s id column.
The referenced table must exist in the same project before you create the referencing table. A table can also reference itself, for example parent_id on a categories table.
Each column can have at most one foreign key. A table can have several foreign keys on different columns.
Foreign keys are defined when the table is created, with create_table or the web app’s New table dialog. They can’t be added to an existing table.
A NULL value is always allowed in a nullable foreign key column. Set nullable: false to require a reference.

Delete rules

onDelete decides what happens to referencing rows when a referenced row is deleted:

Rule	Effect	Use when
`restrict` (default)	The delete is refused while referencing rows exist	Referencing rows must be handled deliberately
`cascade`	Referencing rows are deleted too	Child rows have no meaning without the parent, such as order lines
`set null`	The referencing column is set to `NULL`	The link is optional, such as a book’s author

Use set null only on nullable columns. On a NOT NULL column, deleting a referenced row fails. The web app’s New table dialog always uses restrict. Ask Claude, or use create_table directly, for cascade or set null.

Example

Create companies, then contacts with a foreign key that deletes contacts along with their company:

create_table arguments

{
  "projectId": "01k7m3x9q2v8d4h6n1r5t0w2yz",
  "table": "contacts",
  "columns": [
    { "name": "full_name", "type": "text", "nullable": false },
    { "name": "company_id", "type": "uuid" }
  ],
  "foreignKeys": [
    { "column": "company_id", "refTable": "companies", "onDelete": "cascade" }
  ]
}

To insert a contact, use a company’s id:

insert_rows arguments

{
  "projectId": "01k7m3x9q2v8d4h6n1r5t0w2yz",
  "table": "contacts",
  "rows": [{ "full_name": "Ada Lovelace", "company_id": "c3f1e8a2-7b4d-4e19-a0c6-5d2b9f8e1a37" }]
}

An id that doesn’t exist in companies fails with:

Referenced row does not exist, or the row is still referenced by another table

Dropping linked tables and columns

Dropping a column also removes its foreign key.
A table can’t be dropped while another table references it. Drop the referencing column or table first.

Viewing relationships

The project’s Schema tab draws a line between each foreign key column and the table it references. list_tables and describe_table return foreign keys in foreignKeys.

Data model

Rules

Trust

Help

Rules

Delete rules

Example

Dropping linked tables and columns

Viewing relationships

​Rules

​Delete rules

​Example

​Dropping linked tables and columns

​Viewing relationships

Rules

Delete rules

Example

Dropping linked tables and columns

Viewing relationships