Skip to content

Concepts, installation and metadata schema

Purpose

Strates provides versioned snapshot persistence for relational data. Instead of modifying the rows currently visible to readers, the application writes the next complete business state under a new UUID v7 buildStrate, then publishes that state by switching one release pointer.

This separates two concerns that are usually coupled in a direct-update workflow:

  • persistence: build the next state, potentially over many tables and workers;
  • publication: make that completed state visible to readers.

The result is reader-facing all-or-nothing visibility without requiring the entire graph build to stay inside one long transaction.

Core concepts

  • scope: logical aggregate type, for example catalog, pricing or booking;
  • scope id: one independent instance of the scope, for example one shop or booking;
  • build strate: UUID v7 identifying one candidate snapshot;
  • root manager: manager used by released-data queries;
  • release pointer: active strate for one (scope, scopeId) pair.

Conceptually:

(scope, scopeId) -> released buildStrate

catalog / shop-42 -> 019c85a7-bec1-7284-93c7-b1a7fc52faca

Every row belonging to that snapshot carries the same buildStrate.

Why version the state?

A direct update changes the live dataset while it is being written. For a large relational graph, readers can therefore require one long transaction to avoid observing an intermediate state.

Strates keeps the released snapshot unchanged while the next version is built:

released A remains visible
        |
        +-- build B in isolation
        |      +-- persist branch 1
        |      +-- persist branch 2
        |      +-- persist branch 3
        |
        +-- all required work succeeded
               |
               +-- switch release pointer A -> B

Because B is not visible before release, independent persistence branches may be executed concurrently by the application. Strates does not automatically parallelize persistMany(); concurrency is an application/runtime concern enabled by the snapshot boundary.

Compatibility and installation

Strates 1.0.0 requires:

PHP >= 8.3
small/swoole-entity-manager-core 3.0.*

Install the package with Composer:

composer require small/swoole-entity-manager-strates

Install metadata tables

MySQL:

mysql app < vendor/small/swoole-entity-manager-strates/schema/mysql.sql

PostgreSQL:

psql app < vendor/small/swoole-entity-manager-strates/schema/postgres.sql

The package creates two metadata tables:

Table Purpose
stratified_build One row per build, with scope, scope id, lifecycle status and timestamps.
released_strates One unique release pointer per (scope, scope_id).

Business tables remain owned by the application. Every stratified business row must expose a mapped buildStrate field.

Build lifecycle

Build states are:

  • building: candidate snapshot is being assembled and is not released;
  • released: snapshot has been published at least once;
  • failed: candidate construction failed and must not be released;
  • garbage_collected: obsolete business rows were collected and metadata is ready for cleanup.

The metadata managers use the ORM default connection. The StratifiedBuildManager and ReleasedStrateManager must resolve to the same connection for release persistence.

Next chapter: Stratified entities and configuration