Managed Postgres OpenAPI

Используйте ClickHouse OpenAPI для программного управления сервисами Managed Postgres так же, как и сервисами ClickHouse. Этот же API также предоставляет [конечную точку Prometheus] для сбора метрик сервиса. Уже знакомы с OpenAPI? Получите свои [ключи API] и сразу переходите к справочнику API Managed Postgres. Если нет, ниже — краткий обзор.

Ключи API

Для использования ClickHouse OpenAPI требуется аутентификация; о том, как создать [ключи API], см. в соответствующем разделе. Затем используйте их, передав учетные данные Basic Auth следующим образом:

KEY_ID=mykeyid
KEY_SECRET=mykeysecret

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

Идентификатор организации

Далее вам понадобится идентификатор вашей организации.

Выберите название своей организации в левом нижнем углу консоли.
Выберите Сведения об организации.
Нажмите значок копирования справа от идентификатора организации, чтобы сразу скопировать его в буфер обмена.

CRUD

Рассмотрим жизненный цикл сервиса Postgres.

Создание

Сначала создайте новый сервис с помощью create API. Для этого в JSON body запроса должны быть указаны следующие свойства:

name: имя нового сервиса Postgres
provider: имя облачного провайдера
region: регион в сети провайдера, в котором будет развернут сервис
size: размер VM
storageSize: размер хранилища для VM

См. документацию create API, чтобы узнать возможные значения этих свойств. Кроме того, укажем Postgres 18 вместо версии по умолчанию — 17:

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=# 

Введите \q для выхода из psql.

Обновление

Patch API поддерживает обновление части свойств управляемого сервиса Postgres с помощью JSON Merge Patch согласно RFC 7396. Для сложных развертываний особенно полезны могут быть теги; просто отправьте в запросе только их:

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"
}

Удаление

Используйте [API удаления], чтобы удалить сервис Postgres.

При удалении сервиса 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 конечные точки предоставляют метрики ЦП, памяти, I/O, подключений и транзакций для сервисов Managed Postgres: одна возвращает метрики для всех сервисов в организации, другая — для одного сервиса. См. страницу [конечная точка Prometheus] с инструкциями по настройке и [справочник по метрикам] для полного списка метрик.

Query insights

Телеметрия по отдельным операторам SQL, лежащая в основе вкладки Query Insights в облачной консоли, также доступна программно. Две конечные точки позволяют получить доступ к самым медленным шаблонам запросов в сервисе: одна возвращает список всех шаблонов, ранжированных по влиянию, другая — один шаблон вместе с его недавними выполнениями.

Получить список шаблонов медленных запросов

[API slow patterns] возвращает агрегированные метрики по самым медленным шаблонам запросов, наблюдавшимся в заданном временном интервале. Интервал обязателен — передайте 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 — это знаковый 64-битный хеш нормализованного оператора, поэтому он часто бывает отрицательным. Передайте его обратно дословно — включая начальный - и всё остальное, — чтобы получить один шаблон запроса.

Получить шаблон медленного запроса

Передайте 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

Ответ содержит те же агрегированные данные, что и конечная точка списка, в aggregate, а также массив recentExecutions. Каждое выполнение включает полный набор счётчиков по каждому выполнению — ввод-вывод общих и временных блоков, время CPU в пользовательском и системном режимах, параллельные воркеры, 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 возвращает полный набор счётчиков, описанный в разделе счётчики по каждому выполнению.

Get started

Features

Benchmarks

Pricing

ClickHouse Integration

Migrations

Monitoring

FAQ

Ключи API

Идентификатор организации

CRUD

Создание

Чтение

Обновление

Удаление

Мониторинг

Query insights

Получить список шаблонов медленных запросов

Получить шаблон медленного запроса

​Ключи API

​Идентификатор организации

​CRUD

​Создание

​Чтение

​Обновление

​Удаление

​Мониторинг

​Query insights

​Получить список шаблонов медленных запросов

​Получить шаблон медленного запроса

Ключи API

Идентификатор организации

CRUD

Создание

Чтение

Обновление

Удаление

Мониторинг

Query insights

Получить список шаблонов медленных запросов

Получить шаблон медленного запроса