How to connect Supabase

To connect a Supabase project to TeleportHQ, copy its pooler connection string from the Supabase dashboard, paste it into Data Sources → Add Data Source → Supabase, and click Fetch Database Schema. TeleportHQ adds all your Supabase tables to the project, and you can show and edit them in the editor.

Before you start#

• You need a Supabase project and its database password.
• Use the Session or Transaction pooler connection string. TeleportHQ doesn't accept Supabase's "Direct connection" string.
• Connecting Supabase doesn't turn a TeleportHQ website into a web app.

Steps#

1. Copy the connection string from Supabase#

You can follow these steps inside TeleportHQ too: in the Supabase form, click Where to find this? above the Connection String field. A window titled Finding Your Supabase Connection String lists them; close it with Got it.

1. Open your project in the Supabase dashboard.
2. At the top of the page, click Connect.
3. In the Connection string section, set Mode to Session or Transaction.
4. Copy the connection string. It looks like postgresql://postgres.abcd1234:[YOUR-PASSWORD]@aws-0-eu-central-1.pooler.supabase.com:5432/postgres.
5. Replace [YOUR-PASSWORD] with your database password. Forgot it? In Supabase, go to Database → Settings → Database Password to reset it.

2. Add the Supabase data source 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 Supabase card. A panel titled Supabase opens with the section Setup Supabase Connection.
4. In Data Source Name, type a name, for example Bookings.
5. Paste your string into Connection String. When the string is valid, the hint Pooler connection detected appears.
6. Click Fetch Database Schema. It stays greyed out until the string is valid.

TeleportHQ tests the connection, adds all tables and closes the panel. If this is the project's first data source, a window titled IMPORTANT appears first; click I understand.

Check that it worked#

Your Supabase connection appears as a card in the Data Sources panel. Click it: the Database Tables section lists your tables. Click View Data on a table to see its rows.

Troubleshooting#

"Please replace [YOUR-PASSWORD] with your actual database password" The string still contains the placeholder from Supabase. Replace [YOUR-PASSWORD], including the square brackets, with your real password.

"Direct connection URLs are not supported. Please use a Session or Transaction…" You copied the Direct connection string. In Supabase, set Mode to Session or Transaction and copy the string again.

"Invalid connection string format. Expected: postgresql://user:password@host:port/database" Part of the string is missing. Copy it again from Supabase and paste it without extra spaces.

A table is empty in TeleportHQ, but it has rows in Supabase Supabase Row Level Security (RLS, rules that decide who can read each row) is blocking reads. The table viewer says: "If you expect data here, check the RLS (Row Level Security) policies configured in Supabase and make sure that SELECT queries are allowed." Add a policy in Supabase that allows reading the table.

"Failed to test connection" or "Failed to fetch database schema. Make sure that the configuration is correct." Check the password, and that your Supabase project is not paused.

Good to know#

• Full table editing. Supabase tables can be created and edited in TeleportHQ like the built-in database: columns, indexes and links between tables. See Create database tables.
• Your password becomes a Secret. When you save, TeleportHQ stores the connection string in the project's Secrets and links the field to it. To use a Secret you already have, click the plug button next to Connection String (tooltip Link to project secret). See Keep passwords and API keys safe.
• New tables in Supabase show up in TeleportHQ after you refresh the data source. See Refresh, edit or remove a data source.