Getting Started

Connect an existing PostgreSQL app to PgBeam without changing your driver or ORM.

PgBeam sits between your app and Postgres. You point your client at a PgBeam hostname, keep speaking normal PostgreSQL, and get a control plane for pooling, caching, analytics, replicas, and global routing.

Start with the boring change

Most teams can get started by changing one thing: the host in DATABASE_URL. No SDK. No protocol shim. No application rewrite.

What changes

Update your connection string

# Before
DATABASE_URL=postgresql://user:pass@db.example.com:5432/mydb

# After
DATABASE_URL=postgresql://user:pass@abc.aws.pgbeam.app:5432/mydb

PgBeam still speaks the PostgreSQL wire protocol, so your existing drivers and ORMs keep working. The difference is that connections now land on a PgBeam data plane first, where pooling, routing, analytics, and optional caching can happen.

What you get

🔗

Connection Pooling

Keep upstream connection pressure under control without wiring PgBouncer into every environment.

⚡

Query Caching

Cache repeated read traffic close to users, with TTL and stale-while-revalidate controls when you need them.

📖

Read Replicas

Route selected reads to replicas instead of pretending every query should behave the same way.

🌍

Global Routing

Send clients to the nearest edge while keeping pools near the database when relay makes more sense.

🔒

Custom Domains

Use your own hostname and let PgBeam handle the certificate plumbing.

📊

Query Insights

Pull metrics, usage, activity, and query insights from the same control plane the dashboard uses.

Prerequisites

Before you begin, you need:

A PostgreSQL database reachable from the internet
The connection details for that database: host, port, username, password, and database name

Setup

Create an account

Sign up at dash.pgbeam.com. New accounts start on the Starter plan, which includes a 14-day trial. A default organization is created for you automatically.

Create a project

Create a project in the dashboard. Each project gets a hostname like abc.aws.pgbeam.app. That hostname is what your application will connect to.

Add your origin database

Use Add Database in the dashboard and enter the connection details for the database PgBeam should forward traffic to.

Field	Description	Example
Host	Origin database hostname	`db.example.com`
Port	PostgreSQL port	`5432`
Database name	Database to connect to	`mydb`
SSL mode	TLS mode used for the upstream connection	`verify-full`

verify-full is the right default for most managed databases. Only relax it if your provider does not give you a certificate chain your client can verify.

PgBeam stores the origin database credentials you enter here. Application user credentials are still checked by the origin database at connection time.

Replace the host in your connection string

.env

# Before
DATABASE_URL=postgresql://user:pass@db.example.com:5432/mydb

# After
DATABASE_URL=postgresql://user:pass@abc.aws.pgbeam.app:5432/mydb

Keep the username, password, port, and database name. The hostname is the only required change.

Run a query

At this point your app should already be talking through PgBeam:

const users = await prisma.user.findMany();

const users = await db.select().from(usersTable);

rows, err := pool.Query(ctx, "SELECT * FROM users")

cur.execute("SELECT * FROM users")
users = cur.fetchall()

If that works, the plumbing is done. Pooling and observability are already in the path. Caching is available when you are ready to turn it on.

Turn on caching later, not first

Caching starts off disabled for new databases. That is the safer default. Once traffic is flowing, you can enable it for stable reads that benefit from reuse.

Open your database in the dashboard and go to Cache Rules. PgBeam tracks query shapes automatically, so you can enable caching on the high-frequency reads that are worth it.

/* @pgbeam:cache maxAge=300 swr=60 */ SELECT * FROM products WHERE active = true;
/* @pgbeam:cache noCache */ SELECT NOW();

SET pgbeam.cache = on;
SET pgbeam.debug = on;
SELECT * FROM users WHERE id = 1;

See the Caching guide for TTL, SWR, bypass rules, and cache annotations.

Supported clients

PgBeam works with any PostgreSQL-compatible client. The docs include concrete setup guides for the tools people ask about most often:

Language	Drivers and ORMs
TypeScript	Prisma, Drizzle, Sequelize, TypeORM
Python	psycopg, SQLAlchemy
Go	pgx
Java	JDBC, HikariCP, Spring Boot

Prefer the terminal?

The PgBeam CLI covers the same setup flow:

Quick CLI setup

curl -fsSL https://pgbeam.com/install | sh
pgbeam auth login
pgbeam projects create --name my-project
pgbeam db add --host db.example.com --port 5432 --database mydb --ssl-mode verify-full
pgbeam env pull