> ## 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 > Управляйте сервисами Managed Postgres с помощью нашего OpenAPI 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](/ru/products/cloud/features/admin-features/api) для программного управления сервисами Managed Postgres так же, как и сервисами ClickHouse. Этот же API также предоставляет \[конечную точку Prometheus] для сбора метрик сервиса. Уже знакомы с [OpenAPI]? Получите свои \[ключи API] и сразу переходите к [справочнику API Managed Postgres][pg-openapi]. Если нет, ниже — краткий обзор.
## Ключи API
Для использования ClickHouse OpenAPI требуется аутентификация; о том, как создать \[ключи API], см. в соответствующем разделе. Затем используйте их, передав учетные данные 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 ```
## Идентификатор организации
Далее вам понадобится идентификатор вашей организации. 1. Выберите название своей организации в левом нижнем углу консоли. 2. Выберите **Сведения об организации**. 3. Нажмите значок копирования справа от **идентификатора организации**, чтобы сразу скопировать его в буфер обмена.
## CRUD
Рассмотрим жизненный цикл сервиса Postgres.
### Создание
Сначала создайте новый сервис с помощью [create API]. Для этого в JSON body запроса должны быть указаны следующие свойства: * `name`: имя нового сервиса Postgres * `provider`: имя облачного провайдера * `region`: регион в сети провайдера, в котором будет развернут сервис * `size`: размер VM * `storageSize`: размер хранилища для VM См. документацию [create API], чтобы узнать возможные значения этих свойств. Кроме того, укажем Postgres 18 вместо версии по умолчанию — 17: ```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=# ``` Введите `\q` для выхода из [psql].
### Обновление
[Patch API] поддерживает обновление части свойств управляемого сервиса Postgres с помощью JSON Merge Patch согласно [RFC 7396]. Для сложных развертываний особенно полезны могут быть теги; просто отправьте в запросе только их: ```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" } ```
### Удаление
Используйте \[API удаления], чтобы удалить сервис Postgres. При удалении сервиса 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 конечные точки предоставляют метрики ЦП, памяти, I/O, подключений и транзакций для сервисов Managed Postgres: одна возвращает метрики для всех сервисов в организации, другая — для одного сервиса. См. страницу \[конечная точка Prometheus] с инструкциями по настройке и \[справочник по метрикам] для полного списка метрик.
## Query insights
Телеметрия по отдельным операторам SQL, лежащая в основе вкладки [Query Insights] в облачной консоли, также доступна программно. Две конечные точки позволяют получить доступ к самым медленным шаблонам запросов в сервисе: одна возвращает список всех шаблонов, ранжированных по влиянию, другая — один шаблон вместе с его недавними выполнениями.
### Получить список шаблонов медленных запросов
\[API slow patterns] возвращает агрегированные метрики по самым медленным шаблонам запросов, наблюдавшимся в заданном временном интервале. Интервал обязателен — передайте `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` — это знаковый 64-битный хеш нормализованного оператора, поэтому он часто бывает отрицательным. Передайте его обратно дословно — включая начальный `-` и всё остальное, — чтобы получить один шаблон запроса.
### Получить шаблон медленного запроса
Передайте `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 ``` Ответ содержит те же агрегированные данные, что и конечная точка списка, в `aggregate`, а также массив `recentExecutions`. Каждое выполнение включает полный набор счётчиков по каждому выполнению — ввод-вывод общих и временных блоков, время CPU в пользовательском и системном режимах, параллельные воркеры, JIT и WAL — те же счётчики, которые \[выдвижная панель сведений] показывает в консоли: ```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 возвращает полный набор счётчиков, описанный в разделе [счётчики по каждому выполнению]. [ClickHouse OpenAPI]: /products/cloud/features/admin-features/api "Cloud API" [OpenAPI]: https://www.openapis.org "Инициатива OpenAPI" [API keys]: /products/cloud/features/admin-features/api/openapi "Управление ключами API" [Prometheus endpoint]: /products/managed-postgres/monitoring/prometheus "Конечная точка Prometheus для Managed Postgres" [metrics reference]: /products/managed-postgres/monitoring/metrics "Справочник метрик Managed Postgres" [pg-openapi]: /api-reference/organization/get-list-of-available-organizations#tag/Postgres "Спецификация OpenAPI для ClickHouse Cloud: 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 "Query Insights для Postgres" [detail flyout]: /products/managed-postgres/monitoring/query-insights#detail "Выдвижная панель сведений Query Insights" [счётчики по каждому выполнению]: /products/managed-postgres/monitoring/query-insights#counters "Счётчики Query Insights по каждому выполнению" [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 с недавними выполнениями"