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

Получить схему базы

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

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

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

Параметры

Параметр Тип Обяз. По умолч. Описание
Параметрid (path) Типstring (UUID) Обяз.да По умолч.— ОписаниеID приложения с kind равным GALAXY_APP. Список: GET /v1/infra/servers
Параметрfile (query) Типstring Обяз.нет По умолч.data.defaultFile из GET /db ОписаниеПуть к файлу базы относительно /data, до 1024 байт в UTF-8. Список файлов — data.files[].file в GET /db. Абсолютный путь, сегменты . и .., символьные ссылки не принимаются

Другие параметры строки запроса дают 400 VALIDATION_ERROR.

Примеры

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

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

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

Terminal
curl "https://vibecode.bitrix24.tech/v1/infra/servers/APP_ID/db/schema" \
  -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/schema`,
  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)
const { success, data, error } = await res.json()
if (!success) throw new Error(error.code)
for (const t of data.tables) {
  console.log(t.name, t.type, t.editability.editable ? 'правится' : t.editability.reason)
}

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

javascript
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${appId}/db/schema`,
  {
    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.tables.map(t => t.name))

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean Описаниеtrue при успешном ответе
Полеdata.file Типstring ОписаниеПуть прочитанного файла относительно /data
Полеdata.tables Типarray ОписаниеТаблицы и представления, по алфавиту. Служебные таблицы SQLite с именем на sqlite_ не входят
Полеdata.tables[].name Типstring ОписаниеИмя таблицы или представления. Передаётся в :table при чтении строк
Полеdata.tables[].type Типstring Описаниеtable — таблица, view — представление
Полеdata.tables[].columns Типarray ОписаниеКолонки в порядке объявления, включая скрытые и вычисляемые
Полеdata.tables[].columns[].name Типstring ОписаниеИмя колонки
Полеdata.tables[].columns[].type Типstring ОписаниеТип колонки так, как он объявлен в схеме. Пустая строка, если тип не объявлен
Полеdata.tables[].columns[].notNull Типboolean ОписаниеОбъявлено ли ограничение NOT NULL
Полеdata.tables[].columns[].defaultValue Типstring | null ОписаниеВыражение значения по умолчанию текстом, например CURRENT_TIMESTAMP или 1. null, если значения по умолчанию нет
Полеdata.tables[].columns[].primaryKeyPosition Типinteger ОписаниеНомер колонки в первичном ключе, начиная с 1. 0 — колонка не входит в ключ
Полеdata.tables[].columns[].hidden Типinteger Описание0 — обычная колонка, 1 — скрытая колонка виртуальной таблицы, 2 — вычисляемая колонка VIRTUAL, 3 — вычисляемая колонка STORED
Полеdata.tables[].indexes Типarray ОписаниеИндексы таблицы
Полеdata.tables[].indexes[].name Типstring ОписаниеИмя индекса
Полеdata.tables[].indexes[].unique Типboolean ОписаниеУникальный ли индекс
Полеdata.tables[].indexes[].origin Типstring ОписаниеОткуда индекс: c — создан командой CREATE INDEX, u — ограничением UNIQUE, pk — первичным ключом
Полеdata.tables[].indexes[].partial Типboolean ОписаниеЧастичный ли индекс, то есть с условием WHERE
Полеdata.tables[].indexes[].columns Типarray ОписаниеКолонки индекса по порядку. null на месте выражения, если индекс построен по выражению
Полеdata.tables[].primaryKey Типarray ОписаниеКолонки первичного ключа по порядку. Пустой массив, если ключ не объявлен
Полеdata.tables[].editability.editable Типboolean ОписаниеМожно ли добавлять, изменять и удалять строки через API
Полеdata.tables[].editability.keyKind Типstring | null ОписаниеЧем адресуется строка: pk — первичным ключом, rowid — встроенным номером строки SQLite. null, если правка недоступна
Полеdata.tables[].editability.keyColumns Типarray ОписаниеКолонки, из которых строится ключ строки. Для rowid — одна колонка rowid, _rowid_ или oid. Пустой массив, если правка недоступна
Полеdata.tables[].editability.reason Типstring | null ОписаниеПочему правка недоступна: view — представление, virtual_table — виртуальная таблица, no_stable_key — нет первичного ключа, а встроенный номер строки недоступен: таблица объявлена WITHOUT ROWID или имена rowid, _rowid_ и oid заняты колонками. null, если правка доступна
Полеdata.tables[].rowCountEstimate Типinteger | null ОписаниеОценка числа строк из статистики SQLite. null, если статистики нет
Полеdata.truncated Типboolean Описаниеtrue, если в базе больше 500 таблиц и представлений или схема приблизилась к 1 МиБ. Тогда в ответе только часть таблиц

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

JSON
{
  "success": true,
  "data": {
    "file": "app.db",
    "tables": [
      {
        "name": "active_customers",
        "type": "view",
        "columns": [
          { "name": "id", "type": "INTEGER", "notNull": false, "defaultValue": null, "primaryKeyPosition": 0, "hidden": 0 },
          { "name": "name", "type": "TEXT", "notNull": false, "defaultValue": null, "primaryKeyPosition": 0, "hidden": 0 }
        ],
        "indexes": [],
        "primaryKey": [],
        "editability": {
          "editable": false,
          "keyKind": null,
          "keyColumns": [],
          "reason": "view"
        },
        "rowCountEstimate": null
      },
      {
        "name": "customers",
        "type": "table",
        "columns": [
          { "name": "id", "type": "INTEGER", "notNull": false, "defaultValue": null, "primaryKeyPosition": 1, "hidden": 0 },
          { "name": "name", "type": "TEXT", "notNull": true, "defaultValue": null, "primaryKeyPosition": 0, "hidden": 0 },
          { "name": "email", "type": "TEXT", "notNull": false, "defaultValue": null, "primaryKeyPosition": 0, "hidden": 0 },
          { "name": "created_at", "type": "TEXT", "notNull": false, "defaultValue": "CURRENT_TIMESTAMP", "primaryKeyPosition": 0, "hidden": 0 }
        ],
        "indexes": [
          { "name": "idx_customers_email", "unique": false, "origin": "c", "partial": false, "columns": ["email"] }
        ],
        "primaryKey": ["id"],
        "editability": {
          "editable": true,
          "keyKind": "pk",
          "keyColumns": ["id"],
          "reason": null
        },
        "rowCountEstimate": null
      },
      {
        "name": "order_items",
        "type": "table",
        "columns": [
          { "name": "order_id", "type": "INTEGER", "notNull": true, "defaultValue": null, "primaryKeyPosition": 1, "hidden": 0 },
          { "name": "line", "type": "INTEGER", "notNull": true, "defaultValue": null, "primaryKeyPosition": 2, "hidden": 0 },
          { "name": "sku", "type": "TEXT", "notNull": false, "defaultValue": null, "primaryKeyPosition": 0, "hidden": 0 },
          { "name": "qty", "type": "INTEGER", "notNull": false, "defaultValue": "1", "primaryKeyPosition": 0, "hidden": 0 }
        ],
        "indexes": [
          { "name": "sqlite_autoindex_order_items_1", "unique": true, "origin": "pk", "partial": false, "columns": ["order_id", "line"] }
        ],
        "primaryKey": ["order_id", "line"],
        "editability": {
          "editable": true,
          "keyKind": "pk",
          "keyColumns": ["order_id", "line"],
          "reason": null
        },
        "rowCountEstimate": null
      }
    ],
    "truncated": false
  }
}

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

409 — работающее приложение закрыло соединение с базой в режиме WAL:

JSON
{
  "success": false,
  "error": {
    "code": "APP_DB_WAL_CLOSED",
    "message": "A running application must keep its database connection open for reads and copies. A sleeping application can be read and copied with the connection closed.",
    "details": {
      "source": "sqlite",
      "hint": "A running application must keep its database connection open for reads and copies. A sleeping application can be read and copied with the connection closed."
    }
  }
}

Повтор запроса не поможет, пока работающее приложение не откроет соединение снова. Как держать соединение открытым — Когда база доступна.

Ошибки

HTTP Код Описание
HTTP400 КодVALIDATION_ERROR ОписаниеПередан неизвестный параметр или file пустой либо длиннее 1024 байт
HTTP400 КодAPP_DB_INVALID_FILE Описаниеfile — абсолютный путь, содержит . или .., ведёт через символьную ссылку или указывает не на базу SQLite
HTTP400 КодAPP_DB_UNSUPPORTED_PLACEMENT ОписаниеПриложение размещено не в Галактике
HTTP401 КодMISSING_API_KEY ОписаниеНе передан заголовок X-Api-Key
HTTP401 КодINVALID_API_KEY ОписаниеКлюч не опознан
HTTP402 КодBILLING_FROZEN ОписаниеХост галактики спит, а баланс заморожен — разбудить хост нельзя
HTTP403 КодINFRA_SCOPE_REQUIRED ОписаниеУ ключа нет скоупа vibe:infra
HTTP403 КодAPP_DB_DISABLED ОписаниеРабота с базой не включена для портала
HTTP403 КодSERVER_WAKE_BLOCKED ОписаниеХост галактики спит, и пробуждение для него запрещено
HTTP404 КодNOT_FOUND ОписаниеПриложение не существует, удалено или недоступно этому ключу
HTTP404 КодAPP_DB_NOT_FOUND ОписаниеНет тома /data или файла базы — приложение ещё не создало базу
HTTP409 КодAPP_DB_WAL_CLOSED ОписаниеБаза в режиме WAL, а файлов -wal и -shm нет: работающее приложение закрыло соединение. Заголовка Retry-After нет
HTTP409 КодAPP_DB_BUSY ОписаниеХост занят другой операцией, не подключился за 10 секунд или база заблокирована записью приложения. Ответ несёт заголовок Retry-After
HTTP422 КодAPP_DB_CORRUPT ОписаниеПроверка целостности базы не пройдена
HTTP422 КодAPP_DB_QUERY_TIMEOUT ОписаниеЧтение схемы не уложилось в 5 секунд
HTTP422 КодAPP_DB_SQL_ERROR ОписаниеВ таблице больше 256 колонок или больше 256 индексов, error.details.reason равен other
HTTP429 КодRATE_LIMITED ОписаниеПревышен лимит запросов на чтение для портала — Лимиты. Пауза — в заголовке Retry-After
HTTP503 КодAPP_DB_TOOL_UNAVAILABLE ОписаниеХост не подготовлен к чтению базы или временно недоступен. Ответ несёт заголовок Retry-After. Подготовка — Подготовить хост
HTTP503 Кодuser_self_deletion_pending ОписаниеВладелец ключа удаляет свой аккаунт на этом портале

Полный список общих ошибок API — Ошибки.

Известные особенности

  • Число строк не считается. rowCountEstimate берётся из таблицы статистики sqlite_stat1, которую заполняет команда ANALYZE в самом приложении. Подсчёт строк по таблице вызов не выполняет, поэтому без статистики приходит null, а оценка отстаёт от данных на время с последнего ANALYZE.

Смотрите также