Connecting to your database

There are four ways to reach a project's database on SupaHost. Which ones you can use depends on your plan and on whether you're the instance owner. There's no public Postgres port and no connection pooler, so the usual Supabase Cloud connection strings (db.<ref>.supabase.co, port 6543) don't apply here.

If you only need a copy of the data, any plan can also download a pg_dump file from the Backups tab. See Exporting your data.

Data API: from your app

This is how your application should talk to the database on every plan. PostgREST turns your tables, views and functions into a REST API, and supabase-js wraps it.

Find the values in Dashboard → your project → Connect tab → App: the Project URL, the anon key (labelled "public") and the service_role key (labelled "secret", behind Reveal, owner only).

# .env
SUPABASE_URL=https://app-one.acme.supahost.space
SUPABASE_ANON_KEY=eyJhbGciOi...

import { createClient } from '@supabase/supabase-js'

const supabase = createClient(process.env.SUPABASE_URL!, process.env.SUPABASE_ANON_KEY!)

const { data, error } = await supabase
  .from('bookings')
  .select('id, starts_at, room')
  .gte('starts_at', new Date().toISOString())
  .order('starts_at')

The Data API works from browsers, mobile apps, serverless functions and edge runtimes alike, because it's plain HTTPS. Access is controlled by grants and Row Level Security. See The Data API.

Studio SQL editor: ad-hoc SQL in the browser

The instance owner can open Supabase Studio for any project and run SQL there. Go to Dashboard → your project → Database tab → Open Studio (or use the Studio button in the project header), then pick the SQL editor.

Studio connects as the postgres role, so the SQL editor can create tables, write policies and enable extensions. Studio takes about 20 seconds to start on first visit. See Using Supabase Studio.

MCP execute_sql: for AI coding agents

The SupaHost MCP server lets tools such as Claude Code or Cursor run SQL against a project with the execute_sql tool, and change the schema with apply_migration.

1. Create a token in Dashboard → AI agents (MCP) (or your project → Connect → AI agents (MCP)). Choose the scope (one project or the whole instance) and tick Read-only if the agent should only look.
2. Add the server to your client using the snippet shown. The endpoint is https://mcp.supahost.space/mcp, with the token sent as Authorization: Bearer shp_....

In read-only mode, SQL runs as a role that can read everything but can't write, and the write tools aren't offered at all. See The SupaHost MCP server.

Direct Postgres: Business and Enterprise

On Business and Enterprise you can connect psql, pg_dump, Prisma, Drizzle, DBeaver or any other Postgres client from your own machine. Postgres itself only listens on 127.0.0.1 inside the VM, so you reach it through an SSH tunnel.

1. Add your SSH public key. Go to your project → Connect → SSH & CLI, paste the key into Public key and click Add key. It becomes active within a minute. Supported types are ed25519, RSA (2048 bits or more), ECDSA and the security-key variants. An instance can hold up to 20 keys.

2. Open the tunnel and leave it running. With instance acme:

ssh -N -L 5432:127.0.0.1:5432 [email protected]

3. Get the connection string. In your project → Connect → Database, click Show connection string (owner only). It looks like this and only works while the tunnel is open:

postgresql://postgres:<password>@127.0.0.1:5432/p_app_one

The database name is p_ plus the project name with hyphens turned into underscores.

4. Connect.

psql "postgresql://postgres:<password>@127.0.0.1:5432/p_app_one"

If something on your machine already uses port 5432 (a local Postgres, or the Supabase CLI's database), forward a different local port and use it in the string:

ssh -N -L 5433:127.0.0.1:5432 [email protected]
psql "postgresql://postgres:<password>@127.0.0.1:5433/p_app_one"

psql on the VM itself

The same SSH key also lets you run a few commands on the instance without a tunnel:

ssh [email protected]
sudo supahost-psql app-one                      # interactive psql as postgres
sudo supahost-psql app-one -c "select count(*) from bookings"
sudo supahost-db-url app-one                    # prints the tunnel connection string

The supahost user has no root and can only run these commands (plus supahost-logs and supahost-status). See SSH access and direct Postgres.

Connections are a shared budget

Postgres on your instance allows 400 connections in total, shared by every project and by the platform's own services. There's no pooler in front of it. When you connect an ORM or a worker over the tunnel, set a small pool size (a handful per process is plenty) and close idle connections. See Connections and timeouts.

Serverless and edge code

Serverless functions and edge runtimes open many short-lived connections, which is the case a pooler exists for. On SupaHost, call the Data API from that code with supabase-js instead, or move the logic into a database function and call it with RPC. Edge Functions on SupaHost get SUPABASE_URL and the keys as environment variables, but no database URL.

Troubleshooting

• Connecting directly to Postgres (psql, pg_dump, ORMs)
• Connection refused or timeout when connecting to Postgres
• FATAL: password authentication failed
• Too many connections