Перейти к основному содержимому
Перейти к основному содержимому

OpenAPI для Managed Postgres

Beta

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

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

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

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

  • 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:

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": "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 "$(
    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 поддерживает обновление части свойств сервиса Managed 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], используйте 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 конечные точки предоставляют метрики CPU, памяти, I/O, подключений и транзакций для сервисов Managed Postgres: одна возвращает метрики для всех сервисов в организации, другая — для одного сервиса. Сведения о настройке см. на странице конечная точка Prometheus, а полный список метрик — в metrics reference.