---
title: "db add"
description: "Add a database connection"
canonical: "https://pgbeam.com/docs/cli/db/add"
last-updated: "2026-09-14T19:37:21.000Z"
---

# db add

> Add a database connection

URL: https://pgbeam.com/docs/cli/db/add

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

## 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

-

All global options (`--token`, `--profile`,
`--project`, `--org`, `--json`, `--no-color`, `--no-trunc`, `--debug`) are
also available on this command.

## Examples

## Output

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.