Terraform

Manage your PgBeam infrastructure as code with Terraform. The pgbeam provider offers native resources for projects, databases, replicas, custom domains, cache rules, spend limits, agent credentials, policy profiles, and webhook endpoints.

Setup

terraform {
  required_providers {
    pgbeam = {
      source  = "pgbeam/pgbeam"
      version = "~> 1.0"
    }
  }
}

provider "pgbeam" {
  api_key = var.pgbeam_api_key  # or set PGBEAM_API_KEY
}

variable "pgbeam_api_key" {
  type      = string
  sensitive = true
}

provider "pgbeam" {
api_key = var.pgbeam_api_key
}

export PGBEAM_API_KEY=pgb_your_api_key

resource "pgbeam_project" "my_app" {
  org_id = "org_abc123"
  name   = "my-app"

  database {
    host     = "my-rds.us-east-1.rds.amazonaws.com"
    port     = 5432
    name     = "mydb"
    username = "pgbeam"
    password = var.db_password
  }
}

output "proxy_host" {
  value = pgbeam_project.my_app.proxy_host
}

terraform apply

Resources

pgbeam_project

Manages a PgBeam project with a primary database.

resource "pgbeam_project" "example" {
  org_id = "org_abc123"
  name = "my-app"
  description = "Production database proxy"
  tags = ["production", "us-east-1"]
  allowed_cidrs = ["203.0.113.0/24", "198.51.100.10/32"]
  default_policy_profile_id = "pol_01h455vb4pex5vsknk084sn02q"
  agents_disabled = false
  status = "active"
}

Computed: proxy_host, queries_per_second, burst_size, max_connections, database_count, active_connections, created_at, updated_at, primary_database_id

Import: terraform import pgbeam_project.example <id>

pgbeam_database

Manages an upstream database connection within a PgBeam project.

resource "pgbeam_database" "example" {
  project_id = "prj_01h455vb4pex5vsknk084sn02q"
  host = "db.example.com"
  port = 5432
  name = "mydb"
  username = "pgbeam"
  ssl_mode = "require"
  role = "primary"
  pool_region = "us-east-1"
  query_timeout_ms = 0
  auto_read_routing = false
  cache_config {
    enabled = true
    ttl_seconds = 60
    max_entries = 10000
    swr_seconds = 30
  }
  pool_config {
    pool_size = 20
    min_pool_size = 5
    pool_mode = "transaction"
    max_active = 200
  }
  password = var.password
}

Computed: connection_string, created_at, updated_at

Import: terraform import pgbeam_database.example <project_id>/<id>

pgbeam_replica

Manages a read replica for a PgBeam database.

Replicas are immutable. Any property change triggers replacement.

resource "pgbeam_replica" "example" {
  database_id = "db_01h455vb4pex5vsknk084sn02q"
  host = "replica.db.example.com"
  port = 5432
  ssl_mode = "require"
}

Computed: created_at, updated_at

Import: terraform import pgbeam_replica.example <database_id>/<id>

pgbeam_custom_domain

Manages a custom domain for a PgBeam project.

CustomDomains are immutable. Any property change triggers replacement.

resource "pgbeam_custom_domain" "example" {
  project_id = "prj_01h455vb4pex5vsknk084sn02q"
  domain = "db.example.com"
}

Computed: verified, verified_at, tls_cert_expiry, dns_verification_token, dns_instructions, created_at, updated_at

Import: terraform import pgbeam_custom_domain.example <project_id>/<id>

pgbeam_cache_rule

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

resource "pgbeam_cache_rule" "example" {
  project_id = "prj_01h455vb4pex5vsknk084sn02q"
  database_id = "db_01h455vb4pex5vsknk084sn02q"
  query_hash = "a1b2c3d4e5f60718"
  cache_enabled = true
  cache_ttl_seconds = 300
  cache_swr_seconds = 60
}

Computed: query_hash, normalized_sql, query_type, call_count, avg_latency_ms, p95_latency_ms, avg_response_bytes, stability_rate, recommendation, first_seen_at, last_seen_at

Import: terraform import pgbeam_cache_rule.example <project_id>/<database_id>/<query_hash>

pgbeam_spend_limit

Manages the monthly spend limit for an organization.

resource "pgbeam_spend_limit" "example" {
  org_id = "org_abc123"
  spend_limit = 500
}

Computed: org_id, plan, billing_provider, subscription_status, current_period_end, enabled, custom_pricing, limits, created_at, updated_at

Import: terraform import pgbeam_spend_limit.example <org_id>

pgbeam_agent_credential

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

resource "pgbeam_agent_credential" "example" {
  project_id = "prj_01h455vb4pex5vsknk084sn02q"
  policy_profile_id = "pol_01h455vb4pex5vsknk084sn02q"
  name = "Claude Code (analytics)"
  status = "active"
  principal_type = "agent"
  expires_at = "..."
}

Computed: pg_username, auth_method, last_used_at, created_at, updated_at, connection_string, mcp_url, mcp_token

Import: terraform import pgbeam_agent_credential.example <project_id>/<id>

pgbeam_policy_profile

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.

resource "pgbeam_policy_profile" "example" {
  project_id = "prj_01h455vb4pex5vsknk084sn02q"
  name = "Read-only analytics"
  access_mode = "read_only"
  statement_rules {
    allow = ["..."]
    deny = ["..."]
  }
  table_allowlist = ["..."]
  table_denylist = ["..."]
  masking_rules = ["..."]
  budget_queries_per_hour = 0
  budget_queries_per_day = 0
  max_rows = 0
  statement_timeout_ms = 0
  row_filters = ["..."]
  write_mode = "normal"
  approval_mode = "off"
  approval_auto_max_rows = 0
  approval_timeout_seconds = 300
  migration_safety = "off"
  egress_bytes_per_day = 0
}

Computed: created_at, updated_at

Import: terraform import pgbeam_policy_profile.example <project_id>/<id>

pgbeam_webhook_endpoint

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

resource "pgbeam_webhook_endpoint" "example" {
  project_id = "..."
  url = "https://example.com/hooks/pgbeam"
  format = "json"
  event_types = ["..."]
  enabled = true
  description = "..."
  secret = var.secret
}

Computed: created_at, updated_at

Import: terraform import pgbeam_webhook_endpoint.example <project_id>/<id>

Configuration

Config resolution order: provider block > environment variables.

Replacement vs update

Some property changes trigger resource replacement (destroy + 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