OpenAPI de ClickHouse Managed Postgres

Utilisez la ClickHouse OpenAPI pour gérer par programmation vos services ClickHouse Managed Postgres, comme vous le feriez avec des services ClickHouse. La même API expose également un [point de terminaison Prometheus] pour collecter les métriques du service. Vous connaissez déjà OpenAPI ? Récupérez vos [clés API] et accédez directement à la référence de l’API ClickHouse Managed Postgres. Sinon, suivez ce guide pour une brève présentation.

Clés API

L’utilisation de l’OpenAPI de ClickHouse nécessite une authentification ; consultez [clés API] pour savoir comment les créer. Utilisez-les ensuite comme identifiants d’authentification Basic, comme suit :

KEY_ID=mykeyid
KEY_SECRET=mykeysecret

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

ID de l’organisation

Ensuite, vous aurez besoin de l’ID de votre organisation.

Sélectionnez le nom de votre organisation dans le coin inférieur gauche de la console.
Sélectionnez Détails de l’organisation.
Cliquez sur l’icône de copie à droite de ID de l’organisation pour le copier directement dans votre presse-papiers.

Vous pouvez maintenant l’utiliser dans vos requêtes, comme ceci :

ORG_ID=myorgid

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

Vous venez d’effectuer votre première requête à l’API Postgres : l’[API de liste] ci-dessus affiche tous les serveurs Postgres de votre organisation. Le résultat devrait ressembler à ceci :

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

Voyons le cycle de vie d’un service Postgres.

Créer

Commencez par en créer un nouveau à l’aide de l’[API de création]. Elle nécessite les propriétés suivantes dans le corps JSON de la requête :

name : nom du nouveau service Postgres
provider : nom du fournisseur cloud : aws (ou gcp en Private Preview)
region : région du fournisseur dans laquelle déployer le service
size : taille de la VM

Consultez la documentation de l’[API de création] pour connaître les valeurs possibles de ces propriétés. De plus, nous allons spécifier Postgres 18 plutôt que la version par défaut, 17 :

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

Utilisez maintenant ces données pour créer une nouvelle instance ; notez que cela nécessite l’en-tête Content-Type. Enregistrez la réponse : c’est la seule qui inclut l’identifiant d’authentification du service (la réponse de [réinitialisation du mot de passe] le renvoie également lorsque la requête ne fournit pas de mot de passe) :

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

En cas de réussite, une nouvelle instance sera créée et ses informations seront renvoyées, y compris les données de connexion :

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

Lecture

Utilisez l’id de la réponse pour récupérer à nouveau le service :

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 sortie sera similaire au JSON renvoyé lors de la création, sans les identifiants, mais surveillez le state ; lorsqu’il passe à running, le serveur est prêt :

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

"running"

Vous pouvez maintenant utiliser la propriété connectionString enregistrée à partir de la réponse de création pour vous connecter, par exemple à l’aide de 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=#

Tapez \q pour quitter psql.

Mise à jour

L’[API patch] permet de mettre à jour un sous-ensemble des propriétés d’un service Postgres géré via JSON Merge Patch RFC 7396. Les tags peuvent être particulièrement utiles dans les déploiements complexes ; envoyez-les simplement seuls dans la requête :

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

Les données renvoyées doivent inclure les nouveaux 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"
}

L’OpenAPI fournit des points de terminaison supplémentaires pour mettre à jour des propriétés non prises en charge par l’[API patch]. Par exemple, pour mettre à jour la [configuration de Postgres], utilisez l’[API de configuration] :

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 sortie affichera la configuration mise à jour ainsi qu’un message décrivant les conséquences de cette modification :

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

Supprimer

Utilisez l’[API de suppression] pour supprimer un service Postgres.

La suppression d’un service Postgres supprime complètement le service et toutes ses données. Assurez-vous de disposer d’une sauvegarde ou d’avoir promu une réplique en primaire avant de supprimer un service.

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

En cas de succès, la réponse renverra le code d’état 200, par exemple :

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

Monitoring

Deux points de terminaison compatibles avec Prometheus exposent des métriques de CPU, de mémoire, d’E/S, de connexion et de transaction pour les services ClickHouse Managed Postgres : l’un renvoie les métriques de tous les services de l’organisation, l’autre celles d’un seul service. Consultez la page [point de terminaison Prometheus] pour la configuration et la [référence des métriques] pour la liste complète des métriques.

Query insights

La télémétrie par instruction qui alimente l’onglet Query Insights dans la console cloud est également accessible par programmation. Deux endpoints exposent les modèles de requête les plus lents d’un service : l’un répertorie tous les modèles classés par impact, l’autre renvoie un modèle précis avec ses exécutions récentes.

Lister les modèles de requête lentes

L’[API slow patterns] renvoie des métriques agrégées pour les modèles de requête les plus lents observés sur un intervalle de temps. Cet intervalle est obligatoire — transmettez from_date et to_date sous forme d’horodatages 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

Les résultats affichent par défaut d’abord les modèles les plus coûteux, triés par total_duration par ordre décroissant. Triez selon un autre compteur avec sort_by (par exemple p99_duration, call_count ou total_wal_bytes) et inversez l’ordre avec sort_order. Affinez l’ensemble avec les filtres db_name, db_user, db_operation et app, et parcourez les pages avec limit et offset. Chaque résultat correspond à un modèle normalisé, dont les valeurs littérales ont été supprimées, avec des durées indiquées en microsecondes :

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

Le queryId est le hachage signé sur 64 bits de l’instruction normalisée ; il est donc souvent négatif. Renvoyez-le tel quel — y compris le - initial — pour récupérer un seul modèle de requête.

Obtenir un modèle de requête lente

Fournissez un queryId issu de la réponse de la liste à la slow pattern API pour obtenir les métriques agrégées de ce modèle, ainsi que ses exécutions individuelles les plus récentes. Les champs db_name, db_user et db_operation qui identifient le modèle sont obligatoires :

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 réponse contient le même agrégat que le point de terminaison de liste sous aggregate, ainsi qu’un tableau recentExecutions. Chaque exécution inclut les compteurs complets par exécution — E/S des blocs partagés et temporaires, temps CPU utilisateur et système, workers parallèles, JIT et WAL — les mêmes compteurs que le [volet de détails] ventile dans la 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
}

L’exemple tronque les deux objets pour plus de concision ; l’API renvoie le jeu complet de compteurs documenté dans per-execution counters.

Journaux du serveur

Les journaux du serveur PostgreSQL affichés dans la visionneuse de journaux de la console cloud sont également accessibles par programmation. L’API des journaux renvoie des entrées de journal individuelles pour un service sur une fenêtre temporelle. Comme pour Query insights, cette fenêtre est obligatoire ; transmettez donc from_date et to_date sous forme d’horodatages RFC 3339. La plage ne doit pas dépasser 30 jours et to_date doit être postérieur à 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

Les entrées sont renvoyées de la plus récente à la plus ancienne ; inversez l’ordre avec sort_order (asc ou desc). Filtrez sur un seul niveau de gravité avec severity (par exemple ERROR, WARNING ou LOG), recherchez une sous-chaîne du corps du log sensible à la casse avec body_contains, et parcourez les résultats avec limit et offset. Chaque entrée contient son timestamp, sa severity et son body brut. Le corps est toujours une chaîne : les lignes de log structurées sont renvoyées encodées en JSON, les lignes simples telles quelles :

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

Le point de terminaison pagine les résultats à l’aide de limit et offset, sans renvoyer le nombre total d’entrées ; incrémentez offset jusqu’à ce qu’une page renvoie moins de limit entrées.

Premiers pas

Fonctionnalités

Tarification

ClickHouse Integration

Migrations

Supervision

FAQ

Clés API

ID de l’organisation

CRUD

Créer

Lecture

Mise à jour

Supprimer

Monitoring

Query insights

Lister les modèles de requête lentes

Obtenir un modèle de requête lente

Journaux du serveur

​Clés API

​ID de l’organisation

​CRUD

​Créer

​Lecture

​Mise à jour

​Supprimer

​Monitoring

​Query insights

​Lister les modèles de requête lentes

​Obtenir un modèle de requête lente

​Journaux du serveur

Clés API

ID de l’organisation

CRUD

Créer

Lecture

Mise à jour

Supprimer

Monitoring

Query insights

Lister les modèles de requête lentes

Obtenir un modèle de requête lente

Journaux du serveur