Referência do Terraform para o ClickHouse Managed Postgres

Os serviços do ClickHouse Managed Postgres podem ser criados e gerenciados usando o recurso clickhouse_postgres_service no provider Terraform do ClickHouse. Esta página aborda a configuração do provider e traz exemplos de configuração para o recurso e suas fontes de dados correspondentes.

Adicione o provider ClickHouse na sua configuração do 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
}

Consulte Como gerenciar chaves de API para ver instruções sobre como criar uma chave de API para usar com o provider.

O recurso clickhouse_postgres_service tem os seguintes argumentos:

Os seguintes atributos são somente leitura e são preenchidos pelo ClickHouse Cloud após a criação: id, state, created_at, is_primary, hostname, port e username. Não há atributo connection_string: monte URIs de conexão a partir de hostname, port, username e da senha que você declarar, por exemplo 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"
  }
}

Um serviço padrão deve declarar password ou password_wo. O valor deve ter pelo menos 12 caracteres, incluindo ao menos uma letra minúscula, uma letra maiúscula e um dígito. password_wo (com password_wo_version) aplica as mesmas regras de senha, mas nunca é armazenado no estado; altere password_wo_version para rotacionar a senha. Como a API não retorna credenciais, o Terraform deve continuar sendo o único a gravar a senha: uma senha rotacionada fora do Terraform (Console ou API) não é detectada, e a próxima rotação acionada pelo Terraform reaplica o valor declarado.

O argumento ha_type controla o número de réplicas em standby:

ha_type pode ser alterado após a criação; mudá-lo aciona uma transição de HA. Consulte Alta disponibilidade para mais detalhes.

Defina read_replica_of como o id de um serviço primário para criar uma réplica de leitura via streaming. A réplica herda cloud_provider, region, postgres_version e o superusuário do primário — omita esses campos (e password):

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

Consulte réplicas de leitura para obter mais detalhes.

Defina restore_to_point_in_time para criar um serviço restaurando o backup de outro serviço para um ponto específico no tempo. cloud_provider, region e postgres_version são herdados do serviço de origem (omita-os); size e ha_type devem ser omitidos:

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

O bloco inteiro só pode ser usado na criação: alterar source_id ou restore_target, ou remover o bloco, destrói e recria o serviço. Consulte Backup e restauração para mais detalhes.

Três fontes de dados complementares permitem consultar serviços existentes:

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

Os serviços ClickHouse Managed Postgres existentes podem ser importados para o estado do Terraform usando o ID do serviço:

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

A importação não recupera a senha (a API não a retorna). Após a importação, o primeiro apply faz a rotação do serviço para a password ou password_wo definidos na sua configuração.

Os itens a seguir estão intencionalmente ausentes do schema do recurso:

• Comandos operacionais (restart, promote, switchover).
• Listas de IPs permitidos, endpoints privados, configuração de backup, janelas de manutenção, chaves de criptografia gerenciadas pelo cliente e BYOC.
• Timeouts de ciclo de vida configuráveis — não há bloco timeouts {}.