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

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:

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: build connection URIs from hostname, port, username, and the password you declare, for example postgres://${username}:${password}@${hostname}:${port}/postgres?sslmode=require.

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