> ## Documentation Index
> Fetch the complete documentation index at: https://docs.auxilian.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Foreign keys

> Link tables with uuid foreign keys and control what happens when referenced rows are deleted.

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`](/mcp/tools/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 |

<Note>
  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`.
</Note>

## Example

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

```json create_table arguments theme={null}
{
  "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`:

```json insert_rows arguments theme={null}
{
  "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:

```text theme={null}
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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.