db add
Add a database connection
Add a new database connection to the linked project. PgBeam will use these credentials to connect to your upstream PostgreSQL server. Without the required flags, the command runs interactively and prompts for host, name, username, password, and SSL mode. Advanced flags (role, pool region, query timeout, read routing, and cache/pool config) are optional and default to the platform defaults. After adding, use pgbeam db test to verify connectivity.
Usage
pgbeam db add [flags]Options
| Option | Description | Required | Default |
|---|---|---|---|
--host <value> | Hostname or IP address of the PostgreSQL server | No | - |
--port <value> | Port number of the PostgreSQL server | No | 5432 |
--name <value> | Name of the database on the server | No | - |
--username <value> | Username for authenticating with the database | No | - |
--password <value> | Password for authenticating with the database | No | - |
--ssl-mode <value> | SSL connection mode: disable, require, verify-ca, or verify-full | No | - |
--role <value> | Database role: primary (receives writes) or replica (receives reads) | No | - |
--pool-region <value> | Region where the connection pool is maintained (near the database). Empty means direct connection. | No | - |
--query-timeout-ms <value> | Query timeout in milliseconds. 0 means disabled (default). | No | - |
--auto-read-routing | Auto-route SELECT queries to read replicas | No | - |
--cache-enabled | Enable query result caching for this database | No | - |
--cache-ttl <value> | Time-to-live for cached query results, in seconds | No | - |
--pool-mode <value> | Connection pool mode: transaction, session, or statement | No | - |
--pool-size <value> | Maximum number of connections in the pool | No | - |
--min-pool-size <value> | Minimum number of idle connections maintained in the pool | No | - |
Global options
All global options (--token, --profile,
--project, --org, --json, --no-color, --no-trunc, --debug) are
also available on this command.
Examples
# Interactive database setup
pgbeam db add
# Add with all connection flags
pgbeam db add --host db.example.com --port 5432 --name mydb --username admin --password secret --ssl-mode require
# Add a read replica near its region with auto read routing
pgbeam db add --host replica.example.com --name mydb --username admin --password secret --role replica --pool-region us-east-1 --auto-read-routing
# Add with a query timeout and caching enabled
pgbeam db add --host db.example.com --name mydb --username admin --password secret --query-timeout-ms 30000 --cache-enabled --cache-ttl 60
# Add and get result as JSON
pgbeam db add --host db.example.com --name mydb --username admin --password secret --jsonOutput
Prints the new database ID, name, and host:port. Suggests running pgbeam db test <id> to verify the connection. With --json, returns the full database object.