Skip to content

pulumi.mdx

Latest commit

 

History

History
252 lines (195 loc) · 6.29 KB

pulumi.mdx

File metadata and controls

252 lines (195 loc) · 6.29 KB
title Pulumi
icon Blocks
tag TypeScript
description Manage PgBeam projects, databases, replicas, custom domains, cache rules, and spend limits 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

<Tabs items={["npm", "pnpm", "yarn"]}> bash npm install @pgbeam/pulumi @pulumi/pulumi bash pnpm add @pgbeam/pulumi @pulumi/pulumi bash yarn add @pgbeam/pulumi @pulumi/pulumi

Configure credentials

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

<Tabs items={["Pulumi config", "Environment variable", "Programmatic"]}> 

pulumi config set pgbeam:apiKey --secret pgb_your_api_key
```bash title=".env" PGBEAM_API_KEY=pgb_your_api_key ``` ```ts title="index.ts" import * as pgbeam from "@pgbeam/pulumi";

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

</Tab>
</Tabs>

</Step>
<Step>

### Create a project

```ts title="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

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: [[object Object], [object Object]],
  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

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

Further reading