Skip to main content

Redis configuration

Required persistence settings​

Redis is often used as a cache, but an event store is a system of record. The adapter checks these settings by default:

appendonly yes
appendfsync always        # everysec is an explicit throughput/durability trade-off
maxmemory-policy noeviction

RDB snapshots alone can lose events written since the last snapshot. An eviction policy can silently remove event streams. noeviction prevents Redis from evicting event data when a configured memory limit is reached.

Atomic event writes​

RedisEventStorage::storeEvents() uses one Lua script for the complete call. The script verifies all aggregate versions before its first XADD, writes the aggregate streams, advances the global sequence, and updates the global index. A rejected batch therefore writes nothing and can be retried as the same batch.

Each aggregate uses a Redis Stream key named events:aggregate:{aggregateId}. Stream IDs use 1-{version}. The global index is events:global, with events:global:seq as its monotonic counter.

Snapshots and process managers​

RedisSnapshotStorage stores the latest snapshot in a hash at snapshots:{aggregateId}. RedisSnapshotHistoryStorage uses sorted sets under snapshot_history:{aggregateId}.

RedisProcessManagerStorage stores state in process_manager:{processId} and keeps due timeouts in the process_manager_timeouts sorted set. The state write and timeout index update happen in one Lua script, so clearing a timeout cannot leave a stale timeout entry behind.

Outbox delivery​

Enable outbox enrollment on the event storage:

use DomainFlow\EventSourcing\Facade\EventSourcingFacade;
use DomainFlow\EventSourcing\Outbox\OutboxRelay;
use DomainFlow\EventSourcingRedis\Outbox\RedisOutboxStorage;
use DomainFlow\EventSourcingRedis\Storage\RedisEventStorage;

$storage = new RedisEventStorage($redis, outboxEnabled: true);
$outbox = new RedisOutboxStorage($redis, leaseSeconds: 300);

// Use the relay as the delivery path; do not also pass an inline dispatcher.
$facade = new EventSourcingFacade($storage);
$relay = new OutboxRelay($outbox, $dispatcher);

RedisEventStorage writes outbox entries inside its event Lua script. The separate RedisOutboxStorage owns claiming and marking entries for the relay; it is not passed into RedisEventStorage.

Claims use the Redis server clock, so multiple relay hosts agree on lease expiry. Delivery is at least once and not ordered across aggregates.

Redis Cluster​

Redis Cluster is not supported. The write script needs keys for every aggregate in the batch plus shared global and outbox keys. Those keys cannot reliably be placed in one cluster hash slot without turning the deployment into a single slot bottleneck. Use a single instance or Sentinel for failover.