Pulumi

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

Setup

pulumi config set pgbeam:apiKey --secret pgb_your_api_key

PGBEAM_API_KEY=pgb_your_api_key

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

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

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;

pulumi up

Resources

Project

Manages a PgBeam project with a primary database.

const res = new pgbeam.Project("example", {
  orgId: "org_abc123",
  name: "my-app",
  description: "Production database proxy",
  tags: ["production", "us-east-1"],
  allowedCidrs: ["203.0.113.0/24", "198.51.100.10/32"],
  defaultPolicyProfileId: "pol_01h455vb4pex5vsknk084sn02q",
  agentsDisabled: false,
  status: "active",
});

Outputs: proxyHost, queriesPerSecond, burstSize, maxConnections, databaseCount, activeConnections, createdAt, updatedAt, primaryDatabaseId

Database

Manages an upstream database connection within a PgBeam project.

const res = new pgbeam.Database("example", {
  projectId: "prj_01h455vb4pex5vsknk084sn02q",
  host: "db.example.com",
  port: 5432,
  name: "mydb",
  username: "pgbeam",
  sslMode: "require",
  role: "primary",
  poolRegion: "us-east-1",
  queryTimeoutMs: 0,
  autoReadRouting: false,
  cacheConfig: {
    enabled: true,
    ttlSeconds: 60,
    maxEntries: 10000,
    swrSeconds: 30,
  },
  poolConfig: {
    poolSize: 20,
    minPoolSize: 5,
    poolMode: "transaction",
    maxActive: 200,
  },
  password: secret.value,
});

Outputs: connectionString, createdAt, updatedAt

Replica

Manages a read replica for a PgBeam database.

Replicas are immutable. Any property change triggers replacement.

const res = new pgbeam.Replica("example", {
  databaseId: "db_01h455vb4pex5vsknk084sn02q",
  host: "replica.db.example.com",
  port: 5432,
  sslMode: "require",
});

Outputs: createdAt, updatedAt

CustomDomain

Manages a custom domain for a PgBeam project.

CustomDomains are immutable. Any property change triggers replacement.

const res = new pgbeam.CustomDomain("example", {
  projectId: "prj_01h455vb4pex5vsknk084sn02q",
  domain: "db.example.com",
});

Outputs: verified, verifiedAt, tlsCertExpiry, dnsVerificationToken, dnsInstructions, createdAt, updatedAt

CacheRule

Manages a per-query cache rule. Deletion disables caching (soft-delete).

const res = new pgbeam.CacheRule("example", {
  projectId: "prj_01h455vb4pex5vsknk084sn02q",
  databaseId: "db_01h455vb4pex5vsknk084sn02q",
  queryHash: "a1b2c3d4e5f60718",
  cacheEnabled: true,
  cacheTtlSeconds: 300,
  cacheSwrSeconds: 60,
});

Outputs: queryHash, normalizedSql, queryType, callCount, avgLatencyMs, p95LatencyMs, avgResponseBytes, stabilityRate, recommendation, firstSeenAt, lastSeenAt

SpendLimit

Manages the monthly spend limit for an organization.

const res = new pgbeam.SpendLimit("example", {
  orgId: "org_abc123",
  spendLimit: 500,
});

Outputs: orgId, plan, billingProvider, subscriptionStatus, currentPeriodEnd, enabled, customPricing, limits, createdAt, updatedAt

AgentCredential

Manages a scoped agent credential (a PgBeam-issued Postgres login plus a hosted MCP token) for an AI agent. The connection string and MCP token are one-time secrets returned only at creation and exposed as sensitive computed outputs; they cannot be retrieved again. To rotate the secrets, taint/replace the resource (or use the rotate endpoint out of band).

const res = new pgbeam.AgentCredential("example", {
  projectId: "prj_01h455vb4pex5vsknk084sn02q",
  policyProfileId: "pol_01h455vb4pex5vsknk084sn02q",
  name: "Claude Code (analytics)",
  status: "active",
  principalType: "agent",
  expiresAt: "...",
});

Outputs: pgUsername, authMethod, lastUsedAt, createdAt, updatedAt, connectionString, mcpUrl, mcpToken

PolicyProfile

Manages a policy profile: a named bundle of agent-gateway enforcement rules (access mode, table allow/deny lists, statement-kind rules, PII masking rules, per-relation row filters, query/egress budgets, write mode, approvals, and migration safety) attached to agent credentials and enforced in the PG wire protocol. Nested-list fields (masking_rules, row_filters) and the nested statement_rules object are expressed as structured config.

const res = new pgbeam.PolicyProfile("example", {
  projectId: "prj_01h455vb4pex5vsknk084sn02q",
  name: "Read-only analytics",
  accessMode: "read_only",
  statementRules: {
    allow: ["..."],
    deny: ["..."],
  },
  tableAllowlist: ["..."],
  tableDenylist: ["..."],
  maskingRules: ["..."],
  budgetQueriesPerHour: 0,
  budgetQueriesPerDay: 0,
  maxRows: 0,
  statementTimeoutMs: 0,
  rowFilters: ["..."],
  writeMode: "normal",
  approvalMode: "off",
  approvalAutoMaxRows: 0,
  approvalTimeoutSeconds: 300,
  migrationSafety: "off",
  egressBytesPerDay: 0,
});

Outputs: createdAt, updatedAt

WebhookEndpoint

Manages a webhook endpoint that receives project audit and anomaly event deliveries. The signing secret is write-only and never returned by the API.

const res = new pgbeam.WebhookEndpoint("example", {
  projectId: "...",
  url: "https://example.com/hooks/pgbeam",
  format: "json",
  eventTypes: ["..."],
  enabled: true,
  description: "...",
  secret: secret.value,
});

Outputs: createdAt, updatedAt

Configuration

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:

Further reading

• Connection Pooling: pool modes and sizing
• Caching: query caching and SWR
• Read Replicas: replica routing
• Custom Domains: DNS setup and verification
• API Keys: managing API credentials
• Plans: plan limits and pricing