ClickHouse Managed Postgres OpenAPI

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

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

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

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

Теперь его можно использовать в запросах, например:

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 body запроса должны быть указаны следующие свойства:

name: имя нового сервиса Postgres
provider: имя облачного провайдера: aws (или gcp в режиме закрытой предварительной версии)
region: регион в сети провайдера, в котором будет развернут сервис
size: размер VM

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

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

Введите \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": "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 configuration, используйте 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
}

Удаление

Используйте 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, подключений и транзакций для сервисов ClickHouse 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 возвращает полный набор счётчиков, описанный в разделе счётчики по каждому выполнению.

Серверные журналы

Серверные журналы PostgreSQL, доступные в средстве просмотра журналов в облачной консоли, также доступны программно. API журналов возвращает отдельные записи журнала для сервиса за временной интервал. Как и в Query Insights, указание интервала обязательно, поэтому передайте 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, а не общее количество; увеличивайте offset, пока страница не вернёт меньше limit записей.

Начало работы

Возможности

Цены

Интеграция с ClickHouse

Миграции

Мониторинг

Часто задаваемые вопросы

Ключи API

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

CRUD

Создание

Чтение

Обновление

Удаление

Мониторинг

Query insights

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

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

Серверные журналы

​Ключи API

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

​CRUD

​Создание

​Чтение

​Обновление

​Удаление

​Мониторинг

​Query insights

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

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

​Серверные журналы

Ключи API

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

CRUD

Создание

Чтение

Обновление

Удаление

Мониторинг

Query insights

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

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

Серверные журналы