Getting Started

Give an AI agent safe, scoped, audited access to your Postgres. Enforcement is in the wire protocol, so it works with any Postgres and no code changes.

PgBeam is the safe Postgres gateway for AI agents. You hand an agent a scoped connection string or a hosted MCP endpoint instead of a superuser one, and PgBeam enforces what it can do: read-only access, table and column allowlists, PII masking, query budgets, and a kill-switch. Every query is audited. Enforcement happens at the PostgreSQL wire protocol, so it works with RDS, Aurora, self-hosted, or any managed Postgres, with no extension to install and no change to your schema.

Two minutes to safe agent access

Issue a scoped credential, attach a read-only policy, and point your agent at it. No SDK, no protocol shim, no application rewrite. Start with the Quickstart.

Connect an agent

🚀

Quickstart

Give an agent safe, read-only access in two minutes.

🔌

Hosted MCP

Paste one URL into Claude Code, Cursor, or any MCP client. Policy-enforced query, list_tables, describe_table, and explain tools.

🔗

Connection string

A scoped Postgres URL for any driver, ORM, or agent framework. Enforced from the first query.

⚙️

How it works

Enforcement in the wire protocol, between the agent and your database.

The policy you control

👁️

Read-only enforcement

Block every write and DDL. Reads pass, writes are rejected at the wire.

✅

Allowlists

Allow the exact schemas, tables, and columns the agent should touch.

🕶️

PII masking

Redact, null, or hash sensitive columns in flight. The agent never sees raw values.

⏱️

Query budgets

Cap queries per window and rows per result. Runaway loops hit a ceiling.

🛑

Kill-switch

Stop one agent or every agent instantly. No credential rotation.

📜

Audit log

Every statement recorded with its decision, rows, bytes, and latency.

A real proxy underneath

The gateway runs on a globally distributed wire-protocol proxy. Agent traffic gets connection pooling, query caching, replica routing, and edge latency for free. These are supporting features now, not the headline.

🔗

Connection Pooling

Absorb the connections agents leak without wiring PgBouncer into every environment.

⚡

Query Caching

Absorb the questions agents re-ask, with TTL and stale-while-revalidate controls.

📖

Read Replicas

Route selected reads to replicas instead of treating every query the same.

Connect your own application

The pages above cover giving an agent safe access. PgBeam also sits in front of your own application for pooling, caching, replicas, and routing. The setup below is that path: point your app at a PgBeam hostname and keep speaking normal PostgreSQL. Your application's passthrough connection is never subject to agent policies.

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.proxy.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.proxy.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.

active = true; /* @pgbeam:cache noCache */ SELECT NOW(); ```
</Tab>

<Tab value="Session override">
  ```sql
  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