Referência do Terraform para o ClickHouse Managed Postgres

Referência para gerenciar serviços do ClickHouse Managed Postgres com o provider Terraform do ClickHouse.

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.

Este recurso está em alpha, e seu comportamento pode mudar em versões futuras do provider. Ele é distribuído na compilação regular do provider. Esta página documenta a versão v3.21.0 do provider e posteriores. Consulte os lançamentos do provider para mais detalhes.

​

Configuração do provider

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.

​

Visão geral do recurso

O recurso clickhouse_postgres_service tem os seguintes argumentos:

Argumento	Obrigatório	Descrição
name	Sim	Nome legível por humanos para o serviço. Imutável — alterá-lo destrói e recria o serviço.
cloud_provider	Para uma criação padrão	Provedor de Cloud que hospeda a instância. No momento, apenas aws é compatível. Omita para uma réplica de leitura ou restauração para um ponto no tempo (herdado do recurso de origem).
region	Para uma criação padrão	Região da Cloud (por exemplo, us-east-1). Omita para uma réplica de leitura ou restauração para um ponto no tempo (herdado do recurso de origem).
size	Para uma criação padrão	Tamanho da instância (SKU da VM), por exemplo m6gd.large. Pode ser redimensionada no local. Omita para uma restauração para um ponto no tempo (a instância restaurada será criada com o tamanho do backup).
postgres_version	Não	Versão principal do Postgres (por exemplo, 18). Alterar a versão principal destrói e recria o serviço.
ha_type	Não	Modo de alta disponibilidade: none, async ou sync. Consulte Alta disponibilidade.
password	Para uma criação padrão, a menos que password_wo esteja definido	Senha do superusuário, gerenciada pela sua configuração. O Terraform nunca a lê de volta da API. Armazenada no estado (sensível). Omita para uma réplica de leitura (herdada) ou uma restauração para um ponto no tempo (mantida do backup de origem).
password_wo	Para uma criação padrão, a menos que password esteja definido	Senha de superusuário somente para gravação: aplicada ao serviço, mas nunca armazenada no estado. Requer password_wo_version; requer Terraform 1.11 ou posterior.
password_wo_version	Com password_wo	Número da versão de password_wo. Altere-o para rotacionar para o valor atual de password_wo.
pg_config	Não	Parâmetros do servidor Postgres como um mapa de chave-valor.
pgbouncer_config	Não	Parâmetros do pooler de conexões PgBouncer como um mapa de chave-valor.
tags	Não	Tags do recurso como um mapa de chave-valor.
read_replica_of	Não	ID de um serviço primário a ser replicado. Consulte Réplicas de leitura. Mutuamente exclusivo com restore_to_point_in_time.
restore_to_point_in_time	Não	Cria o serviço restaurando outro serviço para um ponto no tempo. Consulte Restauração para um ponto no tempo. Mutuamente exclusivo com read_replica_of.

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.

A password é armazenada em texto simples no seu estado do Terraform. Proteja seu arquivo de estado adequadamente, por exemplo com um backend remoto usando criptografia em repouso, ou use password_wo para manter a senha totalmente fora do estado.

​

Criar um serviço

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.

​

Alta disponibilidade

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

ha_type	Standbys	Replicação
none	Nenhuma (somente a primária)	—
async	1 standby	Assíncrona — o commit das gravações ocorre sem esperar pela standby
sync	2 standbys	Síncrona — a primária aguarda a confirmação de pelo menos uma 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.

​

Réplicas de leitura

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.

​

Restauração para um ponto no tempo

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.

​

Fontes de dados

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
}

​

Importando serviços existentes

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.

​

Operações não suportadas

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