Démarrage rapide pour Managed Postgres

Vous pouvez suivre ce chemin vous-même, l’automatiser avec un script ou le confier à un agent IA. Passez à la vue Cloud UI pour afficher la version console.Cette page explique comment provisionner ClickHouse Managed Postgres, charger des données, les répliquer vers ClickHouse et exécuter des requêtes sur celles-ci, le tout depuis la ligne de commande avec le ClickHouse CLI (clickhousectl) et psql. Les commandes s’exécutent en mode non interactif ; clickhousectl renvoie du JSON avec --json.

Prérequis

Installez la ClickHouse CLI :

curl https://clickhouse.com/cli | sh

Vous avez également besoin de psql (outils du client PostgreSQL ; sous macOS, brew install libpq) et de jq.Les opérations en écriture (create, delete) nécessitent une authentification par clé API ; la connexion OAuth est en lecture seule :

clickhousectl cloud auth login --api-key <YOUR_KEY> --api-secret <YOUR_SECRET>

Vous pouvez également définir les variables d’environnement CLICKHOUSE_CLOUD_API_KEY et CLICKHOUSE_CLOUD_API_SECRET. Vérifiez avec clickhousectl cloud auth status ; vous devriez voir une entrée avec la portée read/write.

Partie 1 : Créer Postgres et charger les données

Créer un service Postgres

Créez le service et enregistrez la réponse ; le mot de passe n’est affiché qu’une seule fois :

clickhousectl cloud postgres create \
  --name quickstart-pg \
  --region us-east-1 \
  --size c6gd.large \
  --pg-version 18 \
  --json > pg.json

La réponse inclut l’ID du service, le nom d’hôte et une chaîne de connexion prête à l’emploi :

{
  "id": "3b5a3112-bf02-82d0-bd02-fbe67d5caa7a",
  "name": "quickstart-pg",
  "provider": "aws",
  "region": "us-east-1",
  "postgresVersion": "18",
  "size": "c6gd.large",
  "storageSize": 118,
  "haType": "none",
  "state": "creating",
  "createdAt": "2026-07-22T13:21:22Z",
  "hostname": "quickstart-pg-c1406b50.pg7dd324nz0a1qm1fqskxbjn7m.c0.us-east-1.aws.pg.clickhouse.cloud",
  "username": "postgres",
  "password": "vV6cfEr2p_-TzkCDrZOx",
  "connectionString": "postgres://postgres:vV6cfEr2p_-TzkCDrZOx@quickstart-pg-c1406b50.pg7dd324nz0a1qm1fqskxbjn7m.c0.us-east-1.aws.pg.clickhouse.cloud:5432/postgres?channel_binding=require",
  "isPrimary": true,
  "tags": []
}

Extrayez les éléments nécessaires pour la suite de ce guide :

PG_ID=$(jq -r .id pg.json)
PG_URL=$(jq -r .connectionString pg.json)

Si le mot de passe est perdu, générez-en un nouveau avec clickhousectl cloud postgres reset-password $PG_ID --generate.

Attendez que le service soit provisionné

Le provisionnement prend quelques minutes. Vérifiez régulièrement jusqu’à ce que l’état soit running :

while [ "$(clickhousectl cloud postgres get "$PG_ID" --json | jq -r .state)" != "running" ]; do
  sleep 15
done

Charger des données d’exemple

Créez deux tables, puis insérez 1 million d’événements avec psql :

psql "$PG_URL" <<'SQL'
\timing
CREATE TABLE events (
   event_id SERIAL PRIMARY KEY,
   event_name VARCHAR(255) NOT NULL,
   event_type VARCHAR(100),
   event_timestamp TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
   event_data JSONB,
   user_id INT,
   user_ip INET,
   is_active BOOLEAN DEFAULT TRUE,
   created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
   updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE users (
   user_id SERIAL PRIMARY KEY,
   name VARCHAR(100),
   country VARCHAR(50),
   platform VARCHAR(50)
);

INSERT INTO events (event_name, event_type, event_timestamp, event_data, user_id, user_ip)
SELECT
   'Event ' || gs::text AS event_name,
   CASE
       WHEN random() < 0.5 THEN 'click'
       WHEN random() < 0.75 THEN 'view'
       WHEN random() < 0.9 THEN 'purchase'
       WHEN random() < 0.98 THEN 'signup'
       ELSE 'logout'
   END AS event_type,
   NOW() - INTERVAL '1 day' * (gs % 365) AS event_timestamp,
   jsonb_build_object('key', 'value' || gs::text, 'additional_info', 'info_' || (gs % 100)::text) AS event_data,
   GREATEST(1, LEAST(1000, FLOOR(POWER(random(), 2) * 1000) + 1)) AS user_id,
   ('192.168.1.' || ((gs % 254) + 1))::inet AS user_ip
FROM
   generate_series(1, 1000000) gs;

INSERT INTO users (name, country, platform)
SELECT
    first_names[first_idx] || ' ' || last_names[last_idx] AS name,
    CASE
        WHEN random() < 0.25 THEN 'India'
        WHEN random() < 0.5 THEN 'USA'
        WHEN random() < 0.7 THEN 'Germany'
        WHEN random() < 0.85 THEN 'China'
        ELSE 'Other'
    END AS country,
    CASE
        WHEN random() < 0.2 THEN 'iOS'
        WHEN random() < 0.4 THEN 'Android'
        WHEN random() < 0.6 THEN 'Web'
        WHEN random() < 0.75 THEN 'Windows'
        WHEN random() < 0.9 THEN 'MacOS'
        ELSE 'Linux'
    END AS platform
FROM
    generate_series(1, 1000) AS seq
    CROSS JOIN LATERAL (
        SELECT
            array['Alice', 'Bob', 'Charlie', 'Diana', 'Eve', 'Frank', 'Grace', 'Hank', 'Ivy', 'Jack', 'Liam', 'Olivia', 'Noah', 'Emma', 'Sophia', 'Benjamin', 'Isabella', 'Lucas', 'Mia', 'Amelia', 'Aarav', 'Riya', 'Arjun', 'Ananya', 'Wei', 'Li', 'Huan', 'Mei', 'Hans', 'Klaus', 'Greta', 'Sofia'] AS first_names,
            array['Smith', 'Johnson', 'Williams', 'Brown', 'Jones', 'Garcia', 'Miller', 'Davis', 'Martinez', 'Taylor', 'Anderson', 'Thomas', 'Jackson', 'White', 'Harris', 'Martin', 'Thompson', 'Moore', 'Lee', 'Perez', 'Sharma', 'Patel', 'Gupta', 'Reddy', 'Zhang', 'Wang', 'Chen', 'Liu', 'Schmidt', 'Müller', 'Weber', 'Fischer'] AS last_names,
            1 + (seq % 32) AS first_idx,
            1 + ((seq / 32)::int % 32) AS last_idx
    ) AS names;
SQL

Timing is on.
CREATE TABLE
Time: 86.029 ms
CREATE TABLE
Time: 80.962 ms
INSERT 0 1000000
Time: 7120.357 ms (00:07.120)
INSERT 0 1000
Time: 84.807 ms

L’insertion de 1 M de lignes s’effectue en environ 7 secondes sur c6gd.large (la plus petite taille), grâce au stockage NVMe. Vérifiez-le avec une requête ; le nombre de lignes varie d’une exécution à l’autre, car les données sont générées avec random() :

psql "$PG_URL" -c "SELECT event_type, COUNT(*) FROM events GROUP BY event_type ORDER BY 2 DESC;"

Partie 2 : Répliquer dans ClickHouse

Créer un service ClickHouse

Créez un service dans la même région et enregistrez la réponse ; le mot de passe n’apparaît que dans la réponse de création :

clickhousectl cloud service create \
  --name quickstart-ch \
  --region us-east-1 \
  --json > ch.json

CH_ID=$(jq -r .service.id ch.json)
CH_PASSWORD=$(jq -r .password ch.json)

Attendez qu’il soit actif ; le ClickPipe nécessite une destination active :

while [ "$(clickhousectl cloud service get "$CH_ID" --json | jq -r .state)" != "running" ]; do
  sleep 15
done

Pour utiliser plutôt un service existant, définissez CH_ID à partir de clickhousectl cloud service list et CH_PASSWORD sur le mot de passe de l’utilisateur default, requis à l’étape pg_clickhouse.

Répliquer les tables vers ClickHouse

Créez un Postgres CDC ClickPipe sur le service ClickHouse, en pointant vers le nom d’hôte de Managed Postgres. Le pipe copie les lignes existantes, puis maintient ClickHouse synchronisé avec les changements ultérieurs :

PG_HOST=$(jq -r .hostname pg.json)
PG_PASSWORD=$(jq -r .password pg.json)

clickhousectl cloud clickpipe create postgres "$CH_ID" \
  --name quickstart-sync \
  --host "$PG_HOST" \
  --pg-database postgres \
  --username postgres \
  --password "$PG_PASSWORD" \
  --table-mapping public.events:public_events \
  --table-mapping public.users:public_users \
  --json > pipe.json

PIPE_ID=$(jq -r .id pipe.json)

Remarques :

Les tables répliquées sont créées dans la base de données default du service ClickHouse, selon les cibles de --table-mapping
La publication et le slot de réplication sont créés automatiquement, la publication étant limitée aux tables mappées ; passez --publication-name pour utiliser celle que vous gérez vous-même
Utilisez directement le nom d’hôte de Postgres ; la réplication n’est pas prise en charge via PgBouncer

Attendez que le pipe passe à l’état `Running`

Le pipe passe par Provisioning, Setup et (pour les tables plus volumineuses) Snapshot avant de passer à l’état Running, ce qui prend environ 4 minutes pour le premier pipe sur un service. Failed et InternalError sont des états terminaux :

while :; do
  STATE=$(clickhousectl cloud clickpipe get "$CH_ID" "$PIPE_ID" --json | jq -r .state)
  case "$STATE" in
    Running) break ;;
    Failed|InternalError) echo "ClickPipe entered terminal state: $STATE" >&2; exit 1 ;;
  esac
  sleep 15
done

Interroger les données répliquées dans ClickHouse

Exécutez des requêtes SQL sur le service ClickHouse directement depuis la CLI. Le premier appel crée automatiquement un endpoint Query API et une clé API limitée à ce service :

clickhousectl cloud service query --id "$CH_ID" \
  --query "SELECT count() FROM public_events"

Provisioning Query API endpoint + key for service 'quickstart-ch'...
1000000

Les nouvelles écritures dans Postgres sont répliquées en continu. Insérez une ligne, puis interrogez régulièrement jusqu’à ce que le nombre atteigne 1 000 001 (généralement en moins d’une minute) :

psql "$PG_URL" -c "INSERT INTO events (event_name, event_type, user_id, user_ip) VALUES ('cdc-test', 'click', 42, '10.0.0.1');"

while [ "$(clickhousectl cloud service query --id "$CH_ID" \
  --query "SELECT count() FROM public_events")" != "1000001" ]; do
  sleep 10
done

Interroger ClickHouse depuis Postgres

L’extension pg_clickhouse permet à Postgres de servir de couche de requête unifiée pour les données transactionnelles et analytiques. Récupérez le nom d’hôte HTTPS de ClickHouse, puis configurez l’extension via psql :

CH_HOST=$(clickhousectl cloud service get "$CH_ID" --json \
  | jq -r '.endpoints[] | select(.protocol=="https") | .host')

psql "$PG_URL" <<SQL
CREATE EXTENSION pg_clickhouse;
CREATE SERVER ch FOREIGN DATA WRAPPER clickhouse_fdw
       OPTIONS(driver 'http', host '$CH_HOST', dbname 'default', port '8443');
CREATE USER MAPPING FOR CURRENT_USER SERVER ch
       OPTIONS (user 'default', password '$CH_PASSWORD');
CREATE SCHEMA organization;
IMPORT FOREIGN SCHEMA "default" FROM SERVER ch INTO organization;
SQL

Le heredoc est volontairement non guillemeté, afin que le shell substitue $CH_HOST et $CH_PASSWORD avant que le SQL n’arrive à Postgres. Les tables répliquées sont désormais visibles comme des tables étrangères dans le schéma organization ; les requêtes qui les ciblent s’exécutent dans ClickHouse.Mesurées sur c6gd.large avec ce jeu de données, les requêtes analytiques s’exécutent 6 à 9 fois plus vite via les tables étrangères (par exemple, un GROUP BY avec 5 agrégations : 176 ms via ClickHouse contre 1 133 ms en local ; un JOIN avec agrégations : 298 ms contre 2 764 ms).

Nettoyage

Supprimez d’abord le ClickPipe, puis le service Postgres. La suppression d’un service entraîne la suppression définitive de toutes ses données :

clickhousectl cloud clickpipe delete "$CH_ID" "$PIPE_ID"
clickhousectl cloud postgres delete "$PG_ID"

Un service ClickHouse en cours d’exécution ne peut pas être supprimé directement. Arrêtez-le, attendez qu’il soit stopped, puis supprimez-le :

clickhousectl cloud service stop "$CH_ID"

while [ "$(clickhousectl cloud service get "$CH_ID" --json | jq -r .state)" != "stopped" ]; do
  sleep 10
done

clickhousectl cloud service delete "$CH_ID"

Premiers pas

Fonctionnalités

Benchmarks

Tarification

Intégration ClickHouse

Migrations

Surveillance

FAQ

Prérequis

Partie 1 : Créer Postgres et charger les données

Créer un service Postgres

Attendez que le service soit provisionné

Charger des données d’exemple

Partie 2 : Répliquer dans ClickHouse

Créer un service ClickHouse

Répliquer les tables vers ClickHouse

Attendez que le pipe passe à l’état `Running`

Interroger les données répliquées dans ClickHouse

Interroger ClickHouse depuis Postgres

Nettoyage

​Prérequis

​Partie 1 : Créer Postgres et charger les données

​Créer un service Postgres

​Attendez que le service soit provisionné

​Charger des données d’exemple

​Partie 2 : Répliquer dans ClickHouse

​Créer un service ClickHouse

​Répliquer les tables vers ClickHouse

​Attendez que le pipe passe à l’état Running

​Interroger les données répliquées dans ClickHouse

​Interroger ClickHouse depuis Postgres

​Nettoyage

Prérequis

Partie 1 : Créer Postgres et charger les données

Créer un service Postgres

Attendez que le service soit provisionné

Charger des données d’exemple

Partie 2 : Répliquer dans ClickHouse

Créer un service ClickHouse

Répliquer les tables vers ClickHouse

Attendez que le pipe passe à l’état `Running`

Interroger les données répliquées dans ClickHouse

Interroger ClickHouse depuis Postgres

Nettoyage