Python Psycopg Yoyo Persistence Writing

Адаптеры хранения psycopg и миграции yoyo

Общие правила оформления Python-кода брать из $python-code-style-writing и не дублировать здесь; этот скил определяет persistence-контракты и SQL-безопасность.

Порядок работы

1. Извлечь точный контракт порта: методы, типы, отсутствие, конфликты, атомарность, версию и согласованность чтения.
2. Сверить таблицы, столбцы, типы, nullable и ограничения с миграциями.
3. Реализовать connection manager, фабрику UoW, UoW и репозитории с одним владельцем транзакции.
4. Преобразовывать DB-данные только в тип результата порта.
5. Оборачивать ожидаемые ошибки зависимости в AppPortError.
6. Для изменения схемы сначала показать пользователю таблицы и план миграции, получить разрешения и только затем менять файлы.
7. Проверить mapping unit-тестами, SQL — на PostgreSQL, миграции — apply → rollback → apply через yoyo.

Граница ответственности

• Реализовывать существующий application-порт без изменения публичного контракта под удобство PostgreSQL.
• Не возвращать DictRow, cursor, connection, SQL-модель или тип psycopg наружу.
• Не определять доменные инварианты и публичную семантику исходов.
• При недостаточном или противоречивом контракте остановиться и назвать конкретное противоречие.

Транзакционная модель

• Connection manager владеет pool и арендой соединений.
• UnitOfWorkFactory — долгоживущий stateless-адаптер; каждый вызов возвращает новый UoW.
• UoW получает соединение при входе, открывает явный connection.transaction() и предоставляет репозиториям одно соединение.
• UoW единолично определяет commit/rollback. Connection manager и репозитории не придают выходу прикладную семантику.
• Не использовать pool.connection() внутри UoW как второй автоматический transaction manager: арендовать через getconn/putconn или эквивалентный lease без скрытого commit.
• Один UoW нельзя повторно или конкурентно использовать. После выхода очищать connection, transaction context и repository-группы.
• Retry всей операции создаёт новый UoW; отдельный SQL внутри сломанной транзакции не повторять.
• Isolation level, read-only, savepoints и retry добавлять только по требованиям.

Подробности: единица работы и менеджер подключений.

Репозитории

Устройство

• Публичные методы точно реализуют порт и делегируют DB-операции приватным.
• Базовый репозиторий хранит только connection, общий enum таблиц и действительно общие технические helpers. Не создавать универсальный CRUD.
• Статический SQL держать рядом с репозиторием; не строить собственный ORM.
• Использовать явный список колонок вместо SELECT *.
• Каждый приватный DB-метод закрывает cursor контекстным менеджером и преобразует результат до выхода.

Сохранение и чтение

• Одиночный save делегирует в _create/_update с обычным execute; не оборачивать объект в batch_save.
• batch_save заранее преобразует всю пачку и использует executemany, не выполняя SQL в цикле.
• Batch-чтение реализовывать set-based запросом; пустой набор завершать без SQL.
• Connection-bound репозитории UoW не получают новое соединение самостоятельно.
• Самостоятельный read-адаптер арендует соединение на один публичный вызов и не хранит его между вызовами.
• Не объединять оба режима через поле connection | manager.

Подробности: сохранение и чтение.

Преобразование

• Настраивать psycopg с row_factory=dict_row, типизировать строки как DictRow и читать колонки по именам.
• Агрегат или доменную проекцию восстанавливать в _model_to_domain только через доменную фабрику и проектный @handle_domain_errors.
• DTO порта создавать в _model_to_dto.
• Parameter mapper-ы и DB-to-result mapper-ы делать чистыми и переиспользовать между одиночной и пакетной операцией.
• Не менять приватные поля агрегата и не исправлять повреждённые данные молча.
• Преобразовывать вложенные коллекции результата в неизменяемые структуры.

Подробности: преобразование моделей.

Идентификаторы, время и версия

• Получать доменный ID и значимое время уже назначенными вызывающим слоем.
• Не генерировать UUID/время в репозитории, не вызывать соответствующие порты и не подменять значения NOW().
• DB-generated ключ или время допустимы только как технические детали, не пересекающие границу адаптера.
• Выбирать create/update и точки сохранения версии только по контракту.
• При optimistic locking включать ожидаемую сохранённую версию в WHERE и проверять число изменённых строк.
• Не выполнять скрытый retry, перечитывание или last-write-wins.

Полиморфный outbox

• Реализовывать единый outbox только по заданному порту и схеме.
• Сохранять стабильный идентификатор события из outbox DTO; не генерировать и не заменять его в persistence-адаптере. Технический ключ строки outbox хранить отдельно, если он предусмотрен схемой.
• Сопоставлять конкретные DTO с заранее определёнными SQL-объектами и записями реестра таблиц; не принимать имя таблицы из данных и не использовать f-строки.
• Если схема хранит идентификатор агрегата и версию, создавать outbox-запись без предварительного чтения физического идентификатора версии.
• Выбирать ожидающую outbox-запись в заданном постоянном порядке, затем отдельным запросом получать конкретную версию. Два запроса допустимы; не объединять все таблицы громоздким SQL без измеренной необходимости.
• Реализовывать каждый терминальный переход статуса с условием на текущее состояние. Тот же исход делать идемпотентным, а смену терминального исхода — конфликтом, если это задано портом.
• Для batch-save группировать DTO по runtime-типу и выполнять set-based запрос на непустую группу, а не запрос на каждый элемент.

Ошибки

• Использовать параметризованный @handle_postgres_errors на приватных DB-методах; сохранять sync/async-сигнатуру через functools.wraps.
• Перехватывать только ожидаемые ошибки psycopg на минимальной операции.
• Создавать AppPortError с безопасным контекстом, исходной причиной в wrap_error и цепочкой raise ... from error.
• Если порт различает конфликт или недоступность, передавать стабильную application-категорию в data; use case не анализирует тип psycopg.
• Известные constraints сопоставлять с категориями в приватной карте, не по тексту ошибки. Неизвестный constraint — общая ошибка порта.
• Не раскрывать SQLSTATE, constraint name, SQL, параметры, DSN и secrets.
• Не перехватывать BaseException, отмену задачи и ошибки программирования.
• _model_to_domain оставлять под отдельным @handle_domain_errors.
• Не логировать пробрасываемую или обработанную локальную ошибку. Возвращать результат либо пробрасывать типизированную ошибку с безопасным контекстом.

Подробности: ошибки.

SQL и конкурентность

• Передавать данные только через placeholders.
• Собирать схемы, таблицы и колонки через psycopg.sql.Identifier.
• Типизировать статический литерал как SQL, произвольный безопасный SQL-фрагмент как Composable, а результат SQL.format(), SQL.join() и композиции — как Composed. Не объявлять результат форматирования типом SQL.
• Сопоставлять поля и направления сортировки с закрытым набором SQL-объектов.
• Хранить фактические имена таблиц в общем StrEnum persistence-модуля и сверять их с миграциями.
• Для пагинации использовать детерминированный ORDER BY с уникальным tie-breaker.
• Обязательный tenant/context scope включать в тот же SELECT/UPDATE/DELETE, что выполняет операцию.
• Не маскировать различимый конфликт через ON CONFLICT DO NOTHING/DO UPDATE.
• Не повторять отдельный statement после deadlock/serialization failure; при заданном retry повторять всю операцию с новым UoW.

Подробности: безопасный SQL.

Обязательное согласование миграции

До создания или изменения файла:

1. Перечислить создаваемые, изменяемые и удаляемые таблицы и их назначение.

2. Для каждой таблицы показать:

   Столбец	Тип PostgreSQL	NULL	По умолчанию	Ограничения	Назначение

3. Для существующих столбцов показать:

   Столбец	Текущее состояние	Новое состояние	Перенос данных	Риск

4. Перечислить ключи, связи, ON DELETE/ON UPDATE, CHECK, UNIQUE и другие ограничения.

5. Показать способ применения, отката, совместимость версий и риск блокировок.

6. Получить явное подтверждение схемы до редактирования файлов.

Для view, enum, sequence, function, trigger, extension и schema показывать определение, назначение, зависимости, привилегии, влияние и откат.

Индексы и уникальность

• Любой индекс создавать только с явного разрешения.
• Показать таблицу, колонки, метод, условие, ускоряемые запросы, стоимость записи, место и блокировки.
• Уникальный индекс и UNIQUE согласовывать отдельно с бизнес-правилом и стратегией обработки дубликатов.
• Для принятого UNIQUE задавать явное стабильное имя constraint-а через CONSTRAINT <name> UNIQUE (...); не полагаться на имя, автоматически сформированное PostgreSQL. Создаваемый им constraint-backed индекс отдельно не дублировать явным уникальным индексом.
• Прямо заказанный индекс разрешён только в указанном составе.

Существующие миграции

• Перед перезаписью перечислить точные файлы и спросить, какие разрешено менять.
• Уточнить, применялись ли они в общих или production-окружениях.
• Не менять файл без разрешения; при запрете создать корректирующую миграцию.
• Даже при разрешении предупредить о расхождении уже мигрировавших БД.

Реестр физических таблиц

Если схема требует общий реестр таблиц:

• создавать реестр раньше зависимых объектов и, при полном составе, добавлять его собственную запись сразу после создания;
• в миграции создания каждой таблицы добавлять её точное физическое имя в реестр;
• в миграции переименования синхронно обновлять запись реестра;
• в rollback сначала устранять полиморфные ссылки и удалять запись реестра, затем удалять таблицу;
• при полном откате удалять реестр последним;
• проверять integration-тестом прямой и обратный lifecycle записи вместе с соответствующей таблицей.

Разрушительные изменения

Отдельно подтверждать удаление объектов/данных, сужение типов, потенциально необратимый rollback, изменение связей и несовместимое переименование. Показать затрагиваемые данные, перенос/резервирование, совместимость и ограничения отката.

Подробности: миграции yoyo.

Тестирование

• Unit-тестами проверять чистые mapper-ы, параметры, UoW lifecycle и классификацию ошибок.
• Для UoW использовать небольшие fake transaction/connection manager вместо хрупких цепочек AsyncMock.
• SQL и атомарность нескольких репозиториев проверять integration-тестами на PostgreSQL, не SQLite.
• Проверять отмену, cleanup и отсутствие утечки состояния, если этот код написан.
• Создавать domain-объекты только через фабрики.
• Объединять схожие случаи parametrize с ids.
• Применять миграции штатным yoyo, не исполнять прочитанный из файла SQL.
• Поднимать временную инфраструктуру автоматически и удалять после проверки.

Антипаттерны

• Изменение application-порта под удобство SQL.
• Один UoW, сохранённый в повторно используемом use case.
• DB-типы за границей адаптера.
• Доменный ID или значимое время, созданные репозиторием.
• commit/rollback в репозитории либо двойной transaction manager.
• Однострочный save → batch_save.
• N+1 при наличии batch-контракта.
• Анализ psycopg-исключения в use case.
• SQL через f-строки, SELECT *, ручное экранирование.
• Аннотация SQL для результата format(), join() или другой композиции, фактически возвращающей Composed.
• Миграция, импортирующая runtime domain/application-код.
• Перезапись миграции, индекс или разрушительное изменение без разрешения.
• Создание миграции до демонстрации таблицы.
• IF EXISTS/IF NOT EXISTS, скрывающие неожиданную схему.

Критерии готовности

• Порт реализован без раскрытия DB-деталей.
• Фабрика создаёт новый UoW на каждую попытку.
• UoW единолично управляет транзакцией и общим соединением репозиториев.
• Одиночные и пакетные операции не создают лишних запросов.
• Mapping создаёт domain через фабрику либо DTO порта.
• Ошибки преобразованы в AppPortError.
• SQL параметризован, идентификаторы безопасно скомпонованы.
• Scope, пагинация, кардинальность и optimistic locking соответствуют контракту.
• Схема и migration chain согласованы с кодом.
• Все необходимые разрешения пользователя получены.
• Миграция проверена через yoyo apply → rollback → apply.
• Unit- и integration-тесты прошли.

Материалы

• Сохранение
• Чтение и пагинация
• Преобразование моделей
• Ошибки
• Единица работы
• Менеджер подключений
• Безопасный SQL
• Миграции yoyo
• Чеклист