Skip to content
Versioned snapshot persistence · 1.0.0

Strates package documentation

Build complete relational states in isolation, version every snapshot with a UUID v7, persist independent dependency branches concurrently, and publish one coherent state through a release pointer. This documentation is checked against Strates 1.0.0 and Core 3.0.0.

Versioning

Immutable snapshots

Several business-state versions can coexist under distinct buildStrate values.

Visibility

Release pointer

Readers stay on the previous complete state until the candidate snapshot is published.

Performance

Parallel persistence

Independent graph branches can be scheduled concurrently while the candidate remains unreleased.

Reliability

Failure isolation

A failed candidate never replaces the currently released snapshot.

Build privately, publish explicitly

Strates changes the persistence model from update the live state to build the next version.

Every candidate receives a UUID v7 buildStrate. Business rows belonging to that candidate are persisted with the same build identifier. Released queries continue to use the previous buildStrate until released_strates points to the new one.

released snapshot A
        |
        +----------------------------- readers continue using A
        |
        +-- build snapshot B
        |      +-- parent rows
        |      +-- independent branch 1
        |      +-- independent branch 2
        |      +-- dependent relation rows
        |
        +-- all required writes succeed
               |
               +-- release pointer A -> B

The release pointer, not a flag duplicated across every business row, is the source of truth for the active state.

Architectural benefits

  • Versioning: each complete candidate is a distinct snapshot that can coexist with the currently released version.
  • No partial reader state: unreleased rows are excluded from released-data queries.
  • Parallel persistence where dependencies allow it: independent branches can be scheduled concurrently because none becomes visible before release.
  • Shorter critical persistence path: elapsed time can approach the longest independent branch rather than the sum of every branch, when the database and connection pool can sustain the concurrency.
  • Failure isolation: a failed build remains unreleased; readers keep using the previous state.
  • Constant-size publication model: publishing changes release metadata instead of rewriting the complete graph.
  • Explicit relational boundaries: buildStrate participates in relation mappings so parent, child and join rows cannot cross snapshot versions.
  • Controlled retention: obsolete versions can be removed later with delete- or partition-based garbage collection.

Parallelism is enabled, not automatic

Strates does not make persistMany() concurrent. The application owns coroutine/job scheduling and must respect foreign-key dependencies. The package provides the snapshot boundary that makes concurrent persistence safe from a reader-visibility perspective.

Transaction boundaries

Snapshot publication is not a replacement for transactions.

Use local transactions when a persistence branch needs ACID guarantees. The key difference is that one long transaction no longer has to cover the entire graph merely to prevent readers from seeing an intermediate state.

worker A -> local persistence/transaction -> build B
worker B -> local persistence/transaction -> build B
worker C -> local persistence/transaction -> build B

wait for all required workers
            |
            v
         release B

This model is well suited to large catalogs, pricing calculations, availability planning, imports, external synchronization and generated read models.

Version model

The business version key is conceptually:

scope + scopeId + buildStrate

For example:

catalog / shop-42 / strate-A
catalog / shop-42 / strate-B
catalog / shop-99 / strate-C

Only one strate is released for each (scope, scopeId) pair:

released_strates

catalog / shop-42 -> strate-B
catalog / shop-99 -> strate-C

This allows one tenant, catalog or aggregate to be rebuilt independently of the others.

Documentation chapters

Chapter 1 Concepts and installation

Install Strates 1.0 and understand scopes, versions, releases and metadata tables.

 Chapter 2 Entities and configuration

Prepare stratified entities, identifiers, roots and manager configuration.

 Chapter 3 Build, release and query

Create a candidate snapshot, persist it, publish it and query the active version.

 Chapter 4 Relation graphs

Keep parent, child and join rows aligned and identify safe concurrency boundaries.

 Chapter 5 Garbage collection

Remove superseded versions safely through deletion or partition strategies.

 Chapter 6 Operations and troubleshooting

Understand concurrency limits, failure handling and PostgreSQL Core 3 behavior.

 Architecture Versioning and parallel persistence

See why the snapshot model allows independent transaction items to run concurrently.