Skip to content

Operational constraints and troubleshooting

Required invariants

  • Write a complete immutable snapshot before calling release().
  • Use one explicit root manager when a scope contains several managers.
  • Register every dependency manager that must participate in garbage collection.
  • Include buildStrate in every relation mapping between stratified tables.
  • Keep metadata and business managers on the same database connection.
  • Treat released_strates as the only source of truth for the active snapshot.
  • Do not add a duplicated released flag to every business row.

Common exceptions

UnknownStratesScopeException
The scope was not supplied in the constructor configuration.
InvalidStratifiedEntityException
A manager lacks id, buildStrate or the configured scope-id field, or its entity does not implement StratifiedEntityInterface.
BuildNotFoundException
No build matches the supplied scope, scope id and strate.
UnsupportedDatabaseTypeException
Partition garbage collection received a connection other than the supported MySQL or PostgreSQL drivers.
RuntimeException during release
The build status is neither building nor released.

PostgreSQL core 2.7.x release path

The package deliberately bypasses PersistThread::commit() for PostgreSQL and calls flush(). In core 2.7.x, commit checks out a native PgSql\Connection, discovers that it has no PDO transaction methods, then falls back without returning that unused checkout. The direct flush avoids ConnectionNotInPoolException during coroutine shutdown.

This workaround preserves the effective non-transactional behavior of that fallback. Do not document PostgreSQL release as atomic unless the installed core version provides an explicit transaction-safe native path.

Test matrix represented by the supplied package

The supplied integration fixtures cover MySQL and PostgreSQL relation graphs, including:

  • one-to-one, one-to-many and join-entity many-to-many relations;
  • composite relation mappings with buildStrate;
  • unreleased snapshot invisibility;
  • release-pointer switching and idempotent release;
  • scope-id isolation;
  • failed and mismatched build handling;
  • garbage collection across dependency managers.