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.
Stirling PDF - The Open-Source PDF Platform
Stirling PDF is a powerful, open-source PDF editing platform. Run it as a personal desktop app, in the browser, or deploy it on your own servers with a private API. Edit, sign, redact, convert, and automate PDFs without sending documents to external services.
Key Capabilities
- Everywhere you work - Desktop client, browser UI, and self-hosted server with a private API.
- 50+ PDF tools - Edit, merge, split, sign, redact, convert, OCR, compress, and more.
- Automation & workflows - No-code pipelines direct in UI with APIs to process millions of PDFs.
- Enterprise‑grade - SSO, auditing, and flexible on‑prem deployments.
- Developer platform - REST APIs available for nearly all tools to integrate into your existing systems.
- Global UI - Interface available in 40+ languages.
For a full feature list, see the docs: https://docs.stirlingpdf.com
Quick Start
docker run -p 8080:8080 docker.stirlingpdf.com/stirlingtools/stirling-pdf
Then open: http://localhost:8080
For full installation options (including desktop and Kubernetes), see our Documentation Guide.
Resources
Support
- Community: Discord
- Bug Reports: GitHub Issues
Contributing
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
This project uses Task as a unified command runner for all build, dev, and test commands. Run task dev to get started running the editor, run task to see the most common commands, or see the Developer Guide for full details.
For adding translations, see the Translation Guide.
License
Stirling PDF is open-core. See LICENSE for details.