> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ClickHouse Managed Postgres Terraform reference

> Reference for managing ClickHouse Managed Postgres services with the ClickHouse Terraform provider.

export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
  if (link) {
    return <a href={link} target="_blank" rel="noopener noreferrer" className="betaBadge" onClick={galaxyTrack && galaxyEvent ? galaxyOnClick(galaxyEvent) : undefined}>
                <span>Beta</span>
            </a>;
  }
  return <a href="https://clickhouse.com/docs/reference/settings/beta-and-experimental-features#beta-features" className="betaBadge">
            <span>Beta feature</span>
        </a>;
};

<BetaBadge link="https://clickhouse.com/cloud/postgres" galaxyTrack={true} galaxyEvent="docs.managed-postgres.terraform-beta" />

ClickHouse Managed Postgres services can be created and managed using the `clickhouse_postgres_service` resource in the [ClickHouse Terraform provider](https://registry.terraform.io/providers/ClickHouse/clickhouse/latest/docs/resources/postgres_service). This page covers provider setup and configuration examples for the resource and its companion data sources.

<Note>
  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. See the [provider releases](https://github.com/ClickHouse/terraform-provider-clickhouse/releases) for details.
</Note>

<h2 id="provider-setup">
  Provider setup
</h2>

Add the ClickHouse provider to your Terraform configuration:

```hcl theme={null}
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](/products/cloud/features/admin-features/api/openapi) for instructions on creating an API key to use with the provider.

<h2 id="resource-overview">
  Resource overview
</h2>

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

<Warning>
  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.
</Warning>

<h2 id="create-a-service">
  Create a service
</h2>

```hcl theme={null}
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.

<h2 id="high-availability">
  High availability
</h2>

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](/products/managed-postgres/high-availability) for details.

<h2 id="read-replicas">
  Read replicas
</h2>

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`):

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

See [Read replicas](/products/managed-postgres/read-replicas) for details.

<h2 id="point-in-time-restore">
  Point-in-time restore
</h2>

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:

```hcl theme={null}
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](/products/managed-postgres/backup-and-restore) for details.

<h2 id="data-sources">
  Data sources
</h2>

Three companion data sources let you look up existing services:

```hcl theme={null}
# 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
}
```

<h2 id="importing-existing-services">
  Importing existing services
</h2>

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

```bash theme={null}
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.

<h2 id="unsupported-operations">
  Unsupported operations
</h2>

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.