Для AI-агентов: markdown этой страницы — /docs-content/infra/database.md индекс документации — /llms.txt

База данных приложения

Эндпоинты для работы с SQLite-базой приложения в Галактике: чтение схемы и строк, SQL-запросы, правка строк, копии базы и восстановление из копии. База лежит в постоянном томе /data контейнера, и платформа работает с ней, не останавливая приложение.

Скоуп: vibe:infra

Получить сведения о базе

GET /v1/infra/servers/:id/db

Возвращает SQLite-файлы в томе данных приложения, файл по умолчанию, доступные ключу возможности и последнюю готовую копию файла по умолчанию. Вызов нужен перед чтением схемы и строк, чтобы узнать, какой файл открывать.

Условия доступа к базе и лимиты запросов — Когда база доступна и Лимиты.

Параметры

Параметр	Тип	Обяз.	Описание
Параметр`id` (path)	Типstring (UUID)	Обяз.да	ОписаниеID приложения с `kind` равным `GALAXY_APP`. Список: `GET /v1/infra/servers`
Параметр`file` (query)	Типstring	Обяз.нет	ОписаниеНепустая строка до 1024 байт в UTF-8. Параметр игнорируется: список файлов, `defaultFile`, `defaultFileExists` и `lastBackup` от него не зависят. Файл по умолчанию берётся из `VIBE_DB_PATH` контейнера, иначе `app.db`

Других параметров строки запроса эндпоинт не принимает: неизвестный параметр даёт 400 VALIDATION_ERROR.

Примеры

curl — личный ключ

Terminal

curl "https://vibecode.bitrix24.tech/v1/infra/servers/APP_ID/db" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth-приложение

Terminal

curl "https://vibecode.bitrix24.tech/v1/infra/servers/APP_ID/db" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — личный ключ

javascript

const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${appId}/db`,
  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)
const { success, data, error } = await res.json()
if (!success) throw new Error(error.code)
if (!data.defaultFileExists) console.log('Приложение ещё не создало базу')
console.log(data.defaultFile, data.files)

JavaScript — OAuth-приложение

javascript

const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${appId}/db`,
  {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)
const { success, data, error } = await res.json()
if (!success) throw new Error(error.code)
console.log(data.defaultFile, data.files)

Поля ответа

Поле	Тип	Описание
Поле`success`	Типboolean	Описание`true` при успешном ответе
Поле`data.files`	Типarray	ОписаниеНайденные SQLite-файлы, по алфавиту. Пустой массив, если тома нет или в нём нет баз
Поле`data.files[].file`	Типstring	ОписаниеПуть к файлу относительно `/data`. Это значение передаётся в параметр `file` других эндпоинтов раздела
Поле`data.files[].sizeBytes`	Типnumber	ОписаниеРазмер основного файла базы в байтах, без файлов журнала `-wal` и `-shm`
Поле`data.defaultFile`	Типstring	ОписаниеФайл по умолчанию: значение `VIBE_DB_PATH` из контейнера приложения без префикса `/data/`, иначе `app.db`
Поле`data.defaultFileExists`	Типboolean	ОписаниеСуществует ли файл по умолчанию
Поле`data.truncated`	Типboolean	Описание`true`, если обход тома остановлен до конца: в томе больше 1000 записей, найдено 500 файлов, вложенность каталогов больше 8 уровней или список приблизился к 1 МиБ
Поле`data.capabilities.read`	Типboolean	ОписаниеЧтение базы. Всегда `true`
Поле`data.capabilities.write`	Типboolean	ОписаниеЗапись в базу. `false` для ключа в режиме «только чтение»
Поле`data.capabilities.backups`	Типboolean	ОписаниеРабота с копиями. Всегда `true`
Поле`data.lastBackup`	Типobject \| null	ОписаниеПоследняя копия файла по умолчанию в статусе `COMPLETED`. `null`, если таких копий нет
Поле`data.lastBackup.id`	Типstring	ОписаниеID копии. Передаётся в `POST /db/restore`
Поле`data.lastBackup.sourceAppId`	Типstring	ОписаниеID приложения, с которого снята копия
Поле`data.lastBackup.platformPaid`	Типboolean	Описание`true`, если хранение копии оплачивает платформа
Поле`data.lastBackup.captureScope`	Типstring	ОписаниеЧто скопировано. Всегда `SQLITE` — один файл базы
Поле`data.lastBackup.status`	Типstring	ОписаниеСтатус копии. Здесь всегда `COMPLETED`
Поле`data.lastBackup.triggerType`	Типstring	ОписаниеПричина копии: `MANUAL`, `SCHEDULED`, `PRE_CHANGE`, `PRE_DELETE`
Поле`data.lastBackup.file`	Типstring \| null	ОписаниеПуть скопированного файла относительно `/data`
Поле`data.lastBackup.sizeBytes`	Типstring \| null	ОписаниеРазмер копии в байтах, десятичное число строкой
Поле`data.lastBackup.createdAt`	Типstring (ISO 8601)	ОписаниеКогда копия поставлена в очередь
Поле`data.lastBackup.completedAt`	Типstring (ISO 8601) \| null	ОписаниеКогда копия готова
Поле`data.lastBackup.expiresAt`	Типstring (ISO 8601) \| null	ОписаниеКогда копия будет удалена
Поле`data.lastBackup.errorCode`	Типstring \| null	ОписаниеКод ошибки копии. У готовой копии `null`

Те же поля у каждой копии в списке копий.

Пример ответа

JSON

{
  "success": true,
  "data": {
    "files": [
      {
        "file": "app.db",
        "sizeBytes": 20480
      }
    ],
    "defaultFile": "app.db",
    "defaultFileExists": true,
    "truncated": false,
    "capabilities": {
      "read": true,
      "write": true,
      "backups": true
    },
    "lastBackup": {
      "id": "3f6d2a91-8b4e-4c17-a5d0-9e1b7c4f2a68",
      "sourceAppId": "7c2b1f08-3a4d-4e91-9b6c-2f5e8a1d0c33",
      "platformPaid": false,
      "captureScope": "SQLITE",
      "status": "COMPLETED",
      "triggerType": "MANUAL",
      "file": "app.db",
      "sizeBytes": "937",
      "createdAt": "2026-10-20T08:26:17.942Z",
      "completedAt": "2026-10-20T08:28:00.046Z",
      "expiresAt": "2026-10-27T08:28:00.046Z",
      "errorCode": null
    }
  }
}

Пример ответа при ошибке

503 — на хосте галактики нет служебного образа для чтения базы: