OpenAPI de ClickHouse Managed Postgres

Beta

Usa OpenAPI de ClickHouse para gestionar de forma programática tus servicios de ClickHouse 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 ClickHouse 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.

Ahora puedes usarlo en tus solicitudes, así:

ORG_ID=myorgid

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

Ahora ya has hecho tu primera solicitud a la API de Postgres: la [API de listado] de arriba muestra todos los servidores de Postgres de tu organización. La salida debería ser algo como esto:

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

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

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

Ahora usa estos datos para crear una nueva instancia; ten en cuenta que requiere el encabezado Content-Type. Guarda la respuesta: es la única que incluye las credenciales del servicio (la respuesta de [restablecimiento de contraseña] también las devuelve cuando la solicitud no incluye una contraseña):

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

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": "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: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=67b4bc12-8582-45d0-8806-fe9b2e5a54e6
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, sin las credenciales, 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 guardada de la respuesta de creación para conectarse, por ejemplo, con 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=#

Escriba \q para salir de psql.

Actualización

La [API de parches] permite actualizar un subconjunto de las propiedades de un servicio de Managed 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": "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"
}

OpenAPI proporciona endpoints adicionales para actualizar propiedades no admitidas por la [API de parches]. Por ejemplo, para actualizar la [configuración de Postgres], use la [API de configuración]:

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

La salida mostrará la configuración actualizada, así como un mensaje que describe las consecuencias del cambio:

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

Eliminar

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

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 ClickHouse 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.

Logs del servidor

Los logs del servidor PostgreSQL disponibles en el visor de logs de la consola de la nube también están disponibles mediante programación. La API de logs devuelve entradas de log individuales de un servicio durante una ventana de tiempo. Al igual que con Query Insights, la ventana es obligatoria, por lo que pase from_date y to_date como marcas de tiempo RFC 3339. El intervalo no debe superar los 30 días y to_date debe 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

Las entradas se devuelven en orden de más reciente a más antigua; invierta el orden con sort_order (asc o desc). Filtre por un único nivel de gravedad con severity (por ejemplo, ERROR, WARNING o LOG), busque una subcadena del cuerpo del log que distinga entre mayúsculas y minúsculas con body_contains y pagine los resultados con limit y offset.

Cada entrada contiene su timestamp, severity y body sin procesar. El cuerpo es siempre una cadena: las líneas de log estructuradas se devuelven codificadas en JSON y las líneas sin formato, 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
}

El endpoint se pagina con limit y offset en lugar de devolver un recuento total; avance offset hasta que una página devuelva menos entradas que limit.