Managed Postgres OpenAPI - ClickHouse Documentation

ClickHouse OpenAPI를 사용하면 ClickHouse 서비스와 마찬가지로 Managed Postgres 서비스를 프로그래밍 방식으로 제어할 수 있습니다. 동일한 API는 서비스 메트릭을 스크레이핑할 수 있는 [Prometheus 엔드포인트]도 제공합니다. 이미 OpenAPI에 익숙하다면 [API Key]를 발급받아 Managed Postgres API 참조로 바로 이동하십시오. 그렇지 않다면, 아래에서 간단히 살펴보십시오.

API Keys

ClickHouse OpenAPI를 사용하려면 인증이 필요합니다. 생성 방법은 API keys를 참조하십시오. 그런 다음 아래와 같이 basic auth 자격 증명을 사용하십시오:

KEY_ID=mykeyid
KEY_SECRET=mykeysecret

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

조직 ID

다음 단계에서는 조직 ID가 필요합니다.

콘솔의 왼쪽 하단에서 조직 이름을 선택합니다.
Organization details를 선택합니다.
조직 ID 오른쪽의 복사 아이콘을 눌러 클립보드에 바로 복사합니다.

CRUD

Postgres 서비스의 생명주기를 살펴보겠습니다.

생성

먼저 create API를 사용해 새 항목을 생성합니다. 요청의 JSON 본문에는 다음 속성이 필요합니다:

name: 새 Postgres 서비스의 이름
provider: 클라우드 제공업체 이름
region: 서비스를 배포할 제공업체 네트워크 내 리전
size: VM 크기
storageSize: VM의 스토리지 크기

이 속성들에 사용할 수 있는 값은 create API 문서를 참조하십시오. 또한 기본값인 17 대신 Postgres 18을 지정하겠습니다:

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

이제 이 데이터를 사용해 새 인스턴스를 생성하세요. 이때는 Content-Type 헤더가 필요합니다:

curl -s --user "$KEY_ID:$KEY_SECRET" -H 'Content-Type: application/json' \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres" \
    -d "$create_data" | jq

성공하면 새 인스턴스를 생성하고, 연결 정보를 포함한 해당 인스턴스 정보를 반환합니다:

{
  "result": {
    "id": "pg7myrd1j06p3gx4zrm2ze8qz6",
    "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=pg7myrd1j06p3gx4zrm2ze8qz6
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 "$(
    curl -s --user "$KEY_ID:$KEY_SECRET" \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID" \
    | 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": "$PG_ID",
  "name": "my postgres",
  "provider": "aws",
  "region": "us-west-2",
  "postgresVersion": "18",
  "size": "r8gd.large",
  "storageSize": 118,
  "haType": "none",
  "tags": [
    {
      "key": "Environment",
      "value": "production"
    }
  ],
  "connectionString": "postgres://postgres:vV6cfEr2p_-TzkCDrZOx@my-postgres-6d8d2e3e.$PG_ID.c0.us-west-2.aws.pg.clickhouse-dev.com:5432/postgres?channel_binding=require",
  "username": "postgres",
  "password": "vV6cfEr2p_-TzkCDrZOx",
  "hostname": "my-postgres-6d8d2e3e.$PG_ID.c0.us-west-2.aws.pg.clickhouse-dev.com",
  "isPrimary": true,
  "state": "running"
}

삭제

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개의 엔드포인트에서 Managed Postgres 서비스의 CPU, 메모리, I/O, 연결, 트랜잭션 메트릭을 제공합니다. 하나는 조직의 모든 서비스에 대한 메트릭을 반환하고, 다른 하나는 단일 서비스에 대한 메트릭을 반환합니다. 설정 방법은 [Prometheus 엔드포인트] 페이지를, 전체 메트릭 목록은 [메트릭 참고]를 참조하십시오.

쿼리 인사이트

클라우드 콘솔의 [쿼리 인사이트] 탭에서 사용하는 SQL 문별 텔레메트리는 프로그래밍 방식으로도 사용할 수 있습니다. 2개의 엔드포인트가 서비스에서 가장 느린 쿼리 패턴을 제공합니다. 하나는 영향도 순으로 정렬된 모든 패턴을 나열하고, 다른 하나는 최근 실행 내역과 함께 단일 패턴을 반환합니다.

느린 쿼리 패턴 목록

slow patterns API는 지정한 시간 구간에서 관찰된 가장 느린 쿼리 패턴의 집계 메트릭을 반환합니다. 시간 구간 지정은 필수이므로 from_date와 to_date를 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

결과는 기본적으로 total_duration을 기준으로 내림차순 정렬되며, 비용이 가장 큰 패턴이 먼저 표시됩니다. sort_by를 사용해 다른 카운터(예: p99_duration, call_count, total_wal_bytes)를 기준으로 정렬하고, sort_order로 정렬 방향을 반대로 바꿀 수 있습니다. db_name, db_user, db_operation, app 필터로 범위를 좁히고, limit 및 offset으로 페이지를 나눠 볼 수 있습니다. 각 결과는 하나의 정규화된 패턴이며, 리터럴은 제거되고 지속 시간은 마이크로초 단위로 보고됩니다:

{
  "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는 정규화된 SQL 문의 부호 있는 64비트 해시이므로 음수인 경우가 많습니다. 단일 pattern을 가져오려면 앞의 -를 포함한 값을 그대로 다시 전달하세요.

느린 쿼리 패턴 조회

목록 응답의 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

응답에는 목록 endpoint의 aggregate에 있는 것과 동일한 집계와 recentExecutions 배열이 포함됩니다. 각 실행에는 실행별 전체 카운터, 즉 공유 및 임시 블록 I/O, CPU 사용자 및 시스템 시간, 병렬 workers, 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에 문서화된 전체 카운터 세트를 반환합니다.

​API Keys

​조직 ID

​CRUD

​생성

​조회

​업데이트

​삭제

​모니터링

​쿼리 인사이트

​느린 쿼리 패턴 목록

​느린 쿼리 패턴 조회

API Keys

조직 ID

CRUD

생성

조회

업데이트

삭제

모니터링

쿼리 인사이트

느린 쿼리 패턴 목록

느린 쿼리 패턴 조회