Hey, I’ve been working on an open source project called pgfathom. It came from a problem I ran into quite a lot at work with legacy databases.
You’ll sometimes have something like orders.customer_id -> customers.id that the application has treated as a relationship for years, but there’s no actual foreign key in PostgreSQL. So it won’t show up properly in an ERD, and nothing is stopping orphaned rows from getting in.
pgfathom looks for those relationships using the catalog, column names, indexes, existing FKs and JOINs found in views/functions. It then checks the candidates against the actual data.
If it finds orphans, it gives you a query to inspect them. If the relationship checks out, it generates the FK DDL and an index when needed. It never applies any of it. The CLI runs read-only and only generates SQL for you to review.
One thing that helped a lot with weird legacy schemas was letting it learn naming conventions from the database itself instead of assuming everything looks like customer_id.
I tested this on a municipal schema with 277 foreign keys. With half of the FKs left in place so pgfathom could learn the naming pattern, recovery went from 17.3% to 84.9%. If I remove all of them, it drops to 16.6%.
There are also some safeguards for running it against real databases: read-only sessions, query timeouts, limited concurrency, and tests to make sure table values don’t end up in output, logs, JSON or errors.
I used AI as part of my workflow too, mostly for research and implementation, so I’d rather mention that upfront.
It’s still early and I’d really like to test it against schemas that look nothing like the ones I’ve been using.
GitHub:
https://github.com/lvcas-dotcom/pgfathom
If you work with old PostgreSQL databases and feel like giving it a try, I’d appreciate the feedback. Finding cases where it gets the relationship wrong would actually be very useful.
(English isn’t my first language, so apologies if anything in the post sounds a bit off)