Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

ClickHouse Managed Postgres OpenAPI

View as MarkdownEdit this pageReport an issueSet up docs MCP
Бета

Используйте 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

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

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

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

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

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: имя облачного провайдера
  • 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.

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 записей.

Navigation