tpaw Docs

First Connection

Create your first PostgreSQL connection in tpaw using a URL or manual form entry.

Creating a connection in tpaw takes under a minute. You can paste a PostgreSQL URL to auto-fill all fields, or enter credentials manually. Credentials are stored securely in the macOS Keychain.

Required fields

FieldRequiredNotes
NameYesLabel shown on the connection card
HostYesHostname or IP address
PortYesDefault: 5432
UsernameYesPostgreSQL role name
PasswordNoLeave empty for peer/trust auth
DatabaseNoOmit to connect to the default database

Option A: Paste a connection URL

If your service provides a PostgreSQL URL, paste it into the URL field at the top of the connection form. tpaw parses the URL and fills in Host, Port, Username, Password, Database, and SSL mode automatically.

Supported URL format:

postgres://username:password@host:5432/database?sslmode=require

Both postgres:// and postgresql:// schemes are accepted.

Option B: Fill the form manually

  1. Click New Connection on the home screen (or press Cmd+N)
  2. Enter a Name for the connection (e.g., "Local Dev" or "Production DB")
  3. Fill in Host, Port, Username, and optionally Password and Database
  4. Choose an SSL mode: Disable, Prefer, or Require
  5. Optionally add an Environment tag (prod / staging / dev / local)
  6. Optionally enable an SSH tunnel

Test before saving

Click Test to verify connectivity before saving. tpaw attempts a real connection and shows:

  • Green banner: connection succeeded
  • Red banner: error message with the PostgreSQL error code

Fix any errors before clicking Save.

Save the connection

Click Save. The connection card appears on the home screen. Click it to connect.

tpaw automatically reconnects to the last active connection when restarted.

Next steps

On this page