Skip to content

Transactions and persistence threads

A persistence thread batches insert, update and delete operations for one connection.

$thread = $userManager->getConnection()->createPersistThread();

$thread
    ->pushPersist($user)
    ->pushPersist($project)
    ->pushDelete($obsoleteProject)
    ->flush();

flush() executes queued statements without wrapping them in a transaction.

Commit a transactional batch

$thread = $userManager->getConnection()->createPersistThread();

try {
    $thread
        ->pushPersist($user)
        ->pushPersist($project)
        ->commit();
} catch (Throwable $exception) {
    $thread->rollback();
    throw $exception;
}

In Core 3.0, commit() requires a transaction-capable persistence adapter. It then obtains one native driver connection. When that driver exposes PDO-style beginTransaction() and commit() methods, the thread starts a transaction, executes the queued statements on that connection, commits and returns the connection to the pool.

PostgreSQL native-driver behavior

The Core 3.0 PostgreSQL connection uses native PgSql\Connection, which does not expose the PDO transaction methods checked by PersistThread::commit().

In that case Core falls back to flush() rather than providing a native transactional commit. Code that requires strict PostgreSQL transaction semantics must therefore use a path that explicitly guarantees them instead of assuming PersistThread::commit() is atomic for the native PostgreSQL driver.

This distinction is particularly important for higher-level persistence strategies such as Strates: snapshot publication can provide reader-facing version isolation even when individual persistence branches use their own transaction boundaries.

Persistence threads and concurrency

A PersistThread batches work for one connection. It is not itself a scheduler for independent application tasks.

Swoole/OpenSwoole applications can execute independent persistence workflows concurrently when their data dependencies allow it, subject to connection-pool and database capacity. Each workflow can use its own persistence thread and local transaction boundary.

For versioned snapshot workloads, see Strates architecture and parallel persistence.

Entity collections

$users->persist();
$users->delete();

When supported by the connection, collection persistence uses one persistence thread. Small Swoole DB reads the generated identifier after every insert; SQL drivers keep normal batched behavior.

Next chapter: Backups and change detection

Planned Core 3.2: explicit transactional operations

The development branch adds the following API to relational Entity Managers:

  • withinTransaction(callable $callback, mixed $driverConnection = null) — opens and commits a transaction when the manager owns the connection. When provided a connection, it requires an already active transaction and leaves commit/rollback to its caller.
  • withNamedLock(string $name, callable $callback, int $timeoutSeconds = 5) — keeps a session-scoped advisory lock and its pooled connection leased for the entire callback, even across several transactions. MySQL uses GET_LOCK/RELEASE_LOCK; PostgreSQL uses a 64-bit advisory-lock hash.
  • assertActiveDatabase(mixed $driverConnection) — compares the database selected by a native connection against ORM configuration before coordinated writes.
  • SqlState::from(Throwable $error), SqlState::isDuplicateKey(...) and SqlState::isDeadlock(...) — unwrap driver diagnostics without conflating unique-key violations with foreign-key errors.

A connection acquired inside withinTransaction() is returned to the pool when finished. Never allow different coroutines to use a single native handle at the same time; a named lock held on one MySQL session does not protect operations run outside its lock discipline. These additions are not present in Core 3.1.0.

See atomic upserts and typed expressions.