ClickHouse Managed Postgres OpenAPI

ClickHouse OpenAPI를 사용하면 ClickHouse 서비스와 마찬가지로 ClickHouse Managed Postgres 서비스를 프로그래밍 방식으로 제어할 수 있습니다. 동일한 API는 서비스 메트릭을 스크레이핑할 수 있는 [Prometheus 엔드포인트]도 제공합니다. 이미 OpenAPI에 익숙하다면 [API Key]를 발급받아 ClickHouse 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 오른쪽의 복사 아이콘을 눌러 클립보드에 바로 복사합니다.

이제 다음과 같이 요청에 사용할 수 있습니다.

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: 클라우드 제공업체 이름: aws(또는 비공개 프리뷰의 gcp)
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 헤더가 필요합니다. 서비스 자격 증명을 포함하는 유일한 응답이므로 응답을 저장하세요 (요청에 비밀번호를 제공하지 않는 경우 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 구성]을 업데이트하려면 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, 연결, 트랜잭션 메트릭을 제공합니다. 하나는 조직의 모든 서비스에 대한 메트릭을 반환하고, 다른 하나는 단일 서비스에 대한 메트릭을 반환합니다. 설정 방법은 [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를 [slow pattern 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 배열이 포함됩니다. 각 실행에는 실행별 전체 카운터, 즉 공유 및 임시 블록 I/O, CPU 사용자 및 시스템 시간, 병렬 workers, JIT, WAL이 포함되며, 이는 콘솔의 상세 플라이아웃에서 세분화해 보여주는 것과 동일한 카운터입니다:

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

마이그레이션

모니터링

자주 묻는 질문

API Keys

조직 ID

CRUD

생성

조회

업데이트

삭제

모니터링

쿼리 인사이트

느린 쿼리 패턴 목록

느린 쿼리 패턴 조회

서버 로그

​API Keys

​조직 ID

​CRUD

​생성

​조회

​업데이트

​삭제

​모니터링

​쿼리 인사이트

​느린 쿼리 패턴 목록

​느린 쿼리 패턴 조회

​서버 로그

API Keys

조직 ID

CRUD

생성

조회

업데이트

삭제

모니터링

쿼리 인사이트

느린 쿼리 패턴 목록

느린 쿼리 패턴 조회

서버 로그