Docs menu

Connect from a laptop

Open an app's own Postgres on the laptop you manage your Linux server from, for psql, Prisma, Drizzle or supabase db push. The database stays closed to the internet: each connection goes through Secretbase, with your token.

Open it

On a laptop that reaches the server as server, with a token for the app (below):

$ secretbase db connect my-app --to server

It prints the address to use, then waits:

postgresql://app:<password>@<local address>/app
Open until you press Ctrl-C.

The address is on the laptop itself (port 5432, or the next free one; --port <N> picks one), so only programs on the laptop can use it. The password in it is the app's own database password: it is shown only in that terminal, never logged. Press Ctrl-C to close every connection.

The printed address is a secret, because it holds that password. Never put it in git, a chat or a shared file, and never type it out on a command line, where it stays in your shell history.

On the server itself, leave out --to server.

Use it

In a second terminal, read the address it printed into a variable: run read -rs DATABASE_URL, paste the address (it isn't shown while you type) and press Enter. Then use "$DATABASE_URL" in place of the address:

$ read -rs DATABASE_URL && export DATABASE_URL
$ psql "$DATABASE_URL"
$ npx prisma migrate deploy
$ supabase db push --db-url "$DATABASE_URL"

Prisma reads it where its schema says url = env("DATABASE_URL"). For Drizzle, set dbCredentials.url in drizzle.config.ts to process.env.DATABASE_URL, then run npx drizzle-kit migrate in the same terminal. The variable is gone once that terminal is closed.

Which token

db connect needs a token for that app: an App token or a co-developer token (not one made with --scope read), or a Server token with full control. A limited Server token can't open it. On the server:

$ secretbase tokens create --name laptop-db --app my-app

Then on the laptop, run secretbase remote add server <address> with the server's address and paste that token when it asks (as in Linux server). The same token works for the app's Backend commands with --to server. See Tokens.

Limits

  • At most 5 connections to one app at a time.
  • A connection idle for 30 minutes is closed.
  • The app's Postgres must be on and running.
  • Connections close when the token is revoked or ends, and when the app is taken offline or deleted.
  • Each connection is a line in secretbase activity: who, which app, when. Never what was sent.

If something goes wrong

$ secretbase db connect my-app
my-app has no Postgres database running, so there is nothing to connect to. Turn it on with `secretbase database my-app postgres on`; it runs while the app is online. (HB-DATABASE-015)
  • "my-app already has 5 connections open…" (HB-DATABASE-016): close one, then try again.
  • "Port <N> on this computer is taken; choose another with --port."