mirror of
https://github.com/Stirling-Tools/Stirling-PDF.git
synced 2026-09-02 21:03:34 +03:00
ConnorYoh
f15832b2bb
## The problem The SaaS database has two writers and always has: the Supabase migrations in the SaaS repo, and Hibernate's `ddl-auto`. That was a convention rather than a rule, and it leaked twice. - An older `ddl-auto` run widened `team_memberships.role` to varchar(255), which needed [a dedicated migration](https://github.com/Stirling-Tools/Stirling-PDF-SaaS/blob/v3/supabase/migrations/20260804000000_fix_team_memberships_role_varchar50.sql) to repair, because RLS policies depended on the column. - `payg_instance_usage` shipped with an entity and **no migration**, and nobody noticed for months — staging already had the table from an earlier `ddl-auto` run. It surfaced only when a fresh preview branch, built from migrations alone, threw `relation does not exist`. Both are the same bug: nobody had to *say* who owned a table, so the answer got decided by accident. ## The fix `SaasSchemaOwnership` is the register — **29 migration-owned, 29 inherited** and left to Hibernate. `MigrationOwnedSchemaFilter` applies it via Hibernate's `hbm2ddl.schema_filter_provider`, wired on the **saas profile only**. Hibernate is never shown a migration-owned table, so it cannot create, alter, drop or truncate one whatever `ddl-auto` is set to. Inherited tables stay managed, so a fresh preview branch still heals itself on first boot. Self-hosted is untouched — there Hibernate rightly owns everything. **Why a filter rather than just `ddl-auto=none`:** off, and a fresh branch is missing the 29 inherited tables. On, and Hibernate can reach the other 29. The filter is what lets both be true at once. **Why per-table, not per-schema:** Hibernate's schema management runs over every mapped entity regardless of namespace. Moving SaaS tables to their own schema would *not* by itself keep Hibernate out of them — worth knowing, because that was the intuitive fix and it doesn't work. ## The part that makes it stick `SaasSchemaOwnershipTest` makes the register binding: every `@Entity` on the SaaS classpath must appear in exactly one set, so **a new entity fails the build until someone states who owns its table**. That's the forcing function that would have caught `payg_instance_usage`. I verified it bites rather than assuming it — removing a single entry fails with: ``` These entity tables are not declared in SaasSchemaOwnership, so nobody owns them. Offending tables -> entities: [policies (stirling.software.proprietary.policy.store.PolicyEntity)] ``` naming both the table and the class, which is what the next person actually needs. ## One debatable call The **validate** filter excludes them too. Letting validation through would flag drift, which is genuinely useful — but `ddl-auto=validate` fails startup, and it would fail on differences we've deliberately accepted (`ai_create_sessions` carries columns from a reverted Typst feature that nothing maps). A boot failure over a table we chose not to manage is noise. Argued in the javadoc; happy to flip it if you'd rather have the signal. ## Dependency Depends on [Stirling-PDF-SaaS#324](https://github.com/Stirling-Tools/Stirling-PDF-SaaS/pull/324), which adds migrations for the four SaaS-owned tables that had none. They're listed here as migration-owned on that basis, so #324 should land first. Companion to [#7483](https://github.com/Stirling-Tools/Stirling-PDF/pull/7483) (dev/staging profiles with per-profile `ddl-auto`). ## Verification `:saas:test` green including the 5 new tests, `spotlessCheck` green, and the mutation check above.