Managed Postgres OpenAPI

OpenAPI로 Managed Postgres 서비스를 관리합니다

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가 필요합니다.

1. 콘솔의 왼쪽 하단에서 조직 이름을 선택합니다.
2. Organization details를 선택합니다.
3. 조직 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:[e-mail]: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에 문서화된 전체 카운터 세트를 반환합니다.