Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

ClickHouse Managed Postgres Terraform 参考文档

View as MarkdownEdit this pageReport an issueSet up docs MCP
Beta

可通过 ClickHouse Terraform 提供商 中的 clickhouse_postgres_service 资源创建和管理 ClickHouse Managed Postgres 服务。本文介绍该资源及其配套数据源的 提供商 设置与配置示例。

提供商设置

将 ClickHouse 提供商添加到 Terraform 配置中：

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
}

有关如何创建供提供商使用的 API 密钥，请参阅管理 API 密钥。

资源概览

clickhouse_postgres_service 资源具有以下参数：

参数 必需 描述
name 是 服务的易读名称。不可变——修改后会销毁并重新创建该服务。
cloud_provider 标准创建时必填 托管该实例的云提供商。目前仅支持 aws。对于只读副本或时间点恢复，请省略 (将从源服务继承) 。
region 标准创建时必填 云区域 (例如 us-east-1) 。对于只读副本或时间点恢复，请省略 (将从源服务继承) 。
size 标准创建时必填 实例规格 (VM SKU) ，例如 m6gd.large。支持原地调整大小。对于时间点恢复，请省略 (恢复后的实例将使用备份时的规格启动) 。
postgres_version 否 Postgres 主版本 (例如 18) 。更改主版本会销毁并重新创建该服务。
ha_type 否 高可用模式：none、async 或 sync。请参见高可用。
password 标准创建时必填，除非设置了 password_wo 由你的配置管理的超级用户密码。Terraform 不会从 API 中将其读回。会存储在 (敏感) 状态中。对于只读副本，请省略 (将继承)；对于时间点恢复，也请省略 (将保留源备份中的密码) 。
password_wo 标准创建时必填，除非设置了 password 只写超级用户密码：会应用到服务，但绝不会存储在状态中。需要 password_wo_version；需要 Terraform 1.11 或更高版本。
password_wo_version 与 password_wo 一起使用 password_wo 的版本号。更改它可轮换到当前的 password_wo 值。
pg_config 否 以键值映射形式提供的 Postgres 服务器参数。
pgbouncer_config 否 以键值映射形式提供的 PgBouncer 连接池器参数。
tags 否 以键值映射形式提供的资源标签。
read_replica_of 否 要复制的主服务 ID。请参见只读副本。与 restore_to_point_in_time 互斥。
restore_to_point_in_time 否 通过将另一个服务恢复到某个时间点来创建该服务。请参见时间点恢复。与 read_replica_of 互斥。

以下属性为只读，并由 ClickHouse Cloud 在创建后填充：id、state、created_at、is_primary、hostname、port 和 username。不存在 connection_string 属性：请使用 hostname、port、username 以及你声明的密码来构建连接 URI，例如 postgres://${username}:${password}@${hostname}:${port}/postgres?sslmode=require。

创建服务

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"
  }
}

标准 service 必须声明 password 或 password_wo。其值必须至少为 12 个字符，且至少包含一个小写字母、一个大写字母和一个数字。password_wo (连同 password_wo_version) 同样适用这些密码规则，但绝不会存储在状态中；如需轮换，请更改 password_wo_version。由于 API 不会返回凭据，Terraform 必须始终是密码的唯一写入方：如果在 Terraform 之外 (控制台或 API) 轮换了密码，Terraform 不会检测到，而下一次由 Terraform 驱动的轮换会重新写回已声明的值。

高可用

ha_type 参数用于控制待机副本的数量：

ha_type 待机节点 复制
none 无 (仅主节点) —
async 1 个待机节点 异步 — 写入提交时无需等待待机节点
sync 2 个待机节点 同步 — 主节点会等待至少一个待机节点的确认

ha_type 在创建后仍可修改；更改该值会触发 HA 切换。详见 高可用。

只读副本

要创建流式只读副本，请将 read_replica_of 设置为主服务的 id。副本会继承主服务的 cloud_provider、region、postgres_version 和超级用户——请省略这些字段 (以及 password) ：

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

详情请参阅只读副本。

时间点恢复

设置 restore_to_point_in_time，即可通过将另一项服务的备份恢复到某个时间点来创建服务。cloud_provider、region 和 postgres_version 继承自源服务 (请省略这些字段) ；size 和 ha_type 也必须省略：

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"
  }
}

整个配置块仅在创建时使用：更改 source_id 或 restore_target，或删除此配置块，都会销毁并重新创建该服务。详情请参阅备份与恢复。

数据源

三个配套的数据源可帮助您查找现有服务：

# 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
}

导入现有服务

现有的 ClickHouse Managed Postgres 服务可以通过服务 ID 导入到 Terraform 状态中：

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

导入不会恢复密码 (API 不会返回该密码) 。导入后，首次执行 apply 时，服务会切换为你在配置中声明的 password 或 password_wo。

不支持的操作

以下内容刻意未纳入资源 schema：

  • 运维命令 (restart、promote、switchover) 。
  • IP 允许列表、专用终结点、备份配置、维护窗口、客户管理的加密密钥，以及 BYOC。
  • 不支持可配置的生命周期超时设置——不存在 timeouts {} 块。
Navigation