Migrations: a ledger table, module-owned migrations and one apply command
- Dominant language
- C#
- Stars
- 6
- Forks
- 7
- Avg merge
- 4h 42m
- Merged PRs (30d)
- 307
Description
Schema changes that need an ALTER are SQL files run by hand, with no record of what ran. Production uses `AutoCreate.CreateOnly` (`barakoCMS/Extensions/ServiceCollectionExtensions.cs:434-436`, `barakoCMS/Program.cs:66-75`), so an upgrade needing an ALTER fails at startup and the operator applies a file with `psql` (`docs/deploy-on-a-managed-platform.md:204-208`). `migrations/4.2.0/stored-files-parent-index.sql` is a Files module change kept in core's folder. `barakoCMS/Modules/ModuleSchemaPreflight.cs:106-130` can say a module needs a migration but cannot apply one, and BaryoVM preDeploy hooks are the only automated hook point.
### Why it matters
An agency running twenty client instances has no way to ask any of them "which migrations have you had". A module shipped by a third party has nowhere to put its SQL. Skipping a file or running one twice is found out by a failed deploy, or not at all for an index.
### The general concept
A ledger table recording each applied migration by id and checksum. Core and each module ship their migrations as embedded resources with ids. One apply command (alongside the existing JasperFx `db-apply` and `db-patch`) runs what the ledger lacks in order, and preflight reports pending migrations by module and id instead of stopping at "needs migration".
### Where it lives
Core: schema and module preflight. Modules own their migration files.
### Compatibility
Released. The ledger is a new table. An existing database is baselined on first run by checking for the objects each shipped migration creates, so migrations already applied by hand are recorded rather than rerun. The `migrations/` files stay readable for operators who apply by hand. No HTTP change.
### Done when
- Applying twice runs each migration once, and a test showing the second run is a no-op.
- The Files index migration ships with the Files module and appears in the ledger under it.
- Preflight names the pending migration ids on a database that lacks one.
Found in the architecture sweep of 15 September 2026.
Contributor guide
Research direction
Start with barakoCMS/Extensions/ServiceCollectionExtensions.cs, barakoCMS/Program.cs, and barakoCMS/Modules/ModuleSchemaPreflight.cs, then inspect migrations/4.2.0/stored-files-parent-index.sql and the managed-platform deployment instructions. Trace the existing CreateOnly and preflight paths before defining the ledger and module ownership boundaries. Done means repeated application is a no-op, the Files migration is ledgered under its module, and preflight names pending migration ids.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp, postgresql, sql
- Domain
- backend, databases, devops
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100