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

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

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

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

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

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.

Скрытие учетных данных с 31 июля 2026 годаНачиная с 31 июля 2026 года API больше не возвращает свойства password и connectionString в ответах. Они отображаются только в ответе create и в ответе password reset, если запрос не содержал пароль. Рекомендуем сохранить учетные данные из ответа create. Если вы управляете сервисами через Terraform, до 31 июля 2026 года обновите provider до версии v3.21.0 или новее (см. справочник по Terraform).

Создание

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

name: имя нового сервиса Postgres
provider: имя облачного провайдера
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. Сохраните ответ, чтобы получить доступ к возвращённым учётным данным:

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, возвращаемый при создании (но без свойств password и connectionString после 31 июля 2026 года), но следите за 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"
    }
  ],
  "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"
}

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

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

Функции

Бенчмарки

Тарифы

Интеграция ClickHouse

Миграции

Мониторинг

FAQ

Ключи API

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

CRUD

Создание

Чтение

Обновление

Удаление

Мониторинг

Query insights

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

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

​Ключи API

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

​CRUD

​Создание

​Чтение

​Обновление

​Удаление

​Мониторинг

​Query insights

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

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

Ключи API

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

CRUD

Создание

Чтение

Обновление

Удаление

Мониторинг

Query insights

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

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