---
title: "Pulumi"
description: "Manage PgBeam projects, databases, replicas, custom domains, cache rules, spend limits, agent credentials, policy profiles, webhook endpoints, self host enrollments, and honeytokens as infrastructure using Pulumi and the @pgbeam/pulumi package."
canonical: "https://pgbeam.com/docs/pulumi"
last-updated: "2026-09-14T19:37:21.000Z"
---

# Pulumi

> Manage PgBeam projects, databases, replicas, custom domains, cache rules, spend limits, agent credentials, policy profiles, webhook endpoints, self host enrollments, and honeytokens as infrastructure using Pulumi and the @pgbeam/pulumi package.

URL: https://pgbeam.com/docs/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, webhook endpoints, self host enrollments, and honeytokens.

## Setup

## Install the package

## Configure credentials

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

## Create a project

## Deploy

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

**Approval and anomaly rules are not yet managed as code.** Policy profiles
and honeytokens are managed resources, so the enforcement rules and the decoys
live in your reviewed IaC flow and are covered by drift detection. Approval
rules and anomaly rules are not: the API exposes them only as events to review
after the fact (approve/reject, ack/resolve), so there is nothing to declare
yet. Those two still live outside IaC.

## Project

Manages a PgBeam project with a primary database.

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

## Database

Manages an upstream database connection within a PgBeam project.

**Outputs:** `connectionString`, `createdAt`, `updatedAt`

## Replica

Manages a read replica for a PgBeam database.

Replicas are immutable; any property change triggers replacement.

**Outputs:** `createdAt`, `updatedAt`

## CustomDomain

Manages a custom domain for a PgBeam project.

CustomDomains are immutable; any property change triggers replacement.

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

## CacheRule

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

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

## SpendLimit

Manages the monthly spend limit for an organization.

**Outputs:** `orgId`, `plan`, `billingProvider`, `subscriptionStatus`, `currentPeriodEnd`, `enabled`, `customPricing`, `spendCapped`, `spendCappedAt`, `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).

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

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

**Outputs:** `createdAt`, `updatedAt`

## SelfHostEnrollment

Manages a self-host (BYOC) enrollment: a token a self-hosted proxy uses to authenticate to the control plane's config/audit stream. The token is a one-time secret returned only at creation and exposed as a sensitive computed output; it cannot be retrieved again. To rotate the token, replace the resource. Deletion revokes the enrollment.

SelfHostEnrollments are immutable; any property change triggers replacement.

**Outputs:** `createdBy`, `createdAt`, `lastSeenAt`, `revokedAt`, `token`

## Honeytoken

Manages a honeytoken: a decoy (canary) relation that no legitimate query should ever touch. Any agent statement referencing it is blocked and recorded as a canary\_tripped audit event; the kill action additionally disables the tripping credential via the kill-switch. The relation does not have to exist in the upstream database: enforcement is by name, in the wire protocol, before the statement reaches Postgres.

**Outputs:** `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`, `selfHosted`

Database

`projectId`

Replica

Any property change (immutable)

CustomDomain

Any property change (immutable)

CacheRule

`projectId`, `databaseId`, `queryHash`

SpendLimit

`orgId`

AgentCredential

`projectId`, `policyProfileId`, `name`, `principalType`, `expiresAt`

PolicyProfile

`projectId`

WebhookEndpoint

`projectId`

SelfHostEnrollment

Any property change (immutable)

Honeytoken

`projectId`

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