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¶
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 usesGET_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(...)andSqlState::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.