What it is
A drop-in module that adds referential integrity, cascading deletes, multi-column unique constraints, and paginated queries to SpacetimeDB, filling the gap left by the absence of native foreign keys. It sits between your application reducers and the database tables, intercepting writes to enforce the rules you declare.
Where it fits
- Relational data with ownership hierarchies: A project management app where deleting a board should automatically remove all its lists, cards, and comments in one safe transaction.
- Apps with optional references: A task tracker where cards can be assigned to members, and deleting a member should unlink those assignments rather than block or cascade.
- Migrating existing data: A team adopting stricter data rules on a live database that already contains orphaned rows from earlier, less careful code.
- Paginated live views: A collaborative app where multiple clients each need their own scrollable, subscribable window into a large table that updates in real time.
- Multi-language teams: A project where the server module might be written in Rust, C#, or TypeScript but all clients need to see the same schema and behavior.
How it works
Because SpacetimeDB has no native triggers or foreign key enforcement, this module works by routing writes through checked wrappers that you call from your own reducers. Before any delete is applied, the module performs a read-only planning pass that walks every declared relationship level by level, deciding which rows would cascade, which references would be set to null, and whether any row would be left as an orphan that is not allowed. Only if the plan is clean does it proceed to write, applying nullifications first and then deletions from the leaves inward. The whole operation is atomic.
Referential rules are declared once in a concise schema: each declaration names the child column, the parent table, and the behavior on delete (cascade, set null, or restrict). The module uses these declarations for both enforcement and for generating human-readable delete previews, so a client can ask "what would deleting this board affect?" and receive the exact same plan that a real delete would execute.
Pagination is handled by storing each client's current cursor position as a row in the database rather than as a parameter, which lets SpacetimeDB subscriptions track a live page as other clients make edits. A separate integrity check and repair facility scans the full dataset for orphans and duplicates, which is useful after bulk migrations or when first adopting the module on a database that already has data.
