How to connect a database (PostgreSQL, MySQL, MongoDB, Firestore and more)

In TeleportHQ, you connect a database you already own from the Data Sources panel: click + (Add Data Source), pick the database type, enter its connection details, then click Fetch Database Schema. TeleportHQ tests the connection, adds all the database's tables to your project and saves the data source, ready to show on your pages. Connecting a database doesn't turn a website into a web app.

Before you start#

• Your database must be reachable from the internet. TeleportHQ connects to it from its own servers. If your database only accepts connections from certain IP addresses, allow public inbound connections.
• Have your connection details ready: the host (server address), port, database name, username and password, or a connection string (one line that holds all of these).
• Each database type can be connected once per project. If the card shows Already connected, that type is already in use in this project. This applies to PostgreSQL, MySQL, MariaDB, Amazon Redshift, MongoDB, Redis, Firestore, ClickHouse, CockroachDB, TiDB and Turso.
• Using Supabase or Airtable? They have their own guides: Connect Supabase and Connect Airtable.
• Don't have a database? Use the built-in TeleportHQ database instead.

Open the database setup form in TeleportHQ#

These steps are the same for every database type in TeleportHQ.

1. In the left sidebar, click Data Sources (the database icon).
2. In the Data Sources panel, click + (tooltip Add Data Source).
3. Click the card for your database, for example PostgreSQL. Its setup form opens beside the panel.
4. In Data Source Name, type a name, for example Gym members. Use letters, numbers, spaces and underscores. You can leave it empty, and a name is created for you.

Then follow the section for your database below. When you click Fetch Database Schema and this is the project's first data source, a window titled IMPORTANT appears first: click I understand to save. See What are data sources, and which ones can I connect?.

Connect PostgreSQL, MySQL, MariaDB or Amazon Redshift#

To connect a PostgreSQL, MySQL, MariaDB or Amazon Redshift database to TeleportHQ, fill in the server details one field at a time.

1. In Host, type the server address, for example database.example.com.
2. In Port, keep the default or type your own. The defaults are 5432 for PostgreSQL, 3306 for MySQL and MariaDB, and 5439 for Amazon Redshift.
3. In Database Name, type the database name, for example gym.
4. In Authentication Type, choose Password. It starts on No Authentication, which is only for databases that need no login. The User and Password fields appear.
5. Fill in User and Password.
6. If your database requires a secure connection, turn on Enable SSL. Paste the CA Certificate, Client Certificate and Client Key if your provider gave you them.
7. Click Fetch Database Schema. The button stays disabled until Host, Database Name and User are filled.

TeleportHQ adds all tables it finds, saves the data source and closes the panel.

Connect CockroachDB or TiDB#

To connect CockroachDB or TiDB to TeleportHQ, you can use a connection string or separate fields.

1. In Connection String (called Connection String (Optional) for TiDB), paste your connection string. For CockroachDB it looks like postgresql://user:password@host:port/database; for TiDB, mysql://user:password@host:port/database. When filled, it is used instead of the fields below.
2. Or leave it empty and fill in Host, Port, Username, Password and Database Name.
3. Click Fetch Database Schema.

Connect MongoDB#

To connect a MongoDB database to TeleportHQ, use your connection string or the separate fields.

1. In Connection String, paste a string such as mongodb+srv://user:password@cluster.example.net/shop. When filled, it is used instead of the fields below.
2. Or fill in Host, Port, Username, Password and Database Name.
3. Click Fetch Database Schema.

TeleportHQ adds every collection it finds. They are listed under Confirmed Data Sources when you open the data source again.

Connect Redis#

To connect a Redis server to TeleportHQ, use a connection string or the separate fields.

1. In Connection String, paste a string such as redis://user:password@host:6379/0 (or rediss://… for a secure connection).
2. Or fill in Host, Port, Username and Password (both optional) and Database, the Redis database number (usually 0 to 15).
3. Click Fetch Redis Schema.

Redis data in TeleportHQ is read-only. You can show it on pages, but you can't change its structure from the editor.

Connect Firestore#

To connect Firebase Firestore to TeleportHQ, you need a service account key (a JSON file from Firebase that gives access to your project).

1. In the Firebase console, open Project Settings.
2. Open the Service Accounts tab.
3. Click Generate New Private Key. A JSON file downloads.
4. Back in TeleportHQ, click Upload Service Key and choose that file. Or paste its contents into Service Account Key.
5. Click Fetch Database Schema.

The form's Where to find this? link shows the same steps.

Connect ClickHouse#

To connect a ClickHouse database to TeleportHQ, you need its web address and login.

1. In ClickHouse URL, paste your server address, for example https://abc123.eu-central-1.aws.clickhouse.cloud:8443.
2. Fill in Username and Password.
3. Click Fetch Database Schema.

Connect Turso#

To connect a Turso database to TeleportHQ, you need the database URL and an auth token from Turso.

1. In Database URL, paste the address, for example libsql://your-database.turso.io.
2. In Auth Token, paste your Turso auth token.
3. Click Fetch Database Schema.

Check that it worked#

The panel closes and your database appears as a card in the Data Sources panel. Click the card to open it again:

• SQL databases and Turso list their tables under Database Tables, each with a View Data button.
• MongoDB, Redis, Firestore and ClickHouse list them under Confirmed Data Sources.

Click View Data on any table to see its rows. Next, show the data on your pages.

Troubleshooting#

"Failed to test connection. Make sure that the database exists, the credentials are correct and the database allows inbound traffic from public IPs." TeleportHQ could not reach or log in to your database. Check the host, port, database name, username and password. Then, in your database provider's settings (for example the security group on AWS), allow connections from public IP addresses.

"Failed to test connection. Make sure that the credentials are correct and the Redis server allows inbound traffic from public IPs." The same problem for Redis: check the password and allow public connections to the server.

"Failed to test connection. Make sure that the service account is valid and has the necessary permissions." Your Firestore key is wrong or lacks access. Generate a new private key in Firebase and upload it again.

"Invalid JSON file. Please upload a valid service account key file." The file you uploaded for Firestore is not the service account key. Upload the .json file Firebase downloaded.

"Failed to fetch database schema. Make sure that the configuration is correct." The connection worked but TeleportHQ couldn't read the tables. Check that the user has permission to read the database structure.

"We could not find any tables inside the provided … source." The database is empty, or you typed the wrong database name. Check the name. If the database really is empty, create a table first.

The database card shows "Already connected" This project already has a connection of that type, and the card can't be clicked. Open the existing data source from the Data Sources panel to change its details. See Refresh, edit or remove a data source.

Fetch Database Schema stays greyed out A required field is empty. For PostgreSQL, MySQL, MariaDB and Amazon Redshift, fill in Host and Database Name, and User when Authentication Type is Password.

Good to know#

• All tables are added. There is no step to pick only some tables. Use refresh to pick up tables you add later, or remove the ones you don't need.
• Passwords become Secrets. When you save, TeleportHQ moves your password, connection string or token into the project's Secrets and links the field to it. See Keep passwords and API keys safe.
• Your project stays a website. Connecting your own database doesn't ask you to enable web app features, and the project needs no Web App slot.
• What you can change from TeleportHQ depends on the database: