OpenAPI de Managed Postgres

Usa ClickHouse OpenAPI para gestionar de forma programática tus servicios de Managed Postgres, igual que los servicios de ClickHouse. La misma API también expone un [endpoint de Prometheus] para hacer scraping de las métricas del servicio. ¿Ya conoces OpenAPI? Obtén tus [claves de API] y ve directamente a la referencia de la API de Managed Postgres. De lo contrario, sigue leyendo para ver un resumen rápido.

Claves de API

Para usar la OpenAPI de ClickHouse se requiere autenticación; consulta API keys para ver cómo crearlas. Luego úsalas como credenciales de autenticación Basic, así:

KEY_ID=mykeyid
KEY_SECRET=mykeysecret

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

Organization ID

A continuación, necesitarás tu Organization ID.

Selecciona el nombre de tu organización en la esquina inferior izquierda de la Console.
Selecciona Detalles de la organización.
Haz clic en el icono de copiar situado a la derecha de Organization ID para copiarlo directamente al portapapeles.

CRUD

Veamos el ciclo de vida de un servicio de Postgres.

Crear

Primero, cree uno nuevo usando la [API de creación]. Requiere las siguientes propiedades en el cuerpo JSON de la solicitud:

name: Nombre del nuevo servicio de Postgres
provider: Nombre del proveedor de la nube
region: Región dentro de la red del proveedor en la que se desplegará el servicio
size: Tamaño de la VM
storageSize: Tamaño de almacenamiento de la VM

Consulte la documentación de la [API de creación] para ver los posibles valores de estas propiedades. Además, especifiquemos Postgres 18 en lugar de la versión predeterminada, 17:

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

Ahora usa estos datos para crear una nueva instancia; ten en cuenta que requiere el encabezado Content-Type:

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

Si la operación se realiza correctamente, se creará una nueva instancia y se devolverá información sobre ella, incluidos los datos de conexión:

{
  "result": {
    "id": "pg7myrd1j06p3gx4zrm2ze8qz6",
    "name": "my postgres",
    "provider": "aws",
    "region": "us-west-2",
    "postgresVersion": "18",
    "size": "r8gd.large",
    "storageSize": 118,
    "haType": "none",
    "tags": [],
    "connectionString": "postgres://postgres:vV6cfEr2p_-TzkCDrZOx@my-postgres-6d8d2e3e.pg7myrd1j06p3gx4zrm2ze8qz6.c0.us-west-2.aws.pg.clickhouse-dev.com: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
}

Leer

Usa el id de la respuesta para volver a obtener el servicio:

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

La salida será similar al JSON devuelto al crearlo, pero presta atención al state; cuando cambie a running, el servidor estará listo:

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

"running"

Ahora puede usar la propiedad connectionString para conectarse, por ejemplo, con psql:

$ psql "$(
    curl -s --user "$KEY_ID:$KEY_SECRET" \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID" \
    | 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=# 

Escriba \q para salir de psql.

Actualización

La [API de parches] permite actualizar un subconjunto de las propiedades de un servicio gestionado de Postgres mediante JSON Merge Patch de RFC 7396. Las etiquetas pueden ser de especial interés en despliegues complejos; simplemente envíelas solas en la solicitud:

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

La respuesta debería incluir las nuevas etiquetas:

{
  "id": "$PG_ID",
  "name": "my postgres",
  "provider": "aws",
  "region": "us-west-2",
  "postgresVersion": "18",
  "size": "r8gd.large",
  "storageSize": 118,
  "haType": "none",
  "tags": [
    {
      "key": "Environment",
      "value": "production"
    }
  ],
  "connectionString": "postgres://postgres:vV6cfEr2p_-TzkCDrZOx@my-postgres-6d8d2e3e.$PG_ID.c0.us-west-2.aws.pg.clickhouse-dev.com:5432/postgres?channel_binding=require",
  "username": "postgres",
  "password": "vV6cfEr2p_-TzkCDrZOx",
  "hostname": "my-postgres-6d8d2e3e.$PG_ID.c0.us-west-2.aws.pg.clickhouse-dev.com",
  "isPrimary": true,
  "state": "running"
}

Eliminar

Usa la [API de eliminación] para eliminar un servicio de Postgres.

Eliminar un servicio de Postgres elimina por completo el servicio y todos sus datos. Asegúrate de tener una copia de seguridad o de haber promovido una réplica a primaria antes de eliminar un servicio.

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

En caso de éxito, la respuesta devolverá el código de estado 200, por ejemplo:

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

Monitorización

Dos endpoints compatibles con Prometheus exponen métricas de CPU, memoria, E/S, conexión y transacción para los servicios de Managed Postgres: uno devuelve métricas de todos los servicios de la organización y el otro de un solo servicio. Consulta la página de [endpoint de Prometheus] para la configuración y la [referencia de métricas] para ver la lista completa de métricas.

Query insights

La telemetría por sentencia en la que se basa la pestaña Query Insights de la consola de la nube también está disponible programáticamente. Dos endpoints exponen los patrones de consulta más lentos de un servicio: uno enumera cada patrón ordenado por impacto; el otro devuelve un único patrón con sus ejecuciones recientes.

Listar patrones de consultas lentas

La [API de patrones lentos] devuelve métricas agregadas de los patrones de consulta más lentos observados dentro de una ventana de tiempo. La ventana es obligatoria: indica from_date y to_date como marcas de tiempo 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

Los resultados muestran de forma predeterminada primero los patrones más costosos, ordenados por total_duration de forma descendente. Ordene por un contador diferente con sort_by (por ejemplo, p99_duration, call_count o total_wal_bytes) y cambie la dirección con sort_order. Restrinja el conjunto con los filtros db_name, db_user, db_operation y app, y pagínelo con limit y offset. Cada resultado es un patrón normalizado, con los literales eliminados y las duraciones expresadas en microsegundos:

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

El queryId es un hash con signo de 64 bits de la sentencia normalizada, por lo que a menudo es negativo. Devuélvalo tal cual — con el - inicial y todo — para obtener un único patrón.

Obtener un patrón de consulta lenta

Pase un queryId de la respuesta de la lista a la [API de patrones lentos] para obtener las métricas agregadas de ese patrón junto con sus ejecuciones individuales más recientes. Se requieren db_name, db_user y db_operation, que identifican el patrón:

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

La respuesta incluye la misma agregación que el endpoint de lista en aggregate, además de un array recentExecutions. Cada ejecución incluye los contadores completos por ejecución — E/S de bloques compartidos y temporales, tiempo de CPU en modo usuario y de sistema, workers paralelos, JIT y WAL —, los mismos contadores que el [panel lateral de detalles] desglosa en la consola:

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

El ejemplo recorta ambos objetos por brevedad; la API devuelve el conjunto completo de contadores documentado en per-execution counters.

Get started

Features

Benchmarks

Pricing

ClickHouse Integration

Migrations

Monitoring

FAQ

Claves de API

Organization ID

CRUD

Crear

Leer

Actualización

Eliminar

Monitorización

Query insights

Listar patrones de consultas lentas

Obtener un patrón de consulta lenta

​Claves de API

​Organization ID

​CRUD

​Crear

​Leer

​Actualización

​Eliminar

​Monitorización

​Query insights

​Listar patrones de consultas lentas

​Obtener un patrón de consulta lenta

Claves de API

Organization ID

CRUD

Crear

Leer

Actualización

Eliminar

Monitorización

Query insights

Listar patrones de consultas lentas

Obtener un patrón de consulta lenta