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.

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, que alteraram a forma como as credenciais são gerenciadas; versões anteriores se comportam de forma diferente e, desde 31 de julho de 2026, não funcionam mais corretamente. Consulte os lançamentos do provider para mais detalhes.

Faça upgrade para o provider v3.21.0 antes de 31 de julho de 2026Desde 31 de julho de 2026, a API do Managed Postgres deixou de retornar a senha do superusuário e a string de conexão em suas respostas; as credenciais são retornadas apenas quando um serviço é criado ou sua senha é redefinida. As versões v3.21.0 e posteriores do provider funcionam de forma idêntica antes e depois dessa alteração. Versões mais antigas do provider dependem de a API repetir as credenciais: desde 31 de julho de 2026, elas não preenchem mais connection_string, e um serviço criado sem uma password declarada é criado com sucesso, enquanto a senha gerada nunca é capturada em nenhum lugar.Faça upgrade antes de 31 de julho de 2026. Seu estado é migrado automaticamente no primeiro plan ou apply com a v3.21.0. Se algum dos seus serviços depender de uma senha gerada pelo servidor (sem password na configuração), recupere-a primeiro com terraform state pull e declare-a, pois a v3.21.0 exige password ou password_wo para um serviço padrão.

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 (removido na v3.21.0): 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 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 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 {}.

Primeiros passos

Funcionalidades

Benchmarks

Preços

Integração do ClickHouse

Migrações

Monitoramento

FAQ

Referência do Terraform para o ClickHouse Managed Postgres

Configuração do provider

Visão geral do recurso

Criar um serviço

Alta disponibilidade

Réplicas de leitura

Restauração para um ponto no tempo

Fontes de dados

Importando serviços existentes

Operações não suportadas

​Configuração do provider

​Visão geral do recurso

​Criar um serviço

​Alta disponibilidade

​Réplicas de leitura

​Restauração para um ponto no tempo

​Fontes de dados

​Importando serviços existentes

​Operações não suportadas

Configuração do provider

Visão geral do recurso

Criar um serviço

Alta disponibilidade

Réplicas de leitura

Restauração para um ponto no tempo

Fontes de dados

Importando serviços existentes

Operações não suportadas