Snapshot persistence · 0.1.x

Strates package documentation

Build complete business states in isolation, persist independent dependencies concurrently, and publish one coherent snapshot without exposing partially written data. This documentation was checked against Strates 0.1.10 and Core 2.7.1.

Visibility

Atomic publication

Readers move from one complete build to the next through a single release pointer.

Performance

Parallel persistence

Independent graph branches can be written concurrently under one unreleased build.

Reliability

Failure isolation

A failed candidate build never replaces or corrupts the currently released state.

Operations

Retained history

Previous immutable builds remain available for audit, comparison and rollback.

Persistence-first architecture¶

Strates is primarily a persistence strategy for complete, versioned business states. Instead of modifying the rows currently read by the application, a writer persists the next state under a new UUID v7 buildStrate. Released queries continue to read the previous state until one release pointer selects the completed build.

currently released snapshot A
            │
            ├── readers keep using A
            │
            └── build snapshot B in isolation
                         │
                         ├── persistence fails → A remains released
                         │
                         └── persistence completes
                                      │
                                      └── release pointer moves A → B

This separation between writing and publishing provides several persistence benefits:

No partially persisted state is exposed: rows belonging to a build remain invisible to released-data queries until the release pointer is updated.
Failure isolation: a failed import, recalculation or graph persistence does not corrupt or replace the currently released snapshot.
Whole-state consistency: all released rows are selected with the same buildStrate, which prevents readers from mixing records from different versions of an aggregate.
Simpler replacement semantics: complex state can be rebuilt and persisted as a complete snapshot instead of applying an order-sensitive series of inserts, updates and deletes to live rows.
Controlled publication: persistence may take as long as required; publication is reduced to switching the release pointer for one (scope, scopeId) pair.
Transaction-like atomic visibility with parallel persistence: readers receive the same all-or-nothing visibility benefit expected from a transaction, while independent parents, children and other dependencies can be persisted concurrently under the same buildStrate. The candidate graph remains hidden until every required persistence task has completed and the release pointer is switched. This avoids serializing a large dependency graph solely to protect readers from partial state and can substantially reduce the duration of complex persistence workflows.
Retained history: previous immutable snapshots remain available until garbage collection, making audit, comparison and restoration possible.
Practical rollback: a previously released build can be selected again when it is still retained and valid.
Independent aggregate releases: each scope identifier has its own release pointer, so one catalog, booking or tenant can be rebuilt without publishing changes for the others.
Consistent relation graphs: when buildStrate participates in entity and relation identifiers, parent and child rows are persisted and queried from the same snapshot.

Typical use cases include catalog generation, denormalized read models, pricing computation, availability planning, large imports, configuration publication and any persistence workflow where readers must never observe an intermediate state.

Transaction safety and parallel dependency persistence¶

A conventional transaction protects readers from intermediate writes by keeping all dependent persistence operations inside one transaction boundary. For a large graph, this often means holding one transaction open while dependencies are persisted in sequence, or introducing complex coordination when several workers are involved.

Strates provides the same reader-facing atomic publication benefit without requiring every dependency to be persisted serially. All workers write into the same unreleased buildStrate; therefore, parent entities, child collections, relation rows and computed dependencies may be persisted in parallel. Released queries continue to read the previous build throughout that work. Only after every persistence branch succeeds is the release pointer changed, making the completed graph visible as one coherent state.

released build A remains visible
            │
            ├── persist parent for build B ──────────┐
            ├── persist child group 1 for build B ──┤
            ├── persist child group 2 for build B ──┤── run concurrently
            └── persist relation rows for build B ──┘
                                                    │
                              all branches complete │
                                                    ▼
                                       release B atomically

This model is particularly effective for aggregates with many independent dependencies because elapsed persistence time approaches the duration of the slowest branch rather than the sum of every branch.

Atomic publication is not a replacement for every database transaction

Database transactions are still required where local ACID guarantees are needed—for example inside each worker or when updating release metadata. Strates removes the need to use one long, serial transaction as the only mechanism protecting readers from partial graph persistence.

Persistence model compared with direct updates¶

Direct in-place persistence	Strates persistence
Updates the state currently visible to readers	Writes a candidate state under a new `buildStrate`
Readers may observe an intermediate state unless the entire operation fits in one transaction	Released queries remain pinned to the previous snapshot during the build
Dependency persistence is commonly serialized inside one long transaction	Independent dependencies can be persisted in parallel under the same unreleased `buildStrate`
Rollback often requires compensating updates or a backup restore	A retained previous build can be released again
Deletes and update ordering are part of the replacement algorithm	The next complete snapshot replaces the previous one through the release pointer
History requires separate audit infrastructure	Old snapshots naturally remain stored until garbage collection

Strates does not remove the need for database constraints, transaction boundaries or validation. It changes the persistence model so that building a state and making that state visible are separate operations. Storage consumption is consequently higher than with in-place updates, and obsolete builds must be removed through the provided garbage-collection mechanisms.

Documentation chapters¶

Chapter 1 Concepts and installation

Install the package and understand scopes, builds, releases and metadata tables.

Chapter 2 Entities and configuration

Prepare stratified entities, identifiers and manager configuration.

Chapter 3 Build, release and query

Create a candidate snapshot, persist it, release it and query the active build.

Chapter 4 Relation graphs

Keep parent, child and relation rows aligned on one snapshot.

Chapter 5 Garbage collection

Remove obsolete builds safely through deletion or partition strategies.

Chapter 6 Operations and troubleshooting

Understand production constraints, exceptions and PostgreSQL considerations.