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

# add_column

> Add a column to an existing table.

Adds one column to a table. Existing rows get `NULL`, or the column's default if it has one.

| | |
| - | - |
| Scope | `mcp:write` |
| Annotations | `readOnlyHint: false` |
| Activity event | `column.added` |

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

<ParamField body="column" type="object" required>
  The column to add.

  <Expandable title="properties">
    <ParamField body="name" type="string" required>
      Column name. See [Naming rules](/reference/naming-rules). `id` and `created_at` are reserved.
    </ParamField>

    <ParamField body="type" type="string" required>
      One of `text`, `integer`, `numeric`, `boolean`, `timestamptz`, `uuid`, `jsonb`.
    </ParamField>

    <ParamField body="nullable" type="boolean" default="true">
      `false` makes the column `NOT NULL`. A `NOT NULL` column without a default can only be added to an empty table.
    </ParamField>

    <ParamField body="default" type="string">
      `now()` for `timestamptz`, or `gen_random_uuid()` for `uuid`.
    </ParamField>
  </Expandable>
</ParamField>

## Result

The table's updated definition. Same shape as the [`describe_table`](/mcp/tools/describe-table) result.

## Example

```json Arguments theme={null}
{
  "projectId": "01k7m3x9q2v8d4h6n1r5t0w2yz",
  "table": "books",
  "column": { "name": "finished_on", "type": "timestamptz" }
}
```

```json Result theme={null}
{
  "data": {
    "table": "books",
    "columns": [
      { "name": "id", "type": "uuid", "nullable": false, "default": "gen_random_uuid()" },
      { "name": "created_at", "type": "timestamptz", "nullable": false, "default": "now()" },
      { "name": "title", "type": "text", "nullable": false },
      { "name": "rating", "type": "integer" },
      { "name": "finished_on", "type": "timestamptz" }
    ]
  }
}
```

## Errors

| Code | When |
| - | - |
| `ACCESS_DENIED` | You don't have write access, or the connection is read-only |
| `VALIDATION` | Unknown table, invalid name, unsupported type or default, or a `NOT NULL` column without a default on a table that has rows |
| `CONFLICT` | The column already exists |
| `QUOTA_EXCEEDED` | The table already has 50 columns, or the project's storage is full |

## Notes

* To add a foreign key, the column must be created with the table. See [Foreign keys](/reference/foreign-keys).
* To make an existing nullable column required, add a new `NOT NULL` column with a default, or create a new table and copy the rows.


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