pgfathom

pgfathom — это read-only утилита командной строки для археологии схем PostgreSQL. Она находит отношения, которые не объявлены как внешние ключи, путём анализа каталога, свидетельств использования из представлений и функций, соглашений именования и статистики планировщика. Утилита никогда не записывает данные в базу и предназначена для безопасной работы на production-системах. Проблема, которую она решает, заключается в том, что многие унаследованные базы PostgreSQL скрывают ссылочную целостность — колонки, указывающие на другие таблицы, но лишённые ограничений, либо ограничения, созданные с NOT VALID и никогда не валидированные. Это делает модель невидимой для таких инструментов, как ∆, и позволяет аномальным строкам накапливаться незамеченными. Что умеет pgfathom: * В режиме discover генерирует терминальный отчёт с вердиктами (broken, confirmed, weak, unvalidated, detected), версионную JSON-модель и обзоры .sql файлов. Для подтверждённых отношений создаётся DDL с выделенным VALIDATE CONSTRAINT для избежания тяжёлых блокировок, а также CREATE INDEX CONCURRENTLY при необходимости. Для нарушенных отношений выдаётся закомментированный DDL, чтобы пользователь мог решить, что делать с аномальными строками. * Поддерживает профили именования (pt-br, en, es) и умеет считывать соглашения из суффиксов/префиксов непосредственно из ключей, которые схема всё ещё объявляет. Пользователи могут предоставлять собственные TOML-профили. * Предикаты объединения добываются из определений представлений и тел функций (и, когда доступно, из pg_stat_statements), чтобы находить связи, недоступные простому сопоставлению имён. * Пайплайн валидации состоит из шести стадий: чтение каталога, добыча свидетельств использования, генерация кандидатов по профилю, оценка по метаданным, префильтрация со статистикой и финальная валидация против данных с помощью агрегатов. Варианты установки: DEB/RPM пакеты, Homebrew, Docker-образ или сборка из исходников на Go. Утилита read-only, уважает statement и lock timeouts, ограничивает конкурентность и отчитывается о покрытии схем и таблиц, чтобы молчание не принималось за отсутствие проблем. По умолчанию область охвата — public schema, но можно расширить с помощью флагов --all-schemas, --schema, --exclude-schema и --exclude. Команда setup проводит первопользователя через подключение, выбор схем, глубину валидации и расположение вывода. Корректность измеряется коэффициентом восстановления: у схемы с полными внешними ключами их удаляют, запускают pgfathom, и отчитывают долю восстановленных. Результаты публикуются на публичном корпусе, включающем GitLab, муниципальные системы и Discourse, показывая работу в режимах partial (половина ключей удалена) и greenfield (ключи не объявлены вообще). Утилита также показывает вклад каждой стадии — профиля, обнаружения по именам и добычи join-предикатов. Вывод включает терминальную сводку с подсчётами по вердиктам, проанализированными таблицами и результатами префильтрации статистики; версионированную JSON-модель с меткой времени; и .sql файлы с DDL для подтверждённых ключей (готовый к запуску после ревью) и закомментированный DDL для нарушенных (требующий рассмотрения перед любыми действиями). Весь сгенерированный SQL предназначен для рецензирования перед выполнением. Короче говоря, pgfathom превращает молчаливую, недокументированную схему в видимую и действенную модель, предоставляя точные запросы для устранения нарушений целостности и безопасный DDL для восстановления недостающих ограничений.