> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Managed Postgres OpenAPI > OpenAPI로 Managed Postgres 서비스를 관리합니다 export const galaxyOnClick = eventName => () => { try { if (typeof window !== "undefined" && window.galaxy && eventName) { window.galaxy.track(eventName, { interaction: "click" }); } } catch (e) {} }; export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => { if (link) { return Beta ; } return
Beta feature.  Learn more.
; }; [ClickHouse OpenAPI](/ko/products/cloud/features/admin-features/api)를 사용하면 ClickHouse 서비스와 마찬가지로 Managed Postgres 서비스를 프로그래밍 방식으로 제어할 수 있습니다. 동일한 API는 서비스 메트릭을 스크레이핑할 수 있는 \[Prometheus 엔드포인트]도 제공합니다. 이미 [OpenAPI]에 익숙하다면 \[API Key]를 발급받아 [Managed Postgres API 참조][pg-openapi]로 바로 이동하십시오. 그렇지 않다면, 아래에서 간단히 살펴보십시오.
## API Keys
ClickHouse OpenAPI를 사용하려면 인증이 필요합니다. 생성 방법은 [API keys]를 참조하십시오. 그런 다음 아래와 같이 basic auth 자격 증명을 사용하십시오: ```bash theme={null} 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을 지정하겠습니다: ```bash theme={null} create_data='{ "name": "my postgres", "provider": "aws", "region": "us-west-2", "postgresVersion": "18", "size": "r8gd.large", "storageSize": 118 }' ``` 이제 이 데이터를 사용해 새 인스턴스를 생성하세요. 이때는 Content-Type 헤더가 필요합니다: ```bash theme={null} 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 ``` 성공하면 새 인스턴스를 생성하고, 연결 정보를 포함한 해당 인스턴스 정보를 반환합니다: ```json theme={null} { "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`를 사용해 서비스를 다시 조회하세요: ```bash theme={null} 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`으로 바뀌면 서버가 준비된 것입니다: ```bash theme={null} curl -s --user "$KEY_ID:$KEY_SECRET" \ "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID" \ | jq .result.state ``` ```json theme={null} "running" ``` 이제 `connectionString` 속성을 사용해 예를 들어 [psql]로 연결할 수 있습니다: ```bash theme={null} $ 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 서비스 속성의 일부만 업데이트할 수 있도록 지원합니다. 복잡한 배포에서는 태그가 특히 유용할 수 있으며, 요청에는 태그만 보내면 됩니다: ```bash theme={null} 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 ``` 반환된 데이터에는 새로운 태그가 포함되어야 합니다: ```json theme={null} { "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 서비스를 삭제하면 서비스와 그 안의 모든 데이터가 완전히 제거됩니다. 서비스를 삭제하기 전에 반드시 백업이 준비되어 있거나 레플리카를 프라이머리로 승격해 두었는지 확인하십시오. ```bash theme={null} curl -sX DELETE --user "$KEY_ID:$KEY_SECRET" \ "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID" \ | jq ``` 성공 시 응답은 예를 들어 상태 코드 200을 반환합니다: ```json theme={null} { "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 형식의 타임스탬프로 전달하십시오: ```bash theme={null} 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`으로 페이지를 나눠 볼 수 있습니다. 각 결과는 하나의 정규화된 패턴이며, 리터럴은 제거되고 지속 시간은 마이크로초 단위로 보고됩니다: ```json theme={null} { "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`은 필수입니다: ```bash theme={null} 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]에서 세분화해 보여주는 것과 동일한 카운터입니다: ```json theme={null} { "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]에 문서화된 전체 카운터 세트를 반환합니다. [ClickHouse OpenAPI]: /products/cloud/features/admin-features/api "Cloud API" [OpenAPI]: https://www.openapis.org "OpenAPI Initiative" [API keys]: /products/cloud/features/admin-features/api/openapi "API Key 관리" [Prometheus endpoint]: /products/managed-postgres/monitoring/prometheus "Managed Postgres Prometheus 엔드포인트" [metrics reference]: /products/managed-postgres/monitoring/metrics "Managed Postgres 메트릭 참고" [pg-openapi]: /api-reference/organization/get-list-of-available-organizations#tag/Postgres "ClickHouse Cloud용 OpenAPI 사양: Postgres" [list API]: /api-reference/organization/get-list-of-available-organizations#tag/Postgres/operation/postgresServiceGetList "조직의 Postgres 서비스 목록 조회" [create API]: /api-reference/organization/get-list-of-available-organizations#tag/Postgres/operation/postgresServiceCreate "새 Postgres 서비스 생성" [psql]: https://www.postgresql.org/docs/current/app-psql.html "PostgreSQL Docs: psql — PostgreSQL 대화형 터미널" [patch API]: /api-reference/organization/get-list-of-available-organizations#tag/Postgres/operation/postgresServicePatch "PostgreSQL 서비스 업데이트" [RFC 7396]: https://www.rfc-editor.org/rfc/rfc7396 "RFC 7396: JSON Merge Patch" [Postgres configuration]: https://www.postgresql.org/docs/18/runtime-config.html "PostgreSQL Docs: 서버 구성" [config API]: /api-reference/organization/get-list-of-available-organizations#tag/Postgres/operation/postgresServiceSetConfig "Postgres 서비스 구성 업데이트" [delete API]: /api-reference/organization/get-list-of-available-organizations#tag/Postgres/operation/postgresServiceDelete "PostgreSQL 서비스 삭제" [Query Insights]: /products/managed-postgres/monitoring/query-insights "Postgres 쿼리 인사이트" [detail flyout]: /products/managed-postgres/monitoring/query-insights#detail "쿼리 인사이트 상세 플라이아웃" [per-execution counters]: /products/managed-postgres/monitoring/query-insights#counters "쿼리 인사이트 실행별 카운터" [slow patterns API]: /api-reference/organization/get-list-of-available-organizations#tag/Postgres/operation/slowQueryPatternsGetList "Postgres 느린 쿼리 패턴 목록 조회" [slow pattern API]: /api-reference/organization/get-list-of-available-organizations#tag/Postgres/operation/slowQueryPatternGet "최근 실행 내역이 포함된 Postgres 느린 쿼리 패턴 조회"