> ## 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.

# create_table

> Create a table with typed columns and optional foreign keys.

Creates a table in a project. Auxilian adds `id` (`uuid` primary key) and `created_at` (`timestamptz`, defaults to the insert time) automatically. Don't include them in `columns`.

| | |
| - | - |
| Scope | `mcp:write` |
| Annotations | `readOnlyHint: false` |
| Activity event | `table.created` |

## Parameters

<ParamField body="projectId" type="string" required>
  Project id from `list_projects`. You need write access.
</ParamField>

<ParamField body="table" type="string" required>
  Table name. Lowercase letters, digits, and underscores, starting with a letter or underscore, at most 63 characters, and not starting with `proj_`. See [Naming rules](/reference/naming-rules).
</ParamField>

<ParamField body="columns" type="object[]" required>
  One to 50 columns.

  <Expandable title="column">
    <ParamField body="name" type="string" required>
      Column name. Same rules as table names. `id` and `created_at` are reserved.
    </ParamField>

    <ParamField body="type" type="string" required>
      One of `text`, `integer`, `numeric`, `boolean`, `timestamptz`, `uuid`, `jsonb`. See [Data types](/reference/data-types).
    </ParamField>

    <ParamField body="nullable" type="boolean" default="true">
      `false` makes the column `NOT NULL`.
    </ParamField>

    <ParamField body="default" type="string">
      `now()` for a `timestamptz` column, or `gen_random_uuid()` for a `uuid` column. No other defaults are supported.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="foreignKeys" type="object[]">
  Foreign keys from `uuid` columns in this table to the `id` of another table. See [Foreign keys](/reference/foreign-keys).

  <Expandable title="foreign key">
    <ParamField body="column" type="string" required>
      A `uuid` column listed in `columns`. Each column can have at most one foreign key.
    </ParamField>

    <ParamField body="refTable" type="string" required>
      The referenced table. It must already exist in the project, or be this table (a self-reference).
    </ParamField>

    <ParamField body="onDelete" type="string" default="restrict">
      What happens to rows here when the referenced row is deleted: `restrict` blocks the delete, `cascade` deletes these rows too, and `set null` clears the column.
    </ParamField>
  </Expandable>
</ParamField>

## Result

The new table's definition, including the system columns. Same shape as the [`describe_table`](/mcp/tools/describe-table) result.

## Example

```json Arguments theme={null}
{
  "projectId": "01k7m3x9q2v8d4h6n1r5t0w2yz",
  "table": "contacts",
  "columns": [
    { "name": "full_name", "type": "text", "nullable": false },
    { "name": "email", "type": "text" },
    { "name": "company_id", "type": "uuid" },
    { "name": "last_contacted_at", "type": "timestamptz" },
    { "name": "profile", "type": "jsonb" }
  ],
  "foreignKeys": [
    { "column": "company_id", "refTable": "companies", "onDelete": "cascade" }
  ]
}
```

```json Result theme={null}
{
  "data": {
    "table": "contacts",
    "columns": [
      { "name": "id", "type": "uuid", "nullable": false, "default": "gen_random_uuid()" },
      { "name": "created_at", "type": "timestamptz", "nullable": false, "default": "now()" },
      { "name": "full_name", "type": "text", "nullable": false },
      { "name": "email", "type": "text" },
      { "name": "company_id", "type": "uuid" },
      { "name": "last_contacted_at", "type": "timestamptz" },
      { "name": "profile", "type": "jsonb" }
    ],
    "foreignKeys": [
      { "column": "company_id", "refTable": "companies", "refColumn": "id", "onDelete": "cascade" }
    ]
  }
}
```

## Errors

| Code | When |
| - | - |
| `ACCESS_DENIED` | You don't have write access, or the connection is read-only |
| `VALIDATION` | Invalid name, unsupported type or default, duplicate column, no columns, more than 50 columns, a foreign key on a non-`uuid` column, or a foreign key to a table that doesn't exist |
| `CONFLICT` | A table with that name already exists in the project |
| `QUOTA_EXCEEDED` | The project already has 25 tables, or its storage is full |

## Notes

* Columns can't have unique constraints, check constraints, or indexes beyond the `id` primary key.
* Foreign keys can only be added here, when the table is created. `add_column` can't add one later.


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