Pulumi

Manage PgBeam projects, databases, replicas, domains, and cache rules as infrastructure using Pulumi and the @pgbeam/pulumi package.

Manage your PgBeam infrastructure as code with Pulumi. The @pgbeam/pulumi package provides native Pulumi resources for projects, databases, replicas, custom domains, cache rules, and spend limits.

Setup

Install the package

npm install @pgbeam/pulumi @pulumi/pulumi

pnpm add @pgbeam/pulumi @pulumi/pulumi

yarn add @pgbeam/pulumi @pulumi/pulumi

Configure credentials

Set your PgBeam API key via Pulumi config or environment variable:

pulumi config set pgbeam:apiKey --secret pgb_your_api_key

.env

PGBEAM_API_KEY=pgb_your_api_key

index.ts

import * as pgbeam from "@pgbeam/pulumi";

pgbeam.configure({ apiKey: "pgb_your_api_key" });

Create a project

index.ts

import * as pgbeam from "@pgbeam/pulumi";
import * as pulumi from "@pulumi/pulumi";

const config = new pulumi.Config();

const project = new pgbeam.Project("my-app", {
  orgId: config.require("orgId"),
  name: "my-app",
  database: {
    host: "my-rds.us-east-1.rds.amazonaws.com",
    port: 5432,
    name: "mydb",
    username: "pgbeam",
    password: config.requireSecret("dbPassword"),
  },
});

export const proxyHost = project.proxyHost;

Deploy

pulumi up

Pulumi creates the PgBeam project and its primary database atomically. The proxyHost output gives you the PgBeam proxy endpoint to use in your application connection string.

Resources

Project

The top-level resource. Each project gets a unique proxy hostname and is created with its primary upstream database.

const project = new pgbeam.Project("prod", {
  orgId: "org_abc123",
  name: "production",
  cloud: "aws",
  queriesPerSecond: 1000,
  burstSize: 200,
  maxConnections: 500,
  database: {
    host: "primary.us-east-1.rds.amazonaws.com",
    port: 5432,
    name: "mydb",
    username: "pgbeam",
    password: secret.value,
    sslMode: "require",
    poolConfig: {
      poolSize: 20,
      minPoolSize: 5,
      poolMode: "transaction",
    },
    cacheConfig: {
      enabled: true,
      ttlSeconds: 60,
      maxEntries: 10000,
      swrSeconds: 30,
    },
  },
});

Outputs: proxyHost, status, databaseCount, activeConnections, primaryDatabaseId, createdAt, updatedAt

Database

Add additional upstream databases to a project. Useful for read replicas or multi-database setups.

const readDb = new pgbeam.Database("read-replica", {
  projectId: project.id,
  host: "replica.us-east-1.rds.amazonaws.com",
  port: 5432,
  name: "mydb",
  username: "pgbeam",
  password: secret.value,
  role: "replica",
  poolConfig: {
    poolSize: 20,
    minPoolSize: 5,
    poolMode: "transaction",
  },
});

Outputs: connectionString, role, sslMode, cacheConfig, poolConfig

Replica

Register a read replica endpoint under a database. PgBeam routes read queries to replicas automatically based on proximity.

Replicas are immutable — any property change triggers replacement.

const replica = new pgbeam.Replica("us-west", {
  databaseId: readDb.id,
  host: "replica.us-west-2.rds.amazonaws.com",
  port: 5432,
  sslMode: "require",
});

CustomDomain

Attach a custom domain to a project. Requires the Scale or Enterprise plan.

const domain = new pgbeam.CustomDomain("prod-domain", {
  projectId: project.id,
  domain: "db.example.com",
});

export const cnameTarget = domain.dnsInstructions.apply(
  (d) => d?.cnameTarget,
);

After creation, configure DNS records according to the returned dnsInstructions, then verify:

domain.id.apply(async (id) => {
  const result = await pgbeam.verifyCustomDomain(project.id, id);
  console.log("Verified:", result.verified);
});

CacheRule

Override per-query cache settings for a specific query shape.

const rule = new pgbeam.CacheRule("hot-query", {
  projectId: project.id,
  databaseId: readDb.id,
  queryHash: "a1b2c3d4e5f67890",
  cacheEnabled: true,
  cacheTtlSeconds: 300,
  cacheSwrSeconds: 60,
});

Outputs: normalizedSql, queryType, callCount, avgLatencyMs, recommendation

Find query hashes in the PgBeam dashboard under the Cache Rules tab, or via the API's listCacheRules endpoint.

SpendLimit

Set a monthly spending cap for an organization.

const limit = new pgbeam.SpendLimit("prod-limit", {
  orgId: "org_abc123",
  spendLimit: 500,
});

When the limit is reached, the organization's projects are suspended until the next billing period. Removing this resource resets the limit (no cap).

Configuration

Setting	Source	Description
`pgbeam:apiKey`	Pulumi config	API key (recommended: use `--secret`)
`pgbeam:baseUrl`	Pulumi config	API base URL (default: `https://api.pgbeam.com`)
`PGBEAM_API_KEY`	Environment	Fallback API key
`PGBEAM_API_URL`	Environment	Fallback base URL

Config resolution order: configure() call > Pulumi stack config > environment variables.

Replacement vs update

Some property changes trigger resource replacement (delete + create) rather than in-place updates:

Resource	Replacement triggers
Project	`orgId`, `cloud`
Database	`projectId`
Replica	Any property change (immutable)
CustomDomain	Any property change (immutable)
CacheRule	`projectId`, `databaseId`, `queryHash`
SpendLimit	`orgId`