How to set up the built-in TeleportHQ database

The TeleportHQ database is a ready-made database hosted by TeleportHQ, so you can store products, bookings or members without setting up a server. To add it, open Data Sources in the editor's left sidebar, click + (Add Data Source), choose TeleportHQ database and click Setup TeleportHQ Database. TeleportHQ creates the database for your project, and you then add tables to it from the editor.

Before you start#

• It only works on sites hosted by TeleportHQ. The panel says so in its Important box: if you download your project's code, the database connection won't work outside TeleportHQ hosting.
• One TeleportHQ database per project. Once a project has one, the TeleportHQ database card in Add Data Source shows Already connected.
• Some features use it too. Authentication, E-Commerce, the Blog and Help Center, the Admin Panel and the AI Assistant Chat keep their data in a database. When you turn one on, its window offers to set up the TeleportHQ database for you, or to use a database the project already has. Bookings works only with the TeleportHQ database: its window says "Next, choose the database your bookings are stored in.", and with none yet, "Bookings are stored in the TeleportHQ database. Create it to continue." If the project's other features already use another database, Bookings can't be turned on until they're connected to the TeleportHQ database. Features you switch on with Project Menu → Edit → Enable Plugins… always use the TeleportHQ database.
• How much it can hold depends on your plan. See TeleportHQ database limits by plan.
• On the trial, the database runs on the lower tier. A TeleportHQ database created during the trial holds 5,000 records per table and becomes inactive 7 days after it's created. Its Plan Limitations box shows a Trial Plan badge with these starter numbers and says so. Subscribing to Pro or Premium moves it to the Pro and Premium tier. See Why is my TeleportHQ database inactive?

Steps#

1. In the left sidebar, click Data Sources (the database icon).
2. At the top of the Data Sources panel, click + (tooltip Add Data Source). In a project without data sources, you can also click Add data source in the middle of the panel.
3. In the Add Data Source panel, click the TeleportHQ database card.

4. In Data Source Name, type a name, for example Bakery database. The name is optional: left empty, TeleportHQ makes one up.
5. Read the Important box and the Plan Limitations box.
6. Click Setup TeleportHQ Database. The button reads Provisioning Database... while the database is created.

7. If this is the project's first data source, a window titled IMPORTANT appears first. It explains that code download is limited to Next.js once a project has a data source. Click I understand to continue.

Check that it worked#

When the database is ready, the set-up panel closes and the new database shows as a card in the Data Sources panel, of type TeleportHQ database. Click the card: the panel now shows Setup TeleportHQ Database with a check mark, and a Database Tables section with the Add a new table card. The database starts empty. Next, create your first tables or import a spreadsheet.

Troubleshooting#

"Failed to provision database" or "Failed to setup database" TeleportHQ couldn't create the database. Wait a minute and click Setup TeleportHQ Database again. If it keeps failing, write to hello@teleporthq.io.

The TeleportHQ database card shows "Already connected" The project already has a TeleportHQ database, often created by a feature like Authentication, E-Commerce or Bookings. Close Add Data Source and click the existing card in the Data Sources panel instead.

My database stopped working after a few days Databases on the lower tier, including every database created during the trial, become inactive 7 days after they're created. Subscribe to Pro or Premium to restore the database. See Why is my TeleportHQ database inactive?

Good to know#

• Where the data lives: the TeleportHQ database is a PostgreSQL database hosted for you. Each project gets its own.
• Editing your data: open any table with View Data to add, edit and delete rows. See How to view, add and edit records.
• Changes are live: your published site reads the database when visitors open a page, so new records appear without publishing again.
• Your project stays a website. Setting up the TeleportHQ database by hand doesn't ask to turn your website into a web app. The features that use it, such as user sign-in, the store, bookings or the blog, do when you turn them on. See What's the difference between a website and a web app?
• Downloading code: code that uses the TeleportHQ database can't connect to it outside TeleportHQ hosting. If you plan to host elsewhere, connect your own database instead. See also Can I download my site's code?