Выполнить SQL на запись

POST /v1/infra/servers/:id/db/execute

Выполняет SQL-выражения на запись в SQLite-базе приложения одной транзакцией: изменяет строки, создаёт и меняет таблицы, индексы и представления.

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

Параметры

Поля запроса (body)

Неизвестное поле тела отклоняется с 400 VALIDATION_ERROR.

В sql отклоняются с 422 APP_DB_SQL_ERROR и причиной not_permitted: управление транзакциями и точками сохранения (BEGIN, COMMIT, ROLLBACK, SAVEPOINT), ATTACH и DETACH, PRAGMA, создание и удаление виртуальных таблиц, обращение к схемам кроме main, включая временные таблицы, функции load_extension, readfile, writefile и fts3_tokenizer. VACUUM тоже не выполняется: вызов идёт внутри транзакции, и выражение отклоняется с 422 APP_DB_SQL_ERROR.

Примеры

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

curl -X POST "https://vibecode.bitrix24.tech/v1/infra/servers/APP_ID/db/execute" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sql":"UPDATE notes SET body = ? WHERE id = ?","parameters":["updated",1]}'

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

curl -X POST "https://vibecode.bitrix24.tech/v1/infra/servers/APP_ID/db/execute" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sql":"UPDATE notes SET body = ? WHERE id = ?","parameters":["updated",1]}'

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

const url = `https://vibecode.bitrix24.tech/v1/infra/servers/${appId}/db/execute`
const headers = { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' }
const body = JSON.stringify({ sql: 'UPDATE notes SET body = ? WHERE id = ?', parameters: ['updated', 1] })

// Повторяется только 409 APP_DB_BACKUP_NOT_READY: в этом ответе SQL ещё не выполнялся
const deadline = Date.now() + 180_000
let result
while (Date.now() < deadline) {
  const res = await fetch(url, { method: 'POST', headers, body })
  result = await res.json()
  if (res.status !== 409 || result.error?.code !== 'APP_DB_BACKUP_NOT_READY') break
  const seconds = Number(res.headers.get('Retry-After')) || 1
  await new Promise(resolve => setTimeout(resolve, Math.max(seconds, 3) * 1000))
}
if (!result.success) throw new Error(result.error.code)
console.log(result.data.rowCount, result.data.backupId)

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

const url = `https://vibecode.bitrix24.tech/v1/infra/servers/${appId}/db/execute`
const headers = {
  'X-Api-Key': 'YOUR_APP_KEY',
  'Authorization': 'Bearer USER_SESSION_TOKEN',
  'Content-Type': 'application/json',
}
const body = JSON.stringify({ sql: 'UPDATE notes SET body = ? WHERE id = ?', parameters: ['updated', 1] })

const deadline = Date.now() + 180_000
let result
while (Date.now() < deadline) {
  const res = await fetch(url, { method: 'POST', headers, body })
  result = await res.json()
  if (res.status !== 409 || result.error?.code !== 'APP_DB_BACKUP_NOT_READY') break
  const seconds = Number(res.headers.get('Retry-After')) || 1
  await new Promise(resolve => setTimeout(resolve, Math.max(seconds, 3) * 1000))
}
if (!result.success) throw new Error(result.error.code)

Поля ответа

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

{
  "success": true,
  "data": {
    "file": "app.db",
    "rowCount": 1,
    "durationMs": 0.933,
    "statementCount": 1,
    "backupId": "d5e1b7a9-0f42-4c8d-9a3e-6b21c4f80e57"
  }
}

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

422 — выражение PRAGMA journal_mode=DELETE запрещено, транзакция откачена:

{
  "success": false,
  "error": {
    "code": "APP_DB_SQL_ERROR",
    "message": "SQL operation is not permitted",
    "details": {
      "reason": "not_permitted"
    }
  }
}

Ошибки

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

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

• Первый вызов только готовит защитную копию. Пока свежей копии для этого файла нет, вызов ставит её создание в очередь и отвечает 409 APP_DB_BACKUP_NOT_READY с details.backupId, details.retryAfterSeconds и заголовком Retry-After. Повторяйте тот же запрос: когда копия готова, повтор выполняет SQL и возвращает в data.backupId тот же ID. Готовая копия ждёт повтора 10 минут, позже следующий вызов готовит новую. Устройство защитных копий — Защитные копии перед записью.
• Повторы расходуют лимит записи. Каждый повтор после 409 учитывается в лимите запросов на запись (Лимиты), поэтому держите паузу не короче трёх секунд, даже когда Retry-After равен 1.
• Отказ копии приходит один раз. Если защитная копия не создалась, ближайший вызов получает причину с details.retryable: false, а следующий вызов уже ставит в очередь новую копию.
• Весь вызов — одна транзакция. Ошибка любого выражения или превышение 30 секунд откатывает все выражения вызова. Строки, которые возвращают SELECT и RETURNING, читаются до конца и отбрасываются: в ответ они не попадают. SQL и значения параметров в журнал аудита не записываются.
• Внешние ключи проверяются всегда. На время вызова платформа включает проверку внешних ключей, даже если само приложение её не включает. Нарушение ссылочной целостности откатывает вызов с причиной constraint_failed.
• Контейнер приложения не запускается. SQL выполняет служебный контейнер на хосте с тем же томом /data.
• Инструмент для AI-агентов повторяет только неготовую копию. Инструмент manage_app_db из MCP-сервера Вайбкод с action: "execute" принимает serverId, file, sql, parameters и сам повторяет только 409 APP_DB_BACKUP_NOT_READY. Общий срок ожидания — 180 секунд, пауза — по Retry-After, но не короче трёх секунд. Сетевую ошибку и APP_DB_WRITE_OUTCOME_UNKNOWN инструмент не повторяет. Отмена ожидания не доказывает, что уже отправленная запись откатилась.

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

• Выполнить SQL-запрос на чтение
• Получить список копий базы
• Восстановить базу из копии
• Получить статус подготовки хоста
• База данных приложения