Document (or provide) an ordering guarantee for test/install/*.sql files #111

🤖 (Claude)

base.mk's test/install schedule generation (~line 298) iterates $(TEST_INSTALL_SQL_FILES) (a $(wildcard test/install/*.sql) expansion) with no explicit sort, so the order install files run in depends entirely on whatever order Make's wildcard happens to return (in practice, alphabetical on most platforms/filesystems, but this isn't a documented guarantee anyone should rely on).

This bit a real consumer: two install files had an implicit dependency (one provisions roles the other's CREATE EXTENSION ... CASCADE requires to already exist), named such that alphabetical order ran them backwards. It "worked" for a long time anyway, purely by accident — an unrelated step elsewhere in the same test run happened to provision the same roles as a side effect, masking the real ordering bug until that masking step was removed. Confirmed by regenerating the schedule and observing the actual (wrong) order, then by explicitly dropping the roles and watching a real test run fail without the masking step.

Neither pgxntool/CLAUDE.md nor any other doc says anything about whether file order is guaranteed or how to control it if a consumer has an inter-file dependency like this. Two possible directions, either would resolve this:

1. Document that ordering is NOT guaranteed and consumers with dependencies between install files must encode that in the filenames themselves (e.g. a numeric prefix) to get deterministic alphabetical ordering.
2. Provide an actual ordering mechanism (e.g. read files from a schedule file each consumer maintains, rather than a bare wildcard), and document it.

Filing as a documentation gap at minimum — happy to help with a PR for whichever direction is preferred.