ClickHouse Managed Postgres OpenAPI

Controle seus serviços do ClickHouse Managed Postgres com nossa OpenAPI

Use a OpenAPI do ClickHouse para controlar programaticamente seus serviços do ClickHouse Managed Postgres da mesma forma que os serviços do ClickHouse. A mesma API também expõe um endpoint do Prometheus para coleta de métricas do serviço. Já conhece a OpenAPI? Obtenha suas chaves de API e vá direto para a referência da API do ClickHouse Managed Postgres. Caso contrário, acompanhe este guia rápido.

​

Chaves de API

O uso da OpenAPI do ClickHouse requer autenticação; consulte chaves de API para saber como criá-las. Depois, use-as como credenciais de autenticação básica, assim:

KEY_ID=mykeyid
KEY_SECRET=mykeysecret

curl -s --user "$KEY_ID:$KEY_SECRET" https://api.clickhouse.cloud/v1/organizations | jq

​

Organization ID

Em seguida, você precisará do Organization ID da sua organização.

1. Selecione o nome da sua organização no canto inferior esquerdo do Console.
2. Selecione Organization details.
3. Clique no ícone de cópia à direita de Organization ID para copiá-lo diretamente para a área de transferência.

Agora você já pode usá-lo nas suas requisições, assim:

ORG_ID=myorgid

curl -s --user "$KEY_ID:$KEY_SECRET" \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres" | jq

Agora você fez sua primeira requisição à API do Postgres: a list API acima lista todos os servidores Postgres da sua organização. A saída deve ser algo como:

{
  "result": [
    {
      "id": "ee2fef9f-b443-8ad0-8c9b-724390cdb826",
      "name": "oltp",
      "provider": "aws",
      "region": "eu-west-2",
      "postgresVersion": "18",
      "size": "r6gd.medium",
      "storageSize": 59,
      "haType": "none",
      "tags": [],
      "isPrimary": true,
      "state": "running",
      "createdAt": "2026-05-25T16:42:16+00:00"
    }
  ],
  "requestId": "c128d830-5769-4c82-8235-f79aa69d1ebf",
  "status": 200
}

​

CRUD

Vamos analisar o ciclo de vida de um serviço Postgres.

​

Criar

Primeiro, crie um novo serviço usando a create API. Ela exige as seguintes propriedades no corpo JSON da solicitação:

• name: Nome do novo serviço Postgres
• provider: Nome do provedor de Cloud: aws (ou gcp em Private Preview)
• region: Região na rede do provedor onde o serviço será implantado
• size: Tamanho da VM

Consulte a documentação da create API para ver os valores possíveis dessas propriedades. Além disso, vamos especificar o Postgres 18 em vez da versão padrão, 17:

create_data='{
  "name": "my postgres",
  "provider": "aws",
  "region": "us-west-2",
  "postgresVersion": "18",
  "size": "r8gd.large"
}'

Agora use esses dados para criar uma nova instância; observe que isso requer o cabeçalho Content-Type. Salve a resposta: ela é a única que inclui as credenciais do serviço (a resposta de redefinição de senha também as retorna quando a solicitação não fornece uma senha):

pg_created=$(curl -s --user "$KEY_ID:$KEY_SECRET" -H 'Content-Type: application/json' \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres" \
    -d "$create_data")
echo "$pg_created" | jq

Em caso de sucesso, uma nova instância será criada e as informações sobre ela serão retornadas, incluindo os dados de conexão:

{
  "result": {
    "id": "67b4bc12-8582-45d0-8806-fe9b2e5a54e6",
    "name": "my postgres",
    "provider": "aws",
    "region": "us-west-2",
    "postgresVersion": "18",
    "size": "r8gd.large",
    "storageSize": 118,
    "haType": "none",
    "tags": [],
    "connectionString": "postgres://postgres:[e-mail]:5432/postgres?channel_binding=require",
    "username": "postgres",
    "password": "vV6cfEr2p_-TzkCDrZOx",
    "hostname": "my-postgres-6d8d2e3e.pg7myrd1j06p3gx4zrm2ze8qz6.c0.us-west-2.aws.pg.clickhouse-dev.com",
    "isPrimary": true,
    "state": "creating"
  },
  "requestId": "a5957990-dbe5-46fd-b5ce-a7f8f79e50fe",
  "status": 200
}

​

Ler

Use o id da resposta para obter o serviço novamente:

PG_ID=67b4bc12-8582-45d0-8806-fe9b2e5a54e6
curl -s --user "$KEY_ID:$KEY_SECRET" \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID" \
    | jq

A saída será semelhante ao JSON retornado na criação, sem as credenciais, mas fique de olho em state; quando ele mudar para running, o servidor estará pronto:

curl -s --user "$KEY_ID:$KEY_SECRET" \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID" \
    | jq .result.state

"running"

Agora você pode usar a propriedade connectionString salva da resposta de criação para se conectar, por exemplo, usando psql:

$ psql "$(echo "$pg_created" | jq -r .result.connectionString)"

psql (18.3)
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off, ALPN: postgresql)
Type "help" for help.

postgres=#

Digite \q para sair do psql.

​

Atualização

A API de patch oferece suporte à atualização de um subconjunto das propriedades de um serviço Postgres usando RFC 7396 JSON Merge Patch. As tags podem ser especialmente úteis em implantações complexas; basta enviá-las sozinhas na solicitação:

curl -sX PATCH --user "$KEY_ID:$KEY_SECRET" -H 'Content-Type: application/json' \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID" \
    -d '{"tags": [{"key": "Environment", "value": "production"}]}' \
    | jq .result

Os dados retornados devem incluir as novas tags:

{
  "id": "67b4bc12-8582-45d0-8806-fe9b2e5a54e6",
  "name": "my postgres",
  "provider": "aws",
  "region": "us-west-2",
  "postgresVersion": "18",
  "size": "r8gd.large",
  "storageSize": 118,
  "haType": "none",
  "tags": [
    {
      "key": "Environment",
      "value": "production"
    }
  ],
  "username": "postgres",
  "hostname": "my-postgres-6d8d2e3e.$PG_ID.c0.us-west-2.aws.pg.clickhouse-dev.com",
  "isPrimary": true,
  "state": "running"
}

A OpenAPI fornece endpoints adicionais para atualizar propriedades não suportadas pela API de patch. Por exemplo, para atualizar a configuração do Postgres, use a config API:

curl -s --user "$KEY_ID:$KEY_SECRET" -H 'Content-Type: application/json' \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID/config" \
    -d '{"pgConfig": {"max_connections": "42"}, "pgBouncerConfig": {}}' | jq

A saída mostrará a configuração atualizada, bem como uma mensagem que descreve as consequências da alteração:

{
  "result":{
    "pgConfig": {
      "max_connections": "42"
    },
    "pgBouncerConfig": {},
    "message": "The changes in the following parameters require a database restart to take effect: max_connections. You can restart the database by using the restart endpoint."
  },
  "requestId":"fdec06f2-66f7-45b4-9f82-0c051aba20aa",
  "status": 200
}

​

Excluir

Use a API de exclusão para excluir um serviço Postgres.

Excluir um serviço Postgres remove completamente o serviço e todos os seus dados. Certifique-se de ter um backup ou de ter promovido uma réplica para primária antes de excluir um serviço.

curl -sX DELETE --user "$KEY_ID:$KEY_SECRET" \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID" \
    | jq

Em caso de sucesso, a resposta retornará o código de status 200, por exemplo:

{
  "requestId": "ac9bbffa-e370-410c-8bdd-bd24bf3d7f82",
  "status": 200
}

​

Monitoramento

Dois endpoints compatíveis com o Prometheus expõem métricas de CPU, memória, E/S, conexão e transação para serviços do ClickHouse Managed Postgres: um fornece métricas de todos os serviços da organização; o outro, de um único serviço. Consulte a página endpoint do Prometheus para a configuração e a referência de métricas para ver a lista completa de métricas.

​

Query insights

A telemetria por instrução que alimenta a aba Query Insights no console da Cloud também está disponível programaticamente. Dois endpoints expõem os padrões de consulta mais lentos em um serviço: um lista todos os padrões ordenados por impacto; o outro retorna um único padrão com suas execuções recentes.

​

Listar padrões de consultas lentas

A slow patterns API retorna métricas agregadas dos padrões de consulta mais lentos observados em uma janela de tempo. A janela é obrigatória — passe from_date e to_date como timestamps no formato RFC 3339:

FROM=2026-05-25T00:00:00Z
TO=2026-05-26T00:00:00Z

curl -s --user "$KEY_ID:$KEY_SECRET" \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID/slowQueryPatterns?from_date=$FROM&to_date=$TO" \
    | jq

Por padrão, os resultados mostram primeiro os padrões de maior custo, classificados por total_duration em ordem decrescente. Ordene por um contador diferente com sort_by (por exemplo, p99_duration, call_count ou total_wal_bytes) e inverta a direção com sort_order. Restrinja o conjunto com os filtros db_name, db_user, db_operation e app, e percorra as páginas com limit e offset.

Cada resultado é um padrão normalizado, com os literais removidos e as durações informadas em microssegundos:

{
  "result": [
    {
      "queryId": "-4748036479882663975",
      "queryText": "SELECT * FROM orders WHERE customer_id = $1 ORDER BY created_at DESC LIMIT $2",
      "dbName": "sales",
      "dbUser": "orders_service",
      "dbOperation": "SELECT",
      "app": "orders-api",
      "callCount": 84213,
      "errorCount": 0,
      "totalDurationUs": 1012384556,
      "avgDurationUs": 12021,
      "maxDurationUs": 482915,
      "p50DurationUs": 9874,
      "p95DurationUs": 28431,
      "p99DurationUs": 41200,
      "totalRows": 842130,
      "totalSharedBlksRead": 19284,
      "totalSharedBlksHit": 48217734,
      "totalCpuTimeUs": 938472113,
      "totalWalBytes": 0
    }
  ],
  "requestId": "c128d830-5769-4c82-8235-f79aa69d1ebf",
  "status": 200
}

O queryId é um hash com sinal de 64 bits da instrução normalizada, então geralmente é negativo. Envie-o de volta exatamente como está — com o - inicial e tudo — para obter um único padrão.

​

Obter um padrão de consulta lenta

Passe um queryId retornado pela resposta da lista para a API de padrão de consulta lenta para obter as métricas agregadas desse padrão, junto com suas execuções individuais mais recentes. db_name, db_user e db_operation, que identificam o padrão, são obrigatórios:

QUERY_ID=-4748036479882663975

curl -s --user "$KEY_ID:$KEY_SECRET" \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID/slowQueryPatterns/$QUERY_ID?db_name=sales&db_user=orders_service&db_operation=SELECT" \
    | jq

A resposta retorna a mesma agregação do endpoint de listagem em aggregate, além de um array recentExecutions. Cada execução inclui os contadores completos por execução — E/S de blocos compartilhados e temporários, tempo de CPU em modo usuário e do sistema, workers paralelos, JIT e WAL — os mesmos contadores que o painel lateral de detalhes detalha no Console:

{
  "result": {
    "aggregate": {
      "queryId": "-4748036479882663975",
      "queryText": "SELECT * FROM orders WHERE customer_id = $1 ORDER BY created_at DESC LIMIT $2",
      "dbName": "sales",
      "dbUser": "orders_service",
      "dbOperation": "SELECT",
      "callCount": 84213,
      "avgDurationUs": 12021,
      "p99DurationUs": 41200
    },
    "recentExecutions": [
      {
        "timestamp": "2026-05-25T16:42:09Z",
        "durationUs": 41200,
        "rows": 10,
        "sharedBlksHit": 412,
        "sharedBlksRead": 3,
        "tempBlksWritten": 0,
        "cpuUserTimeUs": 38211,
        "cpuSysTimeUs": 1044,
        "parallelWorkersPlanned": 0,
        "parallelWorkersLaunched": 0,
        "walBytes": 0,
        "serverRole": "primary"
      }
    ]
  },
  "requestId": "a5957990-dbe5-46fd-b5ce-a7f8f79e50fe",
  "status": 200
}

O exemplo resume ambos os objetos por brevidade; a API retorna o conjunto completo de contadores documentado em contadores por execução.

​

Logs do servidor

Os logs do servidor PostgreSQL exibidos no visualizador de logs do console do Cloud também estão disponíveis programaticamente. A API de logs retorna entradas de log individuais de um serviço em uma janela de tempo. Assim como no Query Insights, a janela é obrigatória; portanto, passe from_date e to_date como timestamps RFC 3339. O intervalo não pode exceder 30 dias, e to_date deve ser posterior a from_date:

FROM=2026-05-25T00:00:00Z
TO=2026-05-26T00:00:00Z

curl -s --user "$KEY_ID:$KEY_SECRET" \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID/logs?from_date=$FROM&to_date=$TO" \
    | jq

As entradas são retornadas da mais recente para a mais antiga; inverta a ordem com sort_order (asc ou desc). Filtre por uma única severidade com severity (por exemplo, ERROR, WARNING ou LOG), encontre uma substring do corpo do log que diferencia maiúsculas de minúsculas com body_contains e pagine os resultados com limit e offset.

Cada entrada contém timestamp, severity e body bruto. O corpo é sempre uma string: linhas de log estruturadas são retornadas codificadas em JSON, e linhas simples são retornadas literalmente:

{
  "result": [
    {
      "timestamp": "2026-05-25T16:42:09.512844Z",
      "severity": "ERROR",
      "body": "{\"message\":\"deadlock detected\",\"detail\":\"Process 42 waits for ShareLock\"}"
    },
    {
      "timestamp": "2026-05-25T16:41:58.004120Z",
      "severity": "LOG",
      "body": "connection received: host=10.0.0.7 port=54210 user=orders_service database=sales"
    }
  ],
  "limit": 50,
  "offset": 0,
  "requestId": "b0d5c3a1-9f2e-4a7c-8b1d-3e6f0a2c4d55",
  "status": 200
}

O endpoint é paginado com limit e offset, em vez de retornar uma contagem total; avance o offset até que uma página retorne menos entradas que o limit.