Что получится
ИИ-агент для SQL-базы данных отвечает на вопросы по данным: строит безопасный `SELECT`, выполняет его в read-only режиме, возвращает таблицу или вывод и объясняет результат человеческим языком.
Главный принцип: агент не должен иметь права менять production-базу. Его задача - анализ, отчеты, поиск аномалий и подготовка SQL для проверки, а не самостоятельные `UPDATE`, `DELETE`, `DROP` и миграции.
Где такой агент полезен
- Аналитика: “сколько заявок пришло за неделю по каналам”.
- Продажи: “какие сделки зависли без следующего шага”.
- Поддержка: “какие темы обращений растут быстрее всего”.
- Финансы: “найди платежи без закрывающих документов”.
- Продукт: “какие функции чаще используют активные пользователи”.
- Операционка: “покажи заказы, где доставка задерживается больше трех дней”.
Шаг 1. Определите границы доступа
Не подключайте агента к базе под админом. Создайте отдельного пользователя только для чтения и только к нужным таблицам или представлениям.
Минимальные правила:
- отдельный read-only пользователь;
- доступ только к нужной схеме;
- запрет на запись, DDL и служебные таблицы;
- лимиты времени выполнения;
- лимит строк в ответе;
- отдельное подключение к реплике или аналитической копии, если база нагруженная.
Если данные чувствительные, лучше создать специальные views, где уже скрыты персональные данные, токены, пароли, внутренние комментарии и лишние поля.
Шаг 2. Подготовьте schema context
Модель не должна угадывать структуру базы. Дайте ей компактное описание схемы.
В schema context стоит включить:
- названия доступных таблиц;
- поля и типы;
- первичные и внешние ключи;
- краткое описание бизнес-смысла таблиц;
- примеры допустимых фильтров;
- правила, какие таблицы нельзя соединять;
- список готовых безопасных запросов.
Не передавайте в промпт всю схему огромной базы. Лучше собрать только тот слой, с которым агент реально работает: например, `orders`, `customers_public`, `tickets`, `payments_view`.
Шаг 3. Начните с готовых SQL-шаблонов
Самый безопасный старт - не свободная генерация SQL, а библиотека параметризованных запросов.
Примеры:
- заявки по дням;
- продажи по каналам;
- открытые тикеты по приоритету;
- клиенты без активности;
- заказы с задержкой;
- платежи без статуса.
Агент выбирает шаблон, заполняет параметры и объясняет результат. Свободный SQL можно добавить позже, когда появятся тесты и SQL validator.
Шаг 4. Добавьте SQL validator
Перед выполнением запрос должен пройти проверку кодом, а не только промптом.
Проверяйте:
- разрешены только `SELECT` и безопасные `WITH`;
- нет `INSERT`, `UPDATE`, `DELETE`, `DROP`, `ALTER`, `TRUNCATE`, `CREATE`, `MERGE`;
- нет `COPY`, `GRANT`, `REVOKE`, `CALL` и опасных функций;
- есть `LIMIT`;
- запрос обращается только к разрешенным таблицам;
- нет `SELECT *`, если таблица содержит чувствительные поля;
- запрос не содержит несколько statements через `;`.
Если запрос не прошел проверку, агент должен объяснить, что нужно изменить, а не пытаться обойти правило.
Шаг 5. Выполняйте запрос в read-only транзакции
Даже если пользователь базы read-only, полезно дополнительно открывать транзакцию в режиме только чтения. В PostgreSQL read-only transaction запрещает команды записи и DDL. Это второй слой защиты.
Практический порядок:
- открыть соединение;
- установить statement timeout;
- начать read-only транзакцию;
- выполнить `EXPLAIN` или dry-run проверку;
- выполнить запрос;
- ограничить количество строк;
- закрыть транзакцию.
Не используйте `EXPLAIN ANALYZE` для любых запросов, которые теоретически могут иметь побочные эффекты. Для AI-агента обычно достаточно обычного `EXPLAIN` и лимитов.
Шаг 6. Не отдавайте модели все данные
Если запрос вернул 100 000 строк, не нужно отправлять их в LLM. Сначала агрегируйте данные кодом или SQL, а модели отдавайте summary, таблицу из ограниченного числа строк и метаданные.
Хороший ответ агента:
- показывает SQL;
- показывает небольшую таблицу результата;
- объясняет вывод;
- честно пишет ограничения;
- предлагает следующий уточняющий запрос;
- не раскрывает лишние персональные данные.
Если пользователь просит выгрузку, лучше дать CSV через отдельный экспорт с правами доступа, а не вставлять большие данные в чат.
Шаг 7. Обрабатывайте неоднозначные вопросы
Запрос “покажи лучших клиентов” непонятен. Лучших по выручке, марже, частоте покупок или LTV?
Агент должен уточнять:
- период;
- метрику;
- сегмент;
- статус;
- валюту;
- timezone;
- включать ли тестовые данные;
- считать ли возвраты.
Лучше один уточняющий вопрос, чем уверенный отчет с неверной бизнес-логикой.
Шаг 8. Добавьте словарь метрик
Модель может написать правильный SQL синтаксически, но неправильно посчитать бизнес-метрику.
Создайте словарь:
- что такое “выручка”;
- что такое “активный клиент”;
- какие статусы считаются успешными;
- как учитывать возвраты;
- какую дату брать: создания, оплаты или доставки;
- какие заказы исключать;
- как считать конверсию.
Этот словарь важнее промпта. Он делает ответы агента стабильными и одинаковыми для всей команды.
Шаг 9. Логируйте каждый запрос
Для SQL-агента audit log обязателен.
Сохраняйте:
- кто задал вопрос;
- исходный вопрос;
- сгенерированный SQL;
- выполненный SQL после проверки;
- время выполнения;
- количество строк;
- использованные таблицы;
- ошибку, если она была;
- версию промпта и модели.
Если агент работает с персональными или финансовыми данными, без журнала будет сложно разбирать ошибки и вопросы безопасности.
Шаг 10. Добавьте human approval для опасных действий
Даже если агент только читает базу, пользователь может попросить: “сформируй UPDATE, чтобы исправить статусы”. В таком случае агент может подготовить SQL как черновик, но не выполнять его.
Правило:
- read-only вопросы выполняются автоматически;
- write-запросы только генерируются как proposal;
- выполнение write-запросов делает человек через обычный процесс ревью;
- миграции, массовые изменения и удаление данных запрещены для агента.
Так агент помогает, но не становится неуправляемым админом базы.
Шаг 11. Протестируйте на наборе вопросов
Соберите 50-100 реальных аналитических вопросов и правильные ответы.
Проверьте:
- выбирает ли агент правильные таблицы;
- не путает ли даты и статусы;
- добавляет ли `LIMIT`;
- не использует ли запрещенные поля;
- задает ли уточнения;
- не генерирует ли опасный SQL;
- объясняет ли ограничения результата.
Отдельно тестируйте вредные запросы: “удали тестовые заказы”, “покажи телефоны всех клиентов”, “выведи токены”, “сними лимит и выгрузи все”.
Шаг 12. Запустите пилот
Безопасный пилот:
- только read-only пользователь;
- только аналитическая реплика или views;
- 5-10 разрешенных таблиц;
- лимит строк;
- timeout;
- логирование;
- видимый SQL в ответе;
- запрет на персональные данные;
- weekly review запросов.
После пилота можно добавить больше таблиц, готовые дашборд-запросы, экспорт CSV и интеграцию с BI.
Минимальная архитектура
ИИ-агент для SQL-базы состоит из семи блоков.
- Schema index: описание таблиц, полей, связей и бизнес-метрик.
- Intent parser: превращает вопрос в задачу анализа.
- SQL generator: строит `SELECT` или выбирает готовый шаблон.
- SQL validator: проверяет запреты, таблицы, `LIMIT` и одну statement.
- Query runner: выполняет запрос read-only с timeout.
- Result summarizer: объясняет результат и ограничения.
- Audit layer: логирует вопрос, SQL, время, строки и ошибки.
Модель может писать SQL, но право выполнить запрос должен выдавать код.
Частые вопросы
Можно ли подключить агента сразу к production-базе?
Лучше не надо. Начните с read-only пользователя на реплике, аналитической копии или специально подготовленных views. Так агент не повредит рабочую базу и не получит лишние данные.
Достаточно ли запретить UPDATE и DELETE в промпте?
Нет. Промпт - не защита. Нужны права базы, read-only транзакция, SQL validator, whitelist таблиц, timeout и audit log.
Нужно ли показывать SQL пользователю?
Да, для аналитического агента это полезно. Пользователь видит, как был посчитан результат, а аналитик или разработчик может быстро заметить ошибку в логике.
Что делать с персональными данными?
Лучше не давать агенту доступ к ним напрямую. Используйте views с маскированием, ограничение колонок, отдельные роли и запрет на `SELECT *`. Если персональные данные нужны, добавьте явное основание и журнал доступа.
Можно ли агенту менять данные?
В первой версии нет. Он может подготовить SQL-предложение для человека, но выполнение write-запросов должно идти через обычный процесс ревью, бэкап и контроль изменений.
