[Перевод] Мы научили ИИ писать настоящий код для Postgres (и выложили в open source)

TL;DR:

Авторы показывают типичный сценарий, когда ИИ пишет рабочий SQL для Postgres, но закладывает скрытый техдолг. Они предлагают pg-aiguide — open source слой для код-агентов, который добавляет «Postgres-специфичное чутьё» за счёт трёх компонентов: opinionated “skills” с практиками (типы данных, временные метки, индексы, идентификаторы и т.п.), семантического поиска по официальной документации с учётом версий Postgres 15–18 и базы знаний по расширениям (старт с TimescaleDB).

Подключается к Claude Code, Cursor и другим инструментам через MCP или плагин, чтобы по умолчанию получать более корректные, продакшен-ориентированные схемы без ручного промпт-хакинга и вставки документации.

Представьте: вы открываете Claude Code или Cursor, описываете таблицы, и через несколько секунд ИИ отдаёт схему Postgres, которая выглядит… нормально. Она запускается. Тесты проходят. Вы выкатываете в прод.

Чего вы не видите, так это тихих маленьких катастроф, спрятанных внутри: тип money для цен, индекс BRIN по случайным данным, SERIAL и UUID вперемешку, timestamp без часового пояса, потому что какой-то туториал сказал, что так «проще».

Проходит шесть месяцев. Вы отлаживаете баги с конвертацией валют, гоняетесь за призраками таймзон, переписываете миграции и добавляете индекс, который должен был быть с первого дня. Код, который написал ИИ-агент, работал, просто он был плохим. Он копировал любые примеры, которые смог наскрести по всему интернету.

И в этом проблема. Он учился SQL отовсюду: Postgres, MySQL, SQLite, SQL Server, Oracle, случайные туториалы и десятилетие ответов на Stack Overflow. В этом шуме нюансы идиоматичного, качественного Postgres тонут среди хорошего, плохого и MySQL.

Поэтому мы сделали штуку, которая это исправляет.

Дать ИИ недостающее «чутьё» Postgres

pg-aiguide даёт ИИ-агентам для написания кода то самое Postgres-специфичное «чутьё», которого им не хватает. Это работает за счёт трёх вещей, которые дополняют друг друга:

1. AI-оптимизированные «скиллы» — отобранные, намеренно «с мнением» лучшие практики Postgres, которые Claude Code и другие агенты могут применять автоматически.

2. Семантический поиск по официальной документации с учётом версии — извлечение информации для Postgres 15–18.

3. Документация по экосистеме расширений, начиная с TimescaleDB, и дальше список будет быстро расширяться

Вы можете подключить это к любому ИИ-агенту для написания кода через публичный сервер Model Context Protocol (MCP) или через плагин для Claude Code, сделанный так, чтобы использовать нативную поддержку skills в Claude. Без аккаунтов, без лимитов на использование и полностью бесплатно.

Цель простая: сделать так, чтобы ИИ по умолчанию писал корректный, готовый к продакшену Postgres.

Вам не должно быть нужно вставлять документацию, править результат или полагаться на «промт-хакерство». ИИ должен просто генерировать лучший SQL с первого раза.

Начать пользоваться pg-aiguide можно меньше чем за минуту. Он работает с Claude Code, Codex, Cursor, Gemini CLI, Visual Studio, VS Code, Windsurf и любыми другими редакторами, совместимыми с MCP. Инструкции по установке смотрите в кратком руководстве по началу работы.

Почему качество кода базы данных так важно

Использование ИИ среди разработчиков Postgres резко выросло: по данным опроса State of Postgres 2024 доля увеличилась с 37% до 55% всего за год. Но по мере того как LLM становятся более универсальными, обучающие данные становятся широкими, а не специализированными, и сами модели начинают работать менее точно.

Отсюда возникает неожиданная проблема: исследование METR недавно показало, что опытные разработчики, использующие ИИ, на самом деле тратили на выполнение задач на 19% больше времени. Не потому, что ИИ тормозил, а потому что результат был «почти правильным» — с теми самыми тонкими ошибками, которые дольше всего находить, отлаживать и распутывать.

В случае баз данных «почти правильно» очень быстро накапливает последствия.

Схемы закрепляют решения, которые потом больно менять. Ошибки в индексах прячутся до тех пор, пока таблицы не вырастут. Выбор типов данных, который в разработке можно поправить за час, в продакшене может превратиться в дни миграций и аккуратного планирования.

Код приложения можно отрефакторить. Состояние без последствий не отрефакторишь.

pg-aiguide останавливает такие ошибки на входе, пока они не «запеклись» в продакшене.

Обычный SQL против «направляемого» SQL

Вот что происходит, когда вы просите ассистента по коду спроектировать простую схему для книжного магазина.

Без pg-aiguide

CREATE TABLE customers ( customer_id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), email VARCHAR(255) UNIQUE NOT NULL, password_hash VARCHAR(255) NOT NULL, first_name VARCHAR(100) NOT NULL, last_name VARCHAR(100) NOT NULL, phone VARCHAR(20), created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, is_active BOOLEAN DEFAULT TRUE ); CREATE INDEX idx_customers_email ON customers(email); CREATE TABLE authors ( author_id SERIAL PRIMARY KEY, first_name VARCHAR(100) NOT NULL, last_name VARCHAR(100) NOT NULL, biography TEXT, created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP );

Эта схема работает, но в ней есть классические проблемы:

• смешанные стратегии генерации идентификаторов

• произвольные ограничения VARCHAR

• уникальность email с учётом регистра

• значения по умолчанию для временных меток, которые ведут себя по-разному в разных системах

С включённым pg-aiguide

CREATE TABLE authors ( author_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY, name TEXT NOT NULL, bio TEXT, created_at TIMESTAMPTZ NOT NULL DEFAULT now() ); CREATE INDEX ON authors (name); CREATE TABLE users ( user_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY, email TEXT NOT NULL UNIQUE, password_hash TEXT NOT NULL, first_name TEXT NOT NULL, last_name TEXT NOT NULL, phone TEXT, is_active BOOLEAN NOT NULL DEFAULT true, created_at TIMESTAMPTZ NOT NULL DEFAULT now(), updated_at TIMESTAMPTZ NOT NULL DEFAULT now() ); CREATE UNIQUE INDEX ON users (LOWER(email)); CREATE INDEX ON users (created_at);

В этой версии используется:

• согласованная стратегия идентификаторов (BIGINT GENERATED ALWAYS AS IDENTITY)

• TEXT вместо лишнего VARCHAR

• корректная работа со временем (timestamptz + now())

• корректно обеспеченная уникальность без учёта регистра

За кулисами ИИ использовал навык design_postgres_table либо через MCP-инструмент view_skill, либо через нативный фреймворк skills в Claude. В обоих случаях агент сам нашёл и применил рекомендации, оптимизированные под Postgres, без участия человека.

Вам не нужно было по-другому формулировать запрос.

Вам не нужно было вставлять документацию.

pg-aiguide автоматически переключает ИИ с «SQL, который работает» на «SQL, который вы реально захотите видеть в продакшене».

Навыки — секретный ингредиент

Если вы хотите, чтобы ИИ генерировал качественный SQL, недостаточно просто дать ему поиск по руководству. Руководство говорит, что можно сделать, но не говорит, как правильно. Навыки закрывают этот разрыв. Они дают модели «суждение», а не просто факты.

Наши навыки не пытаются заново обучать LLM синтаксису или возможностям. Вместо этого они дают модели контекст, который нужен, чтобы принимать более правильные решения. Ниже фрагмент реального навыка.

«Подводные камни» Postgres

• Индексы для внешних ключей: Postgres не создаёт индексы по столбцам внешних ключей автоматически. Добавляйте их.

• Без молчаливых преобразований: переполнение по длине/точности приводит к ошибке (ничего не обрезается).
  Пример: вставка 999 в NUMERIC(2,0) завершится ошибкой, в отличие от некоторых баз данных, которые молча обрезают или округляют значение.

• Хранение в куче (heap): по умолчанию нет кластеризации по первичному ключу (в отличие от SQL Server/MySQL InnoDB); порядок строк на диске соответствует порядку вставки, если явно не выполнить кластеризацию.

Это те детали, которые обычно узнаёшь только после того, как какое-то время поживёшь в Postgres. Они подставляют LLM ровно по той же причине, по которой подставляют разработчиков, которые только знакомятся с базой (и иногда тех, кто знакомится уже не первый год). Но именно такие детали и позволяют модели генерировать более качественный SQL.

В наших оценках (пока «на человеческих ощущениях», скоро с оценкой через LLM) качество схем стабильно улучшается, если сравнивать систему только с семантическим поиском и систему, где есть и семантический поиск, и навыки:

• более подходящие типы данных

• корректная семантика временных меток

• более продуманная стратегия индексации

• меньше ловушек при миграциях

• меньше долгосрочных сюрпризов с производительностью

Вот как выглядит ситуация, когда «инструменты для написания кода с ИИ действительно понимают Postgres».

Инструменты, которые мы даём LLM

pg-aiguide предоставляет две ключевые возможности, которые хорошо ложатся на то, как работают AI-инструменты для написания кода.

1. Навыки: полное, «с мнением», руководство по Postgres

view_skill возвращает лучшие практики целиком, в виде AI-оптимизированного блока. Это не туториалы и не расплывчатые промпты. Это плотные, адресованные машине, экономные по токенам рекомендации, которыми ИИ может надёжно пользоваться.

Например:

• предпочитай BIGINT GENERATED ALWAYS AS IDENTITY

• не используй money

• не используй timestamp без часового пояса

• индексируй столбцы внешних ключей

• ожидай ошибок при переполнении по точности

Навыки не нужно резать на чанки: они написаны так, чтобы каждый навык целиком помещался в контекст как единый завершённый блок.

Claude Code даже поддерживает skills нативно, поэтому инструмент view_skill на MCP-сервере автоматически отключается, когда используется режим плагина.

1. Семантический поиск: векторный поиск по документации с учётом версии

MCP-инструменты semantic_search_postgres_docs и semantic_search_tiger_docs позволяют ИИ подтягивать корректную документацию для той версии Postgres, на которую вы нацелены.

Это важно, потому что версии Postgres заметно эволюционируют:

• Postgres 15: UNIQUE NULLS NOT DISTINCT

• Postgres 16: крупные изменения в поведении параллельных запросов

• Postgres 17: улучшения обработки ошибок в COPY

Без учёта версии ИИ может (и действительно может) «галлюцинировать» возможности или синтаксис, которые сломают реальную среду.

Все эти знания о Postgres нарезаются на чанки, превращаются в эмбеддинги и хранятся в самом Postgres.

Мы парсим официальную HTML-документацию, сохраняем контекст заголовков, прикрепляем URL источников и используем чанкинг с ограничением по числу символов, добавляя «хлебные крошки» H1→H2→H3, чтобы каждый фрагмент сохранял смысл и было понятно, как он вписывается в общую картину.

---

Для тех, кто хочет внедрить AI на основе LLM в свой проект или сервис, рекомендую обратить внимание на курс «LLM Driven Development». Для знакомства с форматом обучения и экспертами приходите на бесплатные демо-уроки:

• 10 февраля, 20:00. «Тестирование и валидация AI-агентов: от RAG-прототипа к управляемой интеллектуальной системе». Записаться

• 11 февраля, 20:00. «LLM-риски в бизнес-процессах: галлюцинации, доверие и ответственность». Записаться

Источник