How to import data from a spreadsheet file

TeleportHQ has two ways to bring a file into a database. To create new tables from a spreadsheet, JSON or database file, click Import from File on the Add a new table card, choose a file such as products.xlsx, and click Import Data: TeleportHQ reads the columns, creates the tables and fills them with your rows. To update a TeleportHQ database table you already have, open the table and use its Import CSV into this table tool: rows whose key is already in the table are updated, and the rest are added.

Before you start#

• Import from File works with the TeleportHQ database, PostgreSQL, MySQL, MariaDB, Amazon Redshift, Supabase, CockroachDB and TiDB. See How to set up the built-in TeleportHQ database.
• Plan. Import from File works on the trial, Pro and Premium. On the trial, a file going into the TeleportHQ database is checked against the trial's lower limits (see Good to know). After the trial or a subscription ends, the button shows a PRO badge, whose tooltip starts "With a PRO subscription, you can create a database by importing a dump file.", and opens the upgrade window instead.
• Put column names in the first row of CSV and spreadsheet files, for example name, price, category. Files without a header row get automatic column names.

Create new tables from a file#

1. In the left sidebar, click Data Sources (the database icon).
2. Click your database card, for example Bakery database.
3. Under Database Tables, on the Add a new table card, click Import from File. The Import Database Structure window opens.
4. Click the area that reads Drag and drop a file here (or Choose File at the bottom), and pick your file. You can also drag the file onto that area.
5. The file's name and size show in the area, and the button at the bottom changes to Import Data. Click it.

When it finishes, a message confirms Successfully created N table(s), sometimes followed by with N warning(s).

Which files you can import#

• Spreadsheets: .csv, .xlsx (Excel) and .ods (OpenDocument).
• JSON records: .json. A list of items, such as [{"name": "Rye loaf", "price": 6}, …], becomes one table named after the file. An object whose values are lists of items, such as {"products": […], "categories": […]}, becomes one table per list. Numbers and true/false values keep their type, and nested objects and lists are stored as JSON.
• Database files: .sql, .dump, .backup, .pgdump, .tar (PostgreSQL archive) and .db (SQLite). A database file can hold several tables; they are all imported.
• Maximum file size: 10 MB.

The window also lists .tsv, but a .tsv file is refused with "Unsupported file format". Save it as .csv first.

What TeleportHQ does with your file#

The What happens when you import? section of the window lists four stages:

1. Extract Structure: reads the tables and columns in your file.
2. Convert to PostgreSQL: turns them into database tables and column types.
3. Resolve Dependencies: puts linked tables in the right order.
4. Import Data: copies your rows into the new tables.

If your database already has a table with the same name, the imported table gets a new name, so nothing is overwritten.

Update an existing table from a CSV file#

The TeleportHQ database can also take a CSV into a table you already have, for example to update this week's prices. Rows whose key (the primary key, or a column marked unique) is already in the table are updated; the others are added.

1. In the Data Sources panel, click your TeleportHQ database card, then click View Data next to the table.

2. In the toolbar above the rows, click the upload icon (tooltip Import a CSV into this table (update matching rows, add the rest)).

   

3. In the Import CSV into this table panel, click Choose CSV file and pick the file.
4. In Match rows on, choose the column that identifies a row, for example id.
5. Under File column → table column, check that each column of your file goes to the right table column. Choose Ignore for a column you don't want to import.
6. The panel shows how many rows are ready, for example 48 rows ready. Click Import 48 rows.

While it works, the panel shows "Importing… 12 of 48". When it's done, it shows the result, such as 20 updated · 28 added. Click Done.

Good to know about this CSV import:

• Empty cells keep the row's current value, or the column's default for new rows.
• Up to 5,000 rows per file. A .tsv file works here too.
• If two rows of the file share a key, the last one wins.
• It's there for TeleportHQ database tables that have a primary key or a unique column, and for the project owner and admins.

Check that it worked#

The new or updated rows show in the table's Content view. Click View Data on a table to check the rows and columns. See How to view, add and edit records. If an import reported warnings, check the column types in the table's Structure view.

Troubleshooting#

"Failed to import database" TeleportHQ couldn't read or convert the file. Check that the file opens in its own app, is under 10 MB, and has column names in the first row. Save Excel files as .xlsx, not the older .xls.

"Unsupported file format. Supported formats: …" The file type isn't one TeleportHQ imports, or it's a .tsv file. Save it as .csv, .xlsx or .json and try again.

A table has fewer rows than my file The table had more than 10% more records than your plan allows per table, so TeleportHQ imported only its first records, up to the limit, and the import ended "with N warning(s)". A table at most 10% over the limit is imported whole. Split the file, or remove rows you don't need. See TeleportHQ database limits by plan.

"Total records (…) exceed the maximum allowed (…) by more than 10%. Please upgrade your subscription or reduce the data size." All the tables of the file together hold more than 10% more records than your database's total limit, so nothing is imported. "Estimated storage size … exceeds the maximum allowed …" means the same for the data's size. Import fewer tables or fewer rows at once.

"The file is not valid JSON." The .json file has a mistake, such as a missing comma or a name without double quotes. Check it in a JSON validator and choose it again. If the message says "The JSON file must hold an array of objects (one table), or an object whose values are arrays of objects (one table each).", the file holds something else, such as a single item: put the items in a list.

"You've reached the maximum number of tables for your plan (limit: N)…" The import would take the database past its table limit. Remove tables you don't need, or import fewer tables at once.

The import finished "with N warning(s)" The import worked, but some parts of the file needed adjusting. Open the table's Structure view and fix the column types if needed. See How to add columns and link tables together.

"The file has no header row naming its columns." The CSV import into an existing table needs column names in the first row. Add them and choose the file again.

"Map a file column to id to match rows." In File column → table column, send one of your file's columns to the column chosen in Match rows on.

Good to know#

• Import limits: one file can create up to 50 tables (more is refused with "The file contains N tables, which exceeds the maximum allowed (50)…"), and can't take your TeleportHQ database past its plan limits.
• On the trial, the TeleportHQ database is on the lower tier, which holds 5,000 records per table, and the import checks your file against that tier's numbers, not the Pro and Premium ones. See Why is my TeleportHQ database inactive?
• Import or CSV data source? Importing puts your rows in a database you can edit. A CSV File data source, or a list typed in the JavaScript data source, only displays the data and can't be edited row by row in TeleportHQ.