Managed Postgres のクイックスタート

この方法は、自分で進めても、スクリプト化しても、AI Agent に任せてもかまいません。コンソール版を使う場合は、Cloud UI 表示に切り替えてください。このページでは、ClickHouse CLI (clickhousectl) と psql を使って、ClickHouse Managed Postgres のプロビジョニング、データの読み込み、ClickHouse へのレプリケーション、クエリの実行を、すべてコマンドラインから行う方法を説明します。コマンドは非対話型で、clickhousectl は --json を指定すると JSON を出力します。

前提条件

ClickHouse CLIをインストールします：

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

psql (PostgreSQL client ツール。macOS では brew install libpq) と jq も必要です。書き込み操作 (作成、削除) には API key 認証が必要です。OAuth ログインは読み取り専用です:

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

または、環境変数 CLICKHOUSE_CLOUD_API_KEY と CLICKHOUSE_CLOUD_API_SECRET を設定します。clickhousectl cloud auth status で確認し、スコープが read/write のエントリが表示されることを確認してください。

第1部: Postgresを作成し、データを読み込む

Postgresサービスを作成する

サービスを作成し、レスポンスを保存します。パスワードは一度しか表示されません：

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

レスポンスには、サービス ID、ホスト名、すぐに使える接続文字列が含まれます。

{
  "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": []
}

このガイドの以降で必要になる情報を抽出します:

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

パスワードを紛失した場合は、clickhousectl cloud postgres reset-password $PG_ID --generate で新しいパスワードを生成します。

サービスの Provisioning が完了するまで待機する

Provisioning には数分かかります。状態が running になるまでポーリングしてください:

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

サンプルデータを読み込む

2 つのテーブルを作成し、psql を使って 100 万件のイベントを挿入します:

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

NVMeストレージにより、100万行の insert は c6gd.large (最小サイズ) で約7秒で完了します。クエリで確認してください。データは random() で生成されるため、行数は実行のたびに異なります。

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

第2部: ClickHouse にレプリケートする

ClickHouse サービスを作成する

同じリージョンにサービスを作成し、レスポンスを保存します。パスワードは作成時のレスポンスにのみ表示されます。

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)

稼働状態になるまで待機してください。ClickPipe には稼働中の宛先が必要です：

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

代わりに既存のサービスを使用する場合は、clickhousectl cloud service list で取得した CH_ID を設定し、CH_PASSWORD にはその default ユーザーのパスワードを設定します。これは pg_clickhouse のステップで必要です。

テーブルを ClickHouse にレプリケートする

ClickHouse サービス上に、Managed Postgres のホスト名を指定した Postgres CDC ClickPipe を作成します。このパイプは既存の行をコピーし、その後も継続的な変更に合わせて ClickHouse を同期した状態に保ちます。

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)

注意:

レプリケートテーブルは ClickHouse サービス上の default データベースに作成され、名前は --table-mapping のターゲットで指定したものになります
publication と replication slot は自動的に作成され、publication の対象はマップされたテーブルに限定されます。自分で管理するものを使う場合は --publication-name を指定してください
Postgres のホスト名は直接指定してください。PgBouncer 経由のレプリケーションはサポートされていません

パイプが`Running`になるまで待機します

パイプはRunningに到達するまでに、Provisioning、Setup、 (大きなテーブルの場合は) Snapshotを経由します。サービス上の最初のパイプでは、これに約4分かかります。FailedとInternalErrorは終端状態です:

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

ClickHouse でレプリケートされたデータにクエリを実行する

CLI から ClickHouse サービスに直接 SQL を実行します。最初の呼び出しで、Query API エンドポイントとサービススコープの API キーが自動的に作成されます:

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

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

Postgres への新しい書き込みは継続的にレプリケートされます。1 行を挿入し、件数が 1,000,001 に達するまでポーリングしてください (通常は 1 分未満です) :

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

Postgres から ClickHouse をクエリする

pg_clickhouse 拡張機能を使うと、Postgres をトランザクションデータと分析データの両方に対応する統合クエリレイヤーとして利用できます。ClickHouse の HTTPS ホスト名を取得し、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

ヒアドキュメントは意図的にクォートしていないため、SQL が Postgres に届く前に、シェルが $CH_HOST と $CH_PASSWORD を展開します。これで、レプリケートテーブルが organization スキーマ内の外部テーブルとして参照できるようになり、それらに対するクエリは ClickHouse で実行されます。このデータセットを c6gd.large で測定したところ、分析クエリは外部テーブル経由のほうが 6～9 倍高速でした (たとえば、5 つの集計を含む GROUP BY は ClickHouse 経由で 176 ms、ローカルでは 1,133 ms、集計を伴う JOIN は 298 ms、ローカルでは 2,764 ms) 。

クリーンアップ

まず ClickPipe を削除し、次に Postgres サービスを削除します。サービスを削除すると、そのサービス内のすべてのデータが完全に削除されます。

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

稼働中の ClickHouse サービスは直接削除できません。いったん停止し、stopped になるのを待ってから削除してください。

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"

はじめに

機能

ベンチマーク

料金

ClickHouse Integration

移行

監視

よくある質問

Managed Postgres のクイックスタート

前提条件

第1部: Postgresを作成し、データを読み込む

Postgresサービスを作成する

サービスの Provisioning が完了するまで待機する

サンプルデータを読み込む

第2部: ClickHouse にレプリケートする

ClickHouse サービスを作成する

テーブルを ClickHouse にレプリケートする

パイプが`Running`になるまで待機します

ClickHouse でレプリケートされたデータにクエリを実行する

Postgres から ClickHouse をクエリする

クリーンアップ

​前提条件

​第1部: Postgresを作成し、データを読み込む

​Postgresサービスを作成する

​サービスの Provisioning が完了するまで待機する

​サンプルデータを読み込む

​第2部: ClickHouse にレプリケートする

​ClickHouse サービスを作成する

​テーブルを ClickHouse にレプリケートする

​パイプがRunningになるまで待機します

​ClickHouse でレプリケートされたデータにクエリを実行する

​Postgres から ClickHouse をクエリする

​クリーンアップ

前提条件

第1部: Postgresを作成し、データを読み込む

Postgresサービスを作成する

サービスの Provisioning が完了するまで待機する

サンプルデータを読み込む

第2部: ClickHouse にレプリケートする

ClickHouse サービスを作成する

テーブルを ClickHouse にレプリケートする

パイプが`Running`になるまで待機します

ClickHouse でレプリケートされたデータにクエリを実行する

Postgres から ClickHouse をクエリする

クリーンアップ