Войти

API v2 и реальные пользовательские сценарии

Stable

Какие публичные маршруты Control Plane важны пользователю, какие новые runtime‑поля появились у БД и как читать autoscaler через API.

Обновлено: 21 марта 2026 г.

Публичный пользовательский интерфейс Control Plane — это API v2. Именно через него работают Console, CLI и внешние интеграции.

Базовые правила

  • Base URL обычно выглядит так: https://<cp-host>/v2
  • авторизация передаётся как Authorization: Bearer <API_KEY>
  • PostgreSQL‑подключения приложений идут не в Control Plane, а в Gateway: postgres://...@<gateway-host>:5432/...

Что обычно делает пользователь

1. Создаёт tenant

POST /v2/tenants

В ответе обычно приходят:

  • tenant;
  • pg_user;
  • pg_password;
  • dsn_template.

2. Создаёт базу внутри tenant

POST /v2/tenants/:tenant/dbs

Минимально достаточно передать:

{
  "name": "app",
  "size": "L1"
}

Важно:

  • start_immediately отключён;
  • initial_scale для обычного managed‑сценария не используется;
  • база стартует на первом подключении через Gateway автоматически.

3. Получает tenant credentials повторно

GET /v2/tenants/:tenant/credentials

4. Читает состояние ресурсов

  • GET /v2/tenants
  • GET /v2/tenants/:tenant
  • GET /v2/tenants/:tenant/dbs
  • GET /v2/tenants/:tenant/dbs/:db
  • GET /v2/dbs/:id

Именно describe/list запросы теперь особенно полезны, потому что через них виден не только lifecycle базы, но и autoscaler‑состояние.

5. Удаляет ресурсы

  • DELETE /v2/tenants/:tenant/dbs/:db
  • DELETE /v2/tenants/:tenant?cascade=true

Удаление асинхронное, поэтому после запроса ресурс может некоторое время находиться в deleting.

6. Получает события каталога

GET /v2/events

Это поток Server‑Sent Events, который Console использует для почти realtime‑обновления состояний.

Что нового видно в ответе БД

Помимо классических полей state, size, current_scale и target_scale, у БД теперь есть полезные runtime‑поля autoscaler:

  • current_profile
  • target_profile
  • candidate_profile
  • candidate_worker_id
  • candidate_writer_term
  • scale_state
  • freeze_new_checkouts
  • lease_control_epoch
  • autoscale_cooldown_until
  • scale_phase_started_at
  • scale_phase_deadline_at
  • scale_failure_reason

Практически это позволяет через API увидеть:

  • идёт ли handoff профиля;
  • подготовлен ли candidate writer;
  • заморожены ли новые checkout'ы;
  • сорвался ли переход и почему.

Как читать эти поля

  • current_scale / target_scale — writer выключен или включён.
  • current_profile / target_profile — на каком профиле сейчас writer и к какому профилю он идёт.
  • scale_state — стадия handoff.
  • freeze_new_checkouts=true — нормальная controlled‑фаза cutover, а не авария.
  • scale_failure_reason — главный быстрый диагноз, если autoscaler упал в FAILED.

Аккаунты и токены

В API v2 также есть маршруты для аккаунтов и ключей:

  • POST /v2/accounts
  • POST /v2/accounts/:account/api-keys
  • GET /v2/account/profile
  • POST /v2/account/contact
  • GET /v2/api-keys/me
  • POST /v2/api-keys/rotate
  • POST /v2/api-keys/revoke
  • GET /v2/billing/summary
  • POST /v2/account/delete

Что возвращается для подключения

При создании tenant или чтении credentials пользователь получает три главных поля:

  • pg_user
  • pg_password
  • dsn_template

Типовой шаблон выглядит так:

postgres://<pg_user>:<pg_password>@<gateway-host>:5432/<db-name>?sslmode=require

Хороший рабочий сценарий

Самый практичный пользовательский путь для automation выглядит так:

создать tenant -> сохранить pg_user/pg_password/dsn_template -> создать db -> подключить приложение через Gateway -> читать state и scale_state через describe
Почему SPG99АрхитектураПлан развитияДокументацияБлог