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

# Tables

> Create, rename, and delete tables in your Data Model. Every table generates a GraphQL and REST API automatically.

A table is a named collection of records with a fixed set of fields. When you add a table, Archie provisions it in your workspace's PostgreSQL database and generates the corresponding GraphQL and REST endpoints automatically.

## Creating a table

You can create a table manually or describe what you need in plain language and let the AI generate it.

<Steps>
  <Step title="Open the Data Model">
    Click **Data Model** in the project sidebar. The list of existing tables appears.
  </Step>

  <Step title="Click + Add Table">
    The **Add Table** modal opens.
  </Step>

  <Step title="Name the table">
    Enter a unique, lowercase identifier (for example `products`, `orders`, `members`). This is the name that will appear in the GraphQL and REST APIs.
  </Step>

  <Step title="Add a description (optional)">
    Briefly describe what the table stores. This helps your team and any AI agents working on your project understand its purpose.
  </Step>

  <Step title="Build with AI (optional)">
    Instead of adding fields by hand later, describe the table in plain language — for example, *"Create a loans table with customer, book, loan date, due date, and status"*. You can also pick one of the suggestion chips to start from a template.
  </Step>

  <Step title="Create the table">
    Click **Create Table**. The table appears in the sidebar, ready for fields.
  </Step>
</Steps>

<img src="https://mintcdn.com/archie-e998dbf6/GdaYz5W-YpQoJXsQ/features/backend/data-model/data-builder-add-table-modal.png?fit=max&auto=format&n=GdaYz5W-YpQoJXsQ&q=85&s=6f4f685d03da2535e51a552aeb43a3ad" alt="Add Table modal dialog" width="1866" height="1022" data-path="features/backend/data-model/data-builder-add-table-modal.png" />

## The Schema and Data tabs

Every table has two tabs:

* **Schema** — design the table: add fields, set defaults, configure validation, define relationships, and create indexes.
* **Data** — view, edit, import, and export the records inside the table. See [Data Viewer](/features/backend/data-model/data-viewer).

<img src="https://mintcdn.com/archie-e998dbf6/GdaYz5W-YpQoJXsQ/features/backend/data-model/data-model-overview.png?fit=max&auto=format&n=GdaYz5W-YpQoJXsQ&q=85&s=ad3d1963133ab33664fb3aa6c8b7148b" alt="Data Model overview and schema" width="1866" height="853" data-path="features/backend/data-model/data-model-overview.png" />

## Renaming and describing a table

On the **Schema** tab, the table name and description sit at the top of the canvas.

* Click the table name to rename the table. The name change propagates to the auto-generated GraphQL and REST APIs immediately.
* Click the description below the name to edit it.

## Adding and configuring fields

Click **+ Add Field** below the field list to add a column. Each field has a type — boolean, date, number, text, JSONB, UUID, relationship, inline enum, or a reusable Data Type. See [Fields](/features/backend/data-model/fields) for the full list and configuration options.

## Deleting a table

You can delete a table from two places.

**From the sidebar:** hover the table in the **Tables** list and click the red trash can icon next to its name.

**From the table header:** open the table and click the trash can in the top-right corner of the **Schema** tab.

<img src="https://mintcdn.com/archie-e998dbf6/GdaYz5W-YpQoJXsQ/features/backend/data-model/data-builder-delete-table.png?fit=max&auto=format&n=GdaYz5W-YpQoJXsQ&q=85&s=475539b59b20a0445446ac1ed8231530" alt="Delete table with trash icon" width="1866" height="1022" data-path="features/backend/data-model/data-builder-delete-table.png" />

<Warning>
  Deleting a table permanently removes its records and drops it from the GraphQL and REST APIs. There is no undo.
</Warning>

## System tables

Archie ships with system tables that the platform itself depends on — most notably **`users`**, **`roles`**, and **`user_roles`**. These tables appear in the Data Model so you can extend them with custom fields, but their core fields are read-only and the table itself cannot be renamed or deleted. The trash can icon is hidden on system tables.

You can still:

* Add new fields alongside the system fields.
* Read and write rows through the Data Viewer and the auto-generated APIs.
* Govern access to them in [Role-Based Access](/features/backend/app-services/role-based-access).

## Safety checks when updating a table

Archie protects against changes that would silently break existing data:

* Switching a field from optional to mandatory prompts you for a default value to backfill existing rows.
* Changing the type of a Date, Number, or Text field automatically converts existing values where possible.
* Switching a field to **Unique** validates that the current values are already unique before applying the change.

## Permissions

Who can read or write each table is configured in **App Services → Role-Based Access**, not in the Data Model. See [Role-Based Access](/features/backend/app-services/role-based-access).

## FAQ

<AccordionGroup>
  <Accordion title="Why can't I delete the users table?">
    `users`, `roles`, and `user_roles` are system tables. The platform's authentication and access control depend on them, so the delete and rename actions are disabled. You can still add custom fields to them.
  </Accordion>

  <Accordion title="What happens to the GraphQL and REST APIs when I rename a table?">
    Both APIs regenerate immediately. Any client code or integrations that referenced the old name will need to be updated to the new name.
  </Accordion>

  <Accordion title="Can I undo a table deletion?">
    No. Deleting a table drops the underlying records and the generated API endpoints. Export the data first if you might need it again.
  </Accordion>

  <Accordion title="How do I let some user types read a table but not write to it?">
    Configure that in [Role-Based Access](/features/backend/app-services/role-based-access). The Data Model defines the shape of the table; permissions are enforced separately on every auto-generated query and mutation.
  </Accordion>

  <Accordion title="Can I generate a table from a description instead of adding fields by hand?">
    Yes. The **Build with AI** section of the Add Table modal accepts a plain-language description and generates a starter table with suggested fields, which you can then refine.
  </Accordion>
</AccordionGroup>