Для 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 — личный ключ
curl "https://vibecode.bitrix24.tech/v1/infra/servers/APP_ID/db/schema" \
-H "X-Api-Key: YOUR_API_KEY"
curl — OAuth-приложение
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 — личный ключ
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-приложение
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 МиБ. Тогда в ответе только часть таблиц |
Пример ответа
{
"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:
{
"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.