Managed Postgres Terraform reference

ClickHouse Managed Postgres services can be created and managed using the clickhouse_postgres_service resource in the ClickHouse Terraform provider. This page covers provider setup and configuration examples for the resource and its companion data sources.

This resource is in alpha and its behavior may change in future provider versions. It ships in the regular provider build. This page documents provider version v3.21.0 and later, which changed how credentials are managed; earlier versions behave differently and as of July 31, 2026 no longer work correctly. See the provider releases for details.

Upgrade to provider v3.21.0 before July 31, 2026As of July 31, 2026, the Managed Postgres API ceased to return the superuser password and connection string in its responses; credentials are returned only when a service is created or its password is reset. Provider versions v3.21.0 and later work identically before and after this change. Older provider versions rely on the API echoing credentials: as of July 31, 2026, they no longer populate connection_string, and a service created without a declared password succeeds while the generated password is never captured anywhere.Upgrade before July 31, 2026. Your state migrates automatically on the first plan or apply with v3.21.0. If any of your services rely on a server-generated password (no password in configuration), recover it first with terraform state pull and declare it, since v3.21.0 requires password or password_wo for a standard service.

Provider setup

Add the ClickHouse provider to your Terraform configuration:

terraform {
  required_providers {
    clickhouse = {
      source  = "ClickHouse/clickhouse"
      version = ">= 3.21.0"
    }
  }
}

provider "clickhouse" {
  organization_id = var.organization_id
  token_key       = var.token_key
  token_secret    = var.token_secret
}

See Managing API keys for instructions on creating an API key to use with the provider.

Resource overview

The clickhouse_postgres_service resource has the following arguments:

Argument	Required	Description
`name`	Yes	Human-readable name for the service. Immutable — changing it destroys and recreates the service.
`cloud_provider`	For a standard create	Cloud provider hosting the instance. Currently only `aws` is supported. Omit for a read replica or point-in-time restore (inherited from the source).
`region`	For a standard create	Cloud region (for example, `us-east-1`). Omit for a read replica or point-in-time restore (inherited from the source).
`size`	For a standard create	Instance size (VM SKU), for example `m6gd.large`. Resizable in place. Omit for a point-in-time restore (the restored instance comes up at the backup’s size).
`postgres_version`	No	Major Postgres version (for example, `18`). Changing the major version destroys and recreates the service.
`ha_type`	No	High-availability mode: `none`, `async`, or `sync`. See High availability.
`password`	For a standard create, unless `password_wo` is set	Superuser password, managed from your configuration. Terraform never reads it back from the API. Stored in (sensitive) state. Omit for a read replica (inherited) or a point-in-time restore (kept from the source backup).
`password_wo`	For a standard create, unless `password` is set	Write-only superuser password: applied to the service but never stored in state. Requires `password_wo_version`; requires Terraform 1.11 or later.
`password_wo_version`	With `password_wo`	Version number for `password_wo`. Change it to rotate to the current `password_wo` value.
`pg_config`	No	Postgres server parameters as a key-value map.
`pgbouncer_config`	No	PgBouncer connection-pooler parameters as a key-value map.
`tags`	No	Resource tags as a key-value map.
`read_replica_of`	No	ID of a primary service to replicate. See Read replicas. Mutually exclusive with `restore_to_point_in_time`.
`restore_to_point_in_time`	No	Create the service by restoring another service to a point in time. See Point-in-time restore. Mutually exclusive with `read_replica_of`.

The following attributes are read-only and populated by ClickHouse Cloud after creation: id, state, created_at, is_primary, hostname, port, and username. There is no connection_string attribute (removed in v3.21.0): build connection URIs from hostname, port, username, and the password you declare, for example postgres://${username}:${password}@${hostname}:${port}/postgres?sslmode=require.

The password is stored in plain text in your Terraform state. Protect your state file accordingly, for example with a remote backend using encryption at rest, or use password_wo to keep the password out of state entirely.

Create a service

resource "clickhouse_postgres_service" "example" {
  name           = "my-postgres"
  cloud_provider = "aws"
  region         = "us-east-1"
  size           = "m6gd.large"
  password       = var.postgres_password

  # High-availability mode — number of standby replicas:
  #   "none"  – primary only, no standby (default)
  #   "async" – 1 standby, asynchronous replication
  #   "sync"  – 2 standbys, synchronous replication
  ha_type = "async"

  tags = {
    environment = "production"
    team        = "data"
  }
}

A standard service must declare password or password_wo. The value must be at least 12 characters with at least one lowercase letter, one uppercase letter, and one digit. password_wo (with password_wo_version) applies the same password rules but is never stored in state; change password_wo_version to rotate. Because the API does not return credentials, Terraform must stay the only writer of the password: a password rotated outside Terraform (console or API) is not detected, and the next Terraform-driven rotation reasserts the declared value.

High availability

The ha_type argument controls the number of standby replicas:

`ha_type`	Standbys	Replication
`none`	None (primary only)	—
`async`	1 standby	Asynchronous — writes commit without waiting for the standby
`sync`	2 standbys	Synchronous — the primary waits for acknowledgement from at least one standby

ha_type is mutable post-create; changing it triggers an HA transition. See High availability for details.

Read replicas

Set read_replica_of to the id of a primary service to create a streaming read replica. A replica inherits the primary’s cloud_provider, region, postgres_version, and superuser — omit those (and password):

resource "clickhouse_postgres_service" "replica" {
  name            = "my-postgres-replica"
  size            = "m6gd.large"
  read_replica_of = clickhouse_postgres_service.example.id
}

See Read replicas for details.

Point-in-time restore

Set restore_to_point_in_time to create a service by restoring another service’s backup to a point in time. cloud_provider, region, and postgres_version are inherited from the source (omit them); size and ha_type must be omitted:

resource "clickhouse_postgres_service" "restored" {
  name = "my-postgres-restored"

  restore_to_point_in_time = {
    source_id      = clickhouse_postgres_service.example.id
    restore_target = "2026-06-01T12:00:00Z"
  }
}

The whole block is create-time only: changing source_id or restore_target, or removing the block, destroys and recreates the service. See Backup and restore for details.

Data sources

Three companion data sources let you look up existing services:

# A single service by ID.
data "clickhouse_postgres_service" "example" {
  id = clickhouse_postgres_service.example.id
}

# All Managed Postgres services in the organization.
data "clickhouse_postgres_services" "all" {}

# The CA certificates for a service, for TLS connections.
data "clickhouse_postgres_service_ca_certificates" "certs" {
  service_id = clickhouse_postgres_service.example.id
}

Importing existing services

Existing Managed Postgres services can be imported into Terraform state using the service ID:

terraform import clickhouse_postgres_service.example xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Import does not recover the password (the API does not return it). After importing, the first apply rotates the service to the password or password_wo declared in your configuration.

Unsupported operations

The following are intentionally absent from the resource schema:

Operational commands (restart, promote, switchover).
IP allowlists, private endpoints, backup configuration, maintenance windows, customer-managed encryption keys, and BYOC.
Configurable lifecycle timeouts — there is no timeouts {} block.

Get started

Features

Benchmarks

Pricing

ClickHouse Integration

Migrations

Monitoring

FAQ

Provider setup

Resource overview

Create a service

High availability

Read replicas

Point-in-time restore

Data sources

Importing existing services

Unsupported operations

​Provider setup

​Resource overview

​Create a service

​High availability

​Read replicas

​Point-in-time restore

​Data sources

​Importing existing services

​Unsupported operations

Provider setup

Resource overview

Create a service

High availability

Read replicas

Point-in-time restore

Data sources

Importing existing services

Unsupported operations