Skip to content

index.mdx

Latest commit

 

History

History
244 lines (184 loc) · 7.46 KB

index.mdx

File metadata and controls

244 lines (184 loc) · 7.46 KB
title Getting Started
description 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.

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

What changes

# 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

Keep upstream connection pressure under control without wiring PgBouncer into every environment. Cache repeated read traffic close to users, with TTL and stale-while-revalidate controls when you need them. Route selected reads to replicas instead of pretending every query should behave the same way. Send clients to the nearest edge while keeping pools near the database when relay makes more sense. Use your own hostname and let PgBeam handle the certificate plumbing. 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](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.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`    |

<Callout type="info">
  `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.
</Callout>

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

<Tabs items={["Prisma", "Drizzle", "pgx (Go)", "psycopg (Python)"]}>
  <Tab value="Prisma">
    ```ts
    const users = await prisma.user.findMany();
    ```
  </Tab>

  <Tab value="Drizzle">
    ```ts
    const users = await db.select().from(usersTable);
    ```
  </Tab>

  <Tab value="pgx (Go)">
    ```go
    rows, err := pool.Query(ctx, "SELECT * FROM users")
    ```
  </Tab>

  <Tab value="psycopg (Python)">
    ```python
    cur.execute("SELECT * FROM users")
    users = cur.fetchall()
    ```
  </Tab>
</Tabs>

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.

<Tabs items={["Dashboard", "SQL", "Session override"]}> 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 /* @pgbeam:cache maxAge=300 swr=60 */ SELECT * FROM products WHERE active = true; /* @pgbeam:cache noCache */ SELECT NOW(); ``` ```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:

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

Where to go next

Framework-specific setup instructions and pool sizing guidance. Learn when cache helps, when it bypasses, and how to turn it on safely. Manage PgBeam from the terminal and script the control plane. Call the same REST API used by the dashboard and generated SDK. Understand routing, relay, pooling, and failure behavior.