ClickHouse Managed Postgres OpenAPI

ClickHouse OpenAPI を使用すると、 ClickHouse サービスと同様に ClickHouse Managed Postgres サービスをプログラムから操作できます。同じ API では、サービスのメトリクスをスクレイピングするための Prometheus エンドポイントも公開されています。すでに OpenAPI に慣れている場合は、API キーを取得して ClickHouse Managed Postgres API リファレンスに直接進んでください。そうでない場合は、このまま簡単な概要をご確認ください。

API キー

ClickHouse OpenAPI を使用するには認証が必要です。作成方法については [API keys] を参照してください。次に、以下のように Basic 認証の認証情報として使用します。

KEY_ID=mykeyid
KEY_SECRET=mykeysecret

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

Organization ID

次に、Organization ID が必要になります。

コンソールの左下で組織名を選択します。
Organization details を選択します。
Organization ID の右側にあるコピーアイコンをクリックして、直接クリップボードにコピーします。

これで、次のようにリクエストで使用できます。

ORG_ID=myorgid

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

これで最初の Postgres API リクエストを実行できました。上記の list API では、組織内のすべての Postgres サーバーが一覧表示されます。出力は次のようになります。

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

Postgres サービスのライフサイクルを見ていきましょう。

作成

まず、create API を使って新しく作成します。このリクエストでは、JSONボディに次のプロパティを含める必要があります。

name: 新しいPostgres サービスの名前
provider: クラウドプロバイダーの名前
region: serviceをデプロイするproviderのネットワーク内のRegion
size: VMのサイズ

これらのプロパティの設定可能な値については、create API のドキュメントを参照してください。さらに、デフォルトの17ではなく、Postgres 18を指定します。

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

次に、このデータを使用して新しいインスタンスを作成します。なお、そのためにはContent-Typeヘッダーの内容が必要です。レスポンスを保存してください。serviceの認証情報が含まれるのはこのレスポンスだけです (リクエストでpasswordを指定しない場合、password reset のレスポンスでも返されます) ：

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

成功すると、新しいインスタンスが作成され、その情報 (接続情報を含む) が返されます：

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

取得

レスポンスのidを使って、サービスを再度取得します:

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

出力は作成時に返されるJSONと似ていますが、認証情報は含まれません。state を確認してください。これが running に変わったら、サーバーの準備完了です。

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

"running"

これで、作成時のレスポンスから保存した connectionString プロパティを使って、たとえば 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=#

psql を終了するには、\q と入力します。

更新

patch API は、RFC 7396 の JSON Merge Patch を使用して、Managed Postgres サービスのプロパティの一部を更新できます。複雑なデプロイメントでは、タグが特に重要になることがあります。その場合は、リクエストでタグだけを送信してください:

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

返却されるデータには、新しいタグが含まれているはずです：

{
  "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 では、patch API でサポートされていないプロパティを更新するための追加のエンドポイントが提供されています。たとえば、Postgres configuration を更新するには、 config API を使用します。

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

出力には、更新後の設定に加えて、変更による影響を説明するメッセージも表示されます：

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

削除

Postgres サービスを削除するには、delete API を使用します。

Postgres サービスを削除すると、サービス自体とその中のすべてのデータが完全に削除されます。サービスを削除する前に、必ずバックアップを取得するか、レプリカをプライマリに昇格させてください。

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

成功した場合、レスポンスではステータスコード 200 が返されます。例:

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

監視

Prometheus 互換のエンドポイントが 2 つあり、ClickHouse Managed Postgres サービスの CPU、メモリ、I/O、接続、およびトランザクションのメトリクスを公開しています。1 つは組織内のすべてのサービスのメトリクスを返し、もう 1 つは単一のサービスのメトリクスを返します。設定については Prometheus エンドポイントページを、メトリクスの一覧についてはメトリクスリファレンスを参照してください。

クエリインサイト

Cloud Console のクエリインサイトタブの各ステートメントのテレメトリーは、プログラムからも利用できます。2 つのエンドポイントにより、サービス上の最も遅いクエリパターンを取得できます。1 つは影響度順にすべてのパターンを一覧表示し、もう 1 つは単一のパターンとその最近の実行結果を返します。

低速クエリパターンの一覧

スローパターン API は、一定の時間範囲内で観測された最も遅いクエリパターンの集約メトリクスを返します。時間範囲の指定は必須です。 RFC 3339 形式のタイムスタンプとして from_date と to_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/slowQueryPatterns?from_date=$FROM&to_date=$TO" \
    | jq

結果はデフォルトで、total_duration の降順で、最もコストの高いパターンから返されます。sort_by を使うと別の指標 (たとえば p99_duration、call_count、または total_wal_bytes) でソートでき、sort_order で並び順を反転できます。db_name、db_user、 db_operation、および app フィルターで対象を絞り込み、limit と offset でページ送りできます。各結果は 1 つの正規化されたパターンで、リテラルは取り除かれ、実行時間はマイクロ秒単位で示されます:

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

queryId は正規化されたステートメントの符号付き 64 ビットハッシュなので、しばしば負の値になります。単一のパターンを取得するには、先頭の - も含めてその値をそのまま渡してください。

低速クエリパターンを取得する

リストレスポンスの queryId を低速クエリパターン API に渡すと、そのパターンの集約メトリクスと、直近の個別実行結果を取得できます。パターンの識別に必要な db_name、db_user、db_operation は必須です。

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

レスポンスには、aggregate の下にあるリストエンドポイントと同じ集計に加えて、 recentExecutions 配列が含まれます。各実行には、実行ごとの完全なカウンター — shared および temp block の I/O、CPU の user および system time、並列 worker 数、JIT、WAL — が含まれます。これらは、コンソールの detail flyout で内訳が表示されるものと同じカウンターです。

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

この例では簡潔にするため、両方のオブジェクトをトリムしています。API は per-execution counters に記載されている完全なカウンターセットを返します。

サーバーログ

Cloud Console のログビューアで表示される PostgreSQL サーバーログは、プログラムからも利用できます。logs API は、指定した期間内のサービスの個々のログエントリを返します。クエリインサイトと同様に、この期間の指定は必須のため、 from_date と to_date を RFC 3339 形式のタイムスタンプとして渡します。期間は 30 日を超えることはできず、to_date は 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

エントリは新しい順に返されます。sort_order (asc または desc) で順序を反転できます。severity (例: ERROR、 WARNING、LOG) で単一の重大度に絞り込み、body_contains でログボディ内の大文字・小文字を区別する部分文字列を検索し、limit と offset で結果をページングできます。各エントリには timestamp、severity、生データの body が含まれます。ボディは常に文字列です。構造化ログ行は JSON エンコードされて返され、プレーンな行はそのまま返されます。

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

エンドポイントでは合計件数を返すのではなく、limit と offset を使用してページ分割します。ページが limit 未満のエントリを返すまで、offset を増やしてください。

はじめに

機能

料金

ClickHouse Integration

移行

監視

よくある質問

API キー

Organization ID

CRUD

作成

取得

更新

削除

監視

クエリインサイト

低速クエリパターンの一覧

低速クエリパターンを取得する

サーバーログ

​API キー

​Organization ID

​CRUD

​作成

​取得

​更新

​削除

​監視

​クエリインサイト

​低速クエリパターンの一覧

​低速クエリパターンを取得する

​サーバーログ

API キー

Organization ID

CRUD

作成

取得

更新

削除

監視

クエリインサイト

低速クエリパターンの一覧

低速クエリパターンを取得する

サーバーログ