Optimistic locking

Release Notes

New Feature: Optimistic Locking Support

ObjectQuel now supports optimistic locking through the @Orm\Version annotation, preventing lost updates in concurrent access scenarios.

Overview

Optimistic locking detects conflicts at commit time rather than locking records upfront. When multiple processes attempt to modify the same entity, only the first succeeds—subsequent attempts fail with a version mismatch error.

Usage

Add @Orm\Version to any property:

/**
 * @Orm\Column(name="version", type="integer", unsigned=true)
 * @Orm\Version
 */
protected ?int $version = null;

Supported Column Types

• integer: Auto-increments by 1 (starts at 1)
• datetime: Uses database NOW()
• uuid: Generates new GUID

Behavior

INSERT: Version initializes to 1 (integer), current time (datetime), or new GUID (uuid)

UPDATE: Version automatically increments/updates and is included in WHERE clause. Zero affected rows throws OrmException.

Example

// Process A loads entity
$product = $em->find(Product::class, 1); // version = 5
$product->setName("New Name");

// Process B updates same entity (version becomes 6)

// Process A flush fails
$em->flush(); // OrmException: version mismatch

Technical Implementation

• Version columns excluded from change detection
• Automatic version updates via SQL expressions (no round-trip required)
• Post-update SELECT fetches new version values for in-memory synchronization
• Values properly normalized according to property type annotations