How to add columns and link tables together

In TeleportHQ, you change what a database table stores in the Structure view of its table window, without writing SQL. Click Add Column to add a field such as photo, click the pencil (Edit column) to change one, and tick Foreign Key to link a column to another table, for example each order to the customer who placed it. Changes you make are listed under Recent changes, where you can revert them.

Before you start#

• Full column editing works on the TeleportHQ database, PostgreSQL, MySQL, MariaDB, Amazon Redshift, Supabase, CockroachDB and TiDB. ClickHouse, Turso, MongoDB, Firestore and Airtable support only some changes. REST APIs, JavaScript data, Google Sheets, CSV files and Redis can't be changed.
• Only the project owner or an admin can change columns. See What can each role do?
• The table must already exist. See How to create database tables (by hand or with AI).

Open the Structure view#

1. In the left sidebar, click Data Sources (the database icon).
2. Click your database card, then click View Data next to the table.
3. At the top of the table window, click Structure.

The Columns list shows each column with its type, its default value (after =) and badges.

1. Badges: PK (primary key), UQ (unique), NOT NULL (required) and, on a linked column, FK → followed by the table it links to. Point at the FK badge to see the exact column, for example "References customers.id".
2. Edit column (the pencil).
3. Drop column (the trash can).

Add a column#

To add a column to a TeleportHQ database table, for example photo to a products table:

1. In Structure, under the column list, click Add Column. A new column form opens.
2. In Name, type photo.
3. In Type, choose a text type, for example TEXT. Some types ask for Length, Precision or Scale.
4. Optionally set Default, the value new rows get automatically. For example choose NULL, or Custom value… and type a value.
5. Leave Nullable ticked if the column can be empty. Tick Unique if no two rows may have the same value.
6. Click Add Column under the form.

A message confirms Column "photo" added successfully. The Primary Key option isn't in this form when the table already has a primary key.

Link two tables with a foreign key#

A foreign key links a column to a column in another table. For example, orders.customer_id points to customers.id, so each order belongs to one customer. To link TeleportHQ database tables:

1. Open the table that holds the link, for example orders, in Structure.
2. Click Add Column, or the pencil (Edit column) on an existing column such as customer_id.
3. Tick Foreign Key.
4. In References Table, choose customers.
5. In References Column, choose id. The column's Type changes to match and locks: "a foreign key must have the same type as the column it references."
6. Optionally choose On Delete, what happens to orders when their customer is deleted. The line under the field explains each choice: CASCADE deletes the orders too, SET NULL keeps them and clears the link, RESTRICT and NO ACTION block the delete. On Update works the same way for a changed id.
7. Click Add Column (or Save when you edit a column).

The column now shows FK → customers. Click Diagram at the top of the table window to see the link as a line between the two tables.

Edit or delete a column#

• To change a column, click its pencil (Edit column), change the settings, and click Save.
• To delete a column, click its trash can (Drop column). The Confirm Delete window asks "Are you sure you want to drop the column …? This will permanently delete all data in this column." Click Drop column to confirm, or Cancel. For a linked column, the window explains that only the link and the column's values go: the table keeps all its rows.

A primary key column can't be dropped: its trash can is greyed out ("Cannot drop primary key column").

Revert a change from Recent changes#

Every column and index change you make in Structure is listed under Recent changes, newest first, for example "Added column photo". The list is "Kept until you reload the editor".

1. Find the change in Recent changes.
2. Click Revert. The button turns into Confirm revert, and a warning may show, such as "Reverting drops the column and anything written to it since."
3. Click Confirm revert.

A dropped column comes back with its values (up to 5,000 rows). If a later change depends on this one, the list says to revert that one first, for example: Revert “Added index idx_photo” first to revert this.

Add an index#

Indexes make searches and sorting on large tables faster. In Structure, under Indexes:

1. Click Add Index.
2. Type an Index Name, for example idx_products_category.
3. Under Columns:, tick the columns it covers.
4. Tick Unique if no two rows may share those values.
5. Click Create Index.

For the TeleportHQ database, a line above the indexes shows how many you use, for example "TeleportHQ databases have a limit of 20 indexes across all tables. Currently using: 3 / 20 indexes".

Check that it worked#

The column appears in the Columns list with the right type and badges. In Content, the new column shows for every row. On your pages, the new field appears in the Select Dynamic Property panel when you bind an element.

Troubleshooting#

"Foreign key blocked by existing data" Some rows already hold values that don't exist in the linked table (orphan rows). Choose Set "<column>" to NULL to empty them, Delete N orphan row(s) to remove those rows, or Cancel and fix the values in Content first.

"Cannot create foreign key: Column type (X) must match referenced column type (Y)" The two columns have different types. Pick the References Column again so the type is copied, or change the column's Type.

"Select the referenced table and column for the foreign key" Choose both References Table and References Column, or untick Foreign Key.

The Foreign Key box can't be ticked The database has no other table to link to ("No tables available to reference"). Create the other table first.

"Cannot remove primary key. Tables must have at least one primary key column." Every table needs a primary key. Add another primary key column before removing this one.

"Cannot drop the last column in a table" A table must keep at least one column. Add the new column first, then drop the old one.

"order" is a reserved keyword and cannot be used as a column name or "Invalid column name" Column names can use letters, numbers and underscores, can't start with a number, can't have two underscores in a row or end with one, and can't be SQL words like select, order or group. Try order_date instead of order.

Column "x" already exists in this table Pick a different name.

"You've reached the maximum number of columns per table for your plan (limit: 20)…" A TeleportHQ database table has the most columns your plan allows. See TeleportHQ database limits by plan.

Good to know#

• Index limits in the TeleportHQ database depend on your plan: 20 on the trial, Pro and Premium. See TeleportHQ database limits by plan.
• What each database supports: ClickHouse has no foreign keys, unique columns or column editing; Turso has no foreign keys or column editing; MongoDB supports indexes only; Firestore supports creating collections only; Airtable supports adding, changing and removing fields.
• Names can be up to 64 characters.