Connecting to your database
pocketPG supports three connection methods:
- a direct PostgreSQL connection string
- a PostgreSQL connection reached through an SSH tunnel
- a saved instance profile stored in the pocketPG app database
The product is designed to diagnose first. Routine monitoring reads are read-only. Owner-only execution features such as Query Runner, EXPLAIN ANALYZE, or maintenance actions are separate product surfaces.
Direct connection string
Enter a standard PostgreSQL URI:
postgres://user:password@host:5432/dbname
pocketPG tests the connection before loading the dashboard.
If pg_stat_statements is already installed and loaded, the Queries tab and several tuning workflows become available. pocketPG does not install that extension for you.
SSH tunnel
Use an SSH tunnel when the PostgreSQL server is not directly reachable from the internet and you already have a bastion or jump host.
| Field | Description |
|---|---|
| SSH Host | Bastion or jump host address |
| SSH Port | Default 22 |
| SSH User | SSH username |
| SSH Private Key | PEM-format private key (stored server-side for saved instances) |
The SSH tunnel is established by the pocketPG backend, then the PostgreSQL connection is opened through that tunnel.
For saved instances, pocketPG stores the SSH material server-side so shared members can use the saved instance without being shown the raw key.
Saved instances
When you save an instance, pocketPG stores the connection details server-side in the app database. This enables:
- shared access without sharing raw credentials
- background checks for alerts, daily digests, and webhooks
- server-backed history for features that depend on saved instances
Accepted members of a shared instance do not receive the raw connection string or SSH private key.
Default connection behavior
Every monitoring connection uses a few safety defaults:
- Autocommit prevents pocketPG reads from leaving an open transaction behind.
- Statement timeout limits how long one monitoring query can run.
- Lightweight pooling is used for direct connections so repeated reads do not repeat the full connect/authentication path every time.
These defaults matter because PostgreSQL diagnostic queries are still real queries. Even when they are read-only, they should not be allowed to hang indefinitely or leave transaction state behind.