--- title: "Terraform" 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 Terraform and the pgbeam provider." canonical: "https://pgbeam.com/docs/terraform" last-updated: "2026-09-14T19:37:21.000Z" --- # Terraform > 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 Terraform and the pgbeam provider. URL: https://pgbeam.com/docs/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, webhook endpoints, self host enrollments, and honeytokens. ## Setup ## Configure the provider The Terraform provider is coming soon. Registry publishing is on the roadmap. ## Configure credentials Set your PgBeam API key via provider config or environment variable: ## Create a project ## Deploy Terraform creates the PgBeam project and its primary database atomically. The `proxy_host` 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. ## pgbeam_project Manages a PgBeam project with a primary database. **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 ` ## pgbeam_database Manages an upstream database connection within a PgBeam project. **Computed:** `connection_string`, `created_at`, `updated_at` **Import:** `terraform import pgbeam_database.example /` ## pgbeam_replica Manages a read replica for a PgBeam database. Replicas are immutable; any property change triggers replacement. **Computed:** `created_at`, `updated_at` **Import:** `terraform import pgbeam_replica.example /` ## pgbeam_custom_domain Manages a custom domain for a PgBeam project. CustomDomains are immutable; any property change triggers replacement. **Computed:** `verified`, `verified_at`, `tls_cert_expiry`, `dns_verification_token`, `dns_instructions`, `created_at`, `updated_at` **Import:** `terraform import pgbeam_custom_domain.example /` ## pgbeam_cache_rule Manages a per-query cache rule. Deletion disables caching (soft-delete). **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 //` ## pgbeam_spend_limit Manages the monthly spend limit for an organization. **Computed:** `org_id`, `plan`, `billing_provider`, `subscription_status`, `current_period_end`, `enabled`, `custom_pricing`, `spend_capped`, `spend_capped_at`, `limits`, `created_at`, `updated_at` **Import:** `terraform import pgbeam_spend_limit.example ` ## 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). **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 /` ## 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. **Computed:** `created_at`, `updated_at` **Import:** `terraform import pgbeam_policy_profile.example /` ## 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. **Computed:** `created_at`, `updated_at` **Import:** `terraform import pgbeam_webhook_endpoint.example /` ## pgbeam_self_host_enrollment 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. **Computed:** `created_by`, `created_at`, `last_seen_at`, `revoked_at`, `token` **Import:** `terraform import pgbeam_self_host_enrollment.example /` ## pgbeam_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. **Computed:** `created_at`, `updated_at` **Import:** `terraform import pgbeam_honeytoken.example /` ## Configuration Setting Source Description `api_key` Provider block API key (sensitive, recommended: use a variable) `base_url` Provider block 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: provider block > environment variables. ## Replacement vs update Some property changes trigger resource replacement (destroy + create) rather than in-place updates: Resource Replacement triggers Project `org_id`, `cloud`, `self_hosted` Database `project_id` Replica Any property change (immutable) CustomDomain Any property change (immutable) CacheRule `project_id`, `database_id`, `query_hash` SpendLimit `org_id` AgentCredential `project_id`, `policy_profile_id`, `name`, `principal_type`, `expires_at` PolicyProfile `project_id` WebhookEndpoint `project_id` SelfHostEnrollment Any property change (immutable) Honeytoken `project_id` ## 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