Terraform

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

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

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