---
title: "Getting Started"
description: "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."
canonical: "https://pgbeam.com/docs"
last-updated: "2026-10-29T19:01:20.000Z"
---

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

URL: https://pgbeam.com/docs

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 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](/docs/quickstart).

### Connect an agent

- [Quickstart](/docs/quickstart): Give an agent safe, read-only access in two minutes.
- [Hosted MCP](/docs/mcp): Paste one URL into Claude Code, Cursor, or any MCP client. Ten tools: policy-enforced briefing, query, validate_sql, list_tables, describe_table, explain, schema_catalog, and my_permissions, plus search_docs and read_doc.
- [Connection string](/docs/connection-string): A scoped Postgres URL for any driver, ORM, or agent framework. Enforced from the first query.
- [How it works](/docs/how-it-works): Enforcement in the wire protocol, between the agent and your database.

### The policy you control

- [Read-only enforcement](/docs/read-only): Block every write and DDL. Reads pass, writes are rejected at the wire.
- [Allowlists](/docs/allowlists): Allow the exact schemas and tables the agent should touch.
- [PII masking](/docs/masking): Redact, null, or hash sensitive columns in flight. The agent never sees raw values.
- [Query budgets](/docs/budgets): Cap queries per window and rows per result. Runaway loops hit a ceiling.
- [Kill-switch](/docs/kill-switch): Stop one agent or every agent instantly. No credential rotation.
- [Audit log](/docs/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](/docs/pooling): Absorb the connections agents leak without wiring PgBouncer into every environment.
- [Query Caching](/docs/cache): Absorb the questions agents re-ask, with TTL and stale-while-revalidate controls.
- [Read Replicas](/docs/replicas): Route selected reads to replicas instead of treating every query the same.

## How do you 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](https://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

```bash title=".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:

**Prisma**

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

**Drizzle**

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

**pgx (Go)**

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

**psycopg (Python)**

```python
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.

## When should you turn on caching?

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.

{/* prettier-ignore */}

**Dashboard**

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.

**SQL**

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

**Session override**

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

See the [Caching guide](/docs/cache) for TTL, SWR, bypass rules, and cache annotations.

## Which clients are supported?

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](/docs/prisma), [Drizzle](/docs/drizzle), Sequelize, TypeORM |
| Python     | [psycopg](/docs/psycopg), SQLAlchemy                                 |
| Go         | [pgx](/docs/pgx)                                                     |
| Java       | [JDBC](/docs/jdbc), HikariCP, Spring Boot                            |

## Prefer the terminal?

The [PgBeam CLI](/docs/cli) covers the same setup flow:

```bash title="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 --name mydb --ssl-mode verify-full
pgbeam env pull
```

## Where should you go next?

- [Connection Guides](/docs/prisma): Framework-specific setup instructions and pool sizing guidance.
- [Caching](/docs/cache): Learn when cache helps, when it bypasses, and how to turn it on safely.
- [CLI Reference](/docs/cli): Manage PgBeam from the terminal and script the control plane.
- [API Reference](/docs/api): Call the same REST API used by the dashboard and generated SDK.
- [Routing & Regions](/docs/routing): Understand routing, relay, pooling, and failure behavior.