Reading PostgreSQL Without Losing the Details

The second ForgeSchema checkpoint connects the schema contract to an existing PostgreSQL database. The inspect command reads catalog metadata in a read-only transaction and returns the same canonical representation used by the YAML validator. Repeated inspections of a supported unchanged schema produce identical output.

The difficult part is deciding what the engine can describe faithfully. A column default, a partial index or a generated expression cannot simply disappear from the snapshot. The inspector rejects unsupported structures explicitly, identifying the object that prevents a complete supported snapshot. It also separates primary key backing indexes from ordinary indexes and preserves the order of columns within composite keys.

Live tests against PostgreSQL 16.10 and 17.6 exercise a populated customer database, compare the result with desired YAML and cover unsupported structures, restricted access and cancellation. The inspector reads no application rows and does not change database objects.

The next step is comparison: turning the difference between the observed schema and the desired schema into an explained migration plan. Execution is still a later stage, and this checkpoint cannot apply changes.