# База данных

> Одна база PostgreSQL на проект: миграции, раздел «Данные», чтение агентом, лимит объёма.

> Оглавление всей документации: https://docs.getxflow.com/llms.txt

У каждого проекта одна база PostgreSQL на все его приложения и функции. Браузер в базу не
ходит: приложение зовёт [функцию](https://docs.getxflow.com/platform/functions.md), и какие строки увидит посетитель,
решает её код.

Строка подключения лежит в `DATABASE_URL`. Платформа передаёт её только функциям, которые её
упоминают, и сама направляет запросы в базу проекта. В SQL пишут простые имена таблиц:
`select * from tasks`.

## Миграции

Миграция это SQL-файл в `migrations/` в корне проекта: `migrations/0001_init.sql`,
`migrations/0002_orders.sql`.

- Файлы применяются по порядку имён, каждый один раз.
- Применённый файл не правят: платформа откажет, если под тем же именем лежит другой текст.
  Любое изменение схемы это новый файл.
- `BEGIN` и `COMMIT` не нужны и отклоняются: каждая миграция идёт в своей транзакции.

| Команда | Что делает |
|---|---|
| `xflow db migrate` | сохраняет корень проекта и применяет новые миграции |
| `xflow db migrate --dry-run` | показывает, что будет применено, без изменений |
| `xflow db status` | какие миграции применены, какие ждут |
| `xflow db schema [таблица]` | что сейчас лежит в базе |

### Операции, которые уничтожают данные

Истории базы и резервных копий нет. Миграция, которая удаляет или опустошает таблицу,
удаляет столбец или строки (`DROP TABLE`, `DROP COLUMN`, `TRUNCATE`, `DELETE`), проходит только
при двух условиях:

- у команды флаг `--allow-destructive`;
- у ключа агента включено право «Удалять данные» (по умолчанию выключено, включает человек в
  разделе «AI агент»).

Платформа судит по результату, а не по тексту SQL: без обоих условий такую миграцию она
откатывает. С ними перед миграцией сохраняет затронутые таблицы (до 50 000 строк каждая) на
7 дней. Вернуть копию можно только по запросу человека, команды нет.

## Чтение данных

Блок «Данные» на главной проекта: таблицы, строки постранично, значение ячейки целиком с
копированием, панель SQL для чтения (до 500 строк в ответе). Изменить строку или схему отсюда
нельзя. Агент читает командой:

```bash
xflow db query 'select * from orders order by created_at desc limit 20'
```

Запрос идёт в транзакции только для чтения. Строк выводится столько, сколько просит `limit` в
запросе: 50 без него, не больше 300. `--json` печатает длинные значения целиком. Запрос с
кавычками удобнее положить в `.sql` файл вне папки проекта: `xflow db query ../q.sql`.

## Объём базы сверх тарифа

Предел объёма баз организации задаёт [тариф](https://docs.getxflow.com/platform/billing.md), занятое показывают
`xflow whoami` и экран тарифа. Через сутки после превышения запись отключается:

| Что | Работает |
|---|---|
| чтение | да |
| изменение и удаление строк | да |
| новые строки, новые таблицы | нет |
| `xflow db migrate` | нет, ответ `db_write_locked` |

В шапке интерфейса появляется красная полоса «Запись в базу отключена». Функции, которые
добавляют строки, получают `permission denied` (код 42501). Выход: удалить лишнее (миграцией с
`DELETE` или функцией) или расширить объём на экране тарифа. Объём проверяется раз в час,
запись включается, когда занятое ниже 90% предела. Кнопка «Проверить снова» в полосе
проверяет сразу.

## Свой сервер

Базу проекта можно перенести на отдельную машину организации: [Свои серверы баз](https://docs.getxflow.com/platform/db-servers.md).