Managed Postgres Terraform 参考文档

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

此资源目前处于 alpha 阶段，其行为可能会在未来的提供商版本中发生变化。它随常规提供商 build 一同发布。本文档记录的是提供商版本 v3.21.0 及更高版本，这些版本更改了凭据的管理方式；更早版本的行为有所不同，并且截至 2026 年 7 月 31 日已无法再正常工作。详情请参阅提供商发行版。

请在 2026 年 7 月 31 日之前升级到提供商 v3.21.0自 2026 年 7 月 31 日 起，Managed Postgres API 不再在响应中返回超级用户密码和 connection string；只有在创建 service 或重置其密码时才会返回凭据。提供商版本 v3.21.0 及更高版本 在此变更前后的行为完全一致。较旧的提供商版本依赖 API 回显凭据：截至 2026 年 7 月 31 日，这些版本将不再填充 connection_string，而且在未声明 password 的情况下创建的 service 虽然会成功，但系统生成的密码不会被记录到任何地方。请在 2026 年 7 月 31 日之前完成升级。使用 v3.21.0 首次执行 plan 或 apply 时，您的 Terraform 状态会自动迁移。如果您的任何 services 依赖 server 生成的密码 (即配置中没有 password) ，请先使用 terraform state pull 将其取回并显式声明，因为 v3.21.0 要求标准 service 必须提供 password 或 password_wo。

提供商设置

将 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 属性 (已在 v3.21.0 中移除) ：请使用 hostname、port、username 以及你声明的密码来构建连接 URI，例如 postgres://${username}:${password}@${hostname}:${port}/postgres?sslmode=require。

The password 会以明文形式存储在你的 Terraform 状态中。请相应保护好状态文件，例如使用启用静态加密的远程后端，或者使用 password_wo 以使密码完全不进入状态。

创建服务

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

导入现有服务

现有的 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 {} 块。

开始使用

功能

基准测试

定价

ClickHouse 集成

迁移

监控

常见问题

提供商设置

资源概览

创建服务

高可用

只读副本

时间点恢复

数据源

导入现有服务

不支持的操作

​提供商设置

​资源概览

​创建服务

​高可用

​只读副本

​时间点恢复

​数据源

​导入现有服务

​不支持的操作

提供商设置

资源概览

创建服务

高可用

只读副本

时间点恢复

数据源

导入现有服务

不支持的操作