# Table Management

> Create, rename, duplicate and delete NocoDB tables, set the display field and description, including creating a table with its initial fields over MCP or REST (Meta API v3). Use when a NocoDB schema needs a new or changed table. Adding or changing columns is field-management.

- Skill: `agents-store/table-management-3` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add agents-store/table-management-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/agents-store/table-management-3/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: agents-store (https://skillmd.com/u/agents-store)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/agents-store/table-management-3

---


# Table Management

Table writes go through the MCP schema tools on **Cloud / licensed** self-hosted (`listTools` category `tables`, then `callTool`) and through the **REST API** (`curl` on Meta API v3) on **Community Edition** or as a fallback. See **mcp-patterns** for the contract and **api-reference** for the REST surface.

## Discover First

Before creating or changing a table, snapshot the base:

```
mcp__plugin_nocodb-dev_nocodb__getBaseInfo                        ← confirm working base
mcp__plugin_nocodb-dev_nocodb__getBaseSchema                      ← every table with its fields and views, one call
mcp__plugin_nocodb-dev_nocodb__getTablesList                      ← or just titles & IDs
```

Avoid name collisions and unintended duplicates. NocoDB does not enforce title uniqueness within a base — duplicates are accepted but cause downstream confusion.

## Create a Table

### MCP (Cloud / licensed)

```
mcp__plugin_nocodb-dev_nocodb__listTools  category: "tables"      ← once per session: confirms createTable is offered
mcp__plugin_nocodb-dev_nocodb__callTool   name: "createTable"
  arguments: { title: "Customers", description: "Master customer list",
               fields: [ { title: "Name",  type: "SingleLineText" },
                         { title: "Email", type: "Email" } ] }
```

### REST

```bash
curl -sS -X POST \
  -H "xc-token: ${NOCODB_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Customers" }' \
  "${NOCODB_URL}/api/v3/meta/bases/${BASE_ID}/tables"
```

With initial fields (preferred — saves a roundtrip per field; type-specific settings go inside `options`):

```bash
curl -sS -X POST \
  -H "xc-token: ${NOCODB_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Customers",
    "description": "Master customer list",
    "fields": [
      { "title": "Name",   "type": "SingleLineText" },
      { "title": "Email",  "type": "Email" },
      { "title": "Phone",  "type": "PhoneNumber" },
      { "title": "Status", "type": "SingleSelect",
        "options": { "choices": [
          { "title": "New" }, { "title": "Active" }, { "title": "Archived" }
        ]}},
      { "title": "Joined", "type": "Date" }
    ]
  }' \
  "${NOCODB_URL}/api/v3/meta/bases/${BASE_ID}/tables"
```

The response includes the new `tableId` (prefix `m`). For a source other than the default, add `source_id`.

### Verify

```
mcp__plugin_nocodb-dev_nocodb__getTableSchema  tableId: <newTableId>
```

The response should list every field you created, with auto-assigned field IDs and the first non-system field as the display field.

## Rename a Table

```bash
curl -sS -X PATCH \
  -H "xc-token: ${NOCODB_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"title":"NewName"}' \
  "${NOCODB_URL}/api/v3/meta/bases/${BASE_ID}/tables/${TABLE_ID}"
```

MCP: `callTool name: "updateTable"  arguments: { tableId: "<tableId>", title: "NewName" }`.

Renaming a table does **not** rename references in formulas, lookups, or rollups — but those references use IDs internally so they keep working. Visible names in formulas stay as the original; refresh formulas explicitly if you want them to reflect the new name.

## Update Description

```bash
curl -sS -X PATCH \
  -H "xc-token: ${NOCODB_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"description":"New description"}' \
  "${NOCODB_URL}/api/v3/meta/bases/${BASE_ID}/tables/${TABLE_ID}"
```

## Set the Display Field

The display field is what shows up in linked-record dropdowns and lookup card titles. By default, NocoDB picks the first non-system column — usually a SingleLineText named "Title" or similar. Override:

```bash
curl -sS -X PATCH \
  -H "xc-token: ${NOCODB_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"display_field_id":"<fieldId>"}' \
  "${NOCODB_URL}/api/v3/meta/bases/${BASE_ID}/tables/${TABLE_ID}"
```

MCP: `callTool name: "setDisplayField"  arguments: { fieldId: "<fieldId>" }` (category `fields`), or `updateTable` with `display_field_id`.

Allowed display field types: text, number, date/time, duration, autonumber and formula fields. `LongText`, select, link and attachment fields are rejected.

## Duplicate a Table

There is no single duplicate call in the REST API (on Cloud / licensed the MCP `duplicates` category may offer one — check `listTools`). To clone by hand:

1. Read the source schema:

```
mcp__plugin_nocodb-dev_nocodb__getTableSchema  tableId: <sourceTableId>
```

2. Strip IDs from the response and POST as a new table:

```bash
curl -sS -X POST \
  -H "xc-token: ${NOCODB_TOKEN}" \
  -H "Content-Type: application/json" \
  -d @duplicated-table.json \
  "${NOCODB_URL}/api/v3/meta/bases/${BASE_ID}/tables"
```

Note: this clones the schema only. To copy data, see the `import-export` skill in `nocodb-ops`.

## Delete a Table

**Destructive — confirm with the user first.** Print the table title, base, record count, and any dependent fields (Lookups / Rollups / Links from other tables) before asking for approval.

```bash
curl -sS -X DELETE \
  -H "xc-token: ${NOCODB_TOKEN}" \
  "${NOCODB_URL}/api/v3/meta/bases/${BASE_ID}/tables/${TABLE_ID}"
```

MCP: `callTool name: "deleteTable"  arguments: { tableId: "<tableId>" }`.

On Cloud / licensed the deleted table goes to the base trash: `listTrash` (read-only, lists `cleanup_due_at`) and `restoreFromTrash(trashId)` bring it back until the retention window ends. An external source deletes for good.

Pre-delete audit:

```
mcp__plugin_nocodb-dev_nocodb__countRecords  tableId: <tableId>
```

Then read `getBaseSchema` and look in every other table's fields for `options.related_table_id == <tableId>` — those are the relations that will break.

## Pre-Flight Checklist for New Tables

Before creating:

1. **Title.** Distinct from existing tables. Use TitleCase or sentence-case consistently within a base.
2. **Display field.** Plan to have a `SingleLineText` early in the field list — it auto-becomes the display field.
3. **Required fields.** NocoDB doesn't enforce required at schema level (validation is per-view in Forms); decide if you need form-level required or webhook-driven validation later.
4. **Relations.** If this table will hold link fields, create the parent tables first.
5. **Naming convention.** Use kebab-case or camelCase for field titles? Pick one. NocoDB stores titles verbatim; the API matches by exact title (case-sensitive).

## Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| 422 on create with `fields` | One field's payload doesn't match its type | Check `field-types.md` for the exact `options` keys |
| 400 "title required" | Empty title or whitespace-only | Title is mandatory |
| Display field not what you expected | NocoDB picked the first non-system column | Set `display_field_id` explicitly |
| Delete returns 200 but table still visible | Schema cache | Force-refresh in NocoDB UI or wait ~30s |
| Cannot delete table | A link field on another table points to it | Delete the link field on the other side first |
| `createTable` is not offered by `listTools` | Community Edition | Use the REST recipes above |
