Class OracleEventStore
- Namespace
- Excalibur.EventSourcing.Oracle
- Assembly
- Excalibur.EventSourcing.Oracle.dll
Oracle Database implementation of IEventStore.
public sealed class OracleEventStore : IEventStoreErasure, ITransactionalEventStore, IEventStore, IServiceProvider, ITransactionalProjectionEventStore
- Inheritance
-
OracleEventStore
- Implements
- Inherited Members
Remarks
Provides atomic event appends with optimistic concurrency control. Because Oracle has no rowversion,
concurrency is enforced by reading the current stream version and comparing it inside a
ReadCommitted transaction before the append; a mismatch yields
CreateConcurrencyConflict(long, long?) directly. The pre-check narrows the race
window but is not itself atomic under ReadCommitted, so the shipped UNIQUE(AGGREGATEID,
AGGREGATETYPE, VERSION, TENANTID) constraint (per aggregate stream) is the actual backstop: a loser
that slips past the pre-check hits ORA-00001 on INSERT, which IsStreamUniqueViolation(Exception) /
IsLostRace(Exception, long?, long) classify as the same CreateConcurrencyConflict(long, long?).
Converges Oracle onto the same ReadCommitted + UNIQUE-constraint pattern Postgres and SQL Server already
use, retiring the SERIALIZABLE isolation and its ORA-08177 bounded-retry loop this store carried
previously — atomicity of a multi-row append comes from the transaction boundary, not the isolation
level, so neither depended on SERIALIZABLE in the first place.
Supports pluggable serialization via IPayloadSerializer for event payloads, with a System.Text.Json fallback for backward compatibility.
Constructors
OracleEventStore(Func<OracleConnection>, ILogger<OracleEventStore>, ITenantContext, IPayloadSerializer?, string, string, IJsonTypeInfoResolver?)
Initializes a new instance of the OracleEventStore class with a connection factory.
public OracleEventStore(Func<OracleConnection> connectionFactory, ILogger<OracleEventStore> logger, ITenantContext tenantContext, IPayloadSerializer? payloadSerializer = null, string schema = "EXCALIBUR", string table = "EVENTSTOREEVENTS", IJsonTypeInfoResolver? eventTypeInfoResolver = null)
Parameters
connectionFactoryFunc<OracleConnection>A factory that creates Oracle.ManagedDataAccess.Client.OracleConnection instances.
loggerILogger<OracleEventStore>The logger instance.
tenantContextITenantContextThe ambient tenant context. Required: this store partitions rows by tenant, and it resolves that partition from here, so there is no state in which the partition is undecided. A single-tenant host receives the framework default context and operates as the one canonical tenant.
payloadSerializerIPayloadSerializerOptional pluggable serializer for event payloads.
schemastringThe schema name for the event store table. Default: "EXCALIBUR".
tablestringThe event store table name. Default: "EVENTSTOREEVENTS".
eventTypeInfoResolverIJsonTypeInfoResolverAn optional source-generated JSON type-info resolver covering the application's domain event types and the runtime types of the values it places in Metadata. Supplied, the store serializes without reflection, which is what a native-AOT host published with reflection-based serialization disabled requires. Omitted, the store serializes through the reflection-based serializer exactly as before, so an existing caller is unaffected. The stored wire format is byte-identical either way.
OracleEventStore(string, ILogger<OracleEventStore>, ITenantContext)
Initializes a new instance of the OracleEventStore class.
public OracleEventStore(string connectionString, ILogger<OracleEventStore> logger, ITenantContext tenantContext)
Parameters
connectionStringstringThe Oracle connection string.
loggerILogger<OracleEventStore>The logger instance.
tenantContextITenantContextThe ambient tenant context. Required: this store resolves the tenant partition it reads and writes from here.
Methods
AppendAsync(string, string, IEnumerable<IDomainEvent>, long, CancellationToken)
Appends events to the store with optimistic concurrency control.
public ValueTask<AppendResult> AppendAsync(string aggregateId, string aggregateType, IEnumerable<IDomainEvent> events, long expectedVersion, CancellationToken cancellationToken)
Parameters
aggregateIdstringThe aggregate identifier. Must not be null, empty, or white space.
aggregateTypestringThe aggregate type name. Must not be null, empty, or white space.
eventsIEnumerable<IDomainEvent>The events to append. Must not be null.
expectedVersionlongThe version the stream is expected to currently be at, or
-1when the stream does not yet exist. See the version base stated in the remarks below.cancellationTokenCancellationTokenCancellation token.
Returns
- ValueTask<AppendResult>
The result of the append operation, carrying the stream's version after the append in NextExpectedVersion.
Remarks
Version base. Stream versions are zero-based and contiguous. The first event appended to a
new stream is version 0, and each subsequent event takes the next integer. A stream that
does not yet exist has no current version, which expectedVersion expresses as
-1. Appending N events to a new stream therefore leaves it at version N-1:
that is the value NextExpectedVersion reports, and the value the next
append must pass as expectedVersion — it is the version the stream is now at,
not the version the next event will receive. Appending no events leaves the version unchanged and
reports back the version it was given.
An identifier that is null, empty, or white space is a usage error, never a legitimate stream: accepting one would fabricate a stream key and write events where no reader will ever look. Every implementation therefore rejects such an argument by throwing, rather than reporting a failed AppendResult — a returned result models a domain or infrastructure outcome, not a caller defect. Implementations validate their arguments before any I/O or concurrency check is attempted.
Outcome or defect. The line between a returned AppendResult and a thrown exception is whether the identical call could ever succeed without a change to the calling program. A version clash could, once the caller reloads, so it is reported as a result carrying IsConcurrencyConflict; an infrastructure fault may be reported as Failed only when non-commit is established. A lost commit acknowledgement with inconclusive recovery is Unknown, even if a later read sees a different stream version or no matching rows. Retry classification does not establish commit certainty. An event type the configured resolver does not declare could not — no retry, reload or reconfiguration reaches it — so it throws, as do a blank identifier, a batch above the provider's atomic limit, and cancellation. Every implementation of this interface answers the same way; a caller may rely on that rather than on which provider is configured.
Cancellation propagates. A cancelled append raises OperationCanceledException rather than reporting a failed result: reporting it as a store failure would invite a caller to retry inside a scope that has already been cancelled. Cancellation after dispatch does not prove rollback. Reconcile outside the cancelled operation using the original tenant, stream, event identities, payloads and expected version; do not regenerate events or rebase the append merely because its acknowledgement was not received.
Confined to the ambient tenant established for this store instance: the appended events join only
this tenant's stream for aggregateId, and the optimistic-concurrency check
against expectedVersion is evaluated within that same partition — another
tenant holding a stream under the same aggregateId can neither cause nor observe
a conflict here.
Exceptions
- ArgumentException
aggregateIdoraggregateTypeis empty or white space.- ArgumentNullException
aggregateId,aggregateType, oreventsis null.- EventBatchTooLargeException
eventscontains more events than the underlying store can append atomically. The exception carries the offending count and the limit, so a caller may split the batch and retry.- EventTypeNotDeclaredException
An event's runtime type is not declared by the type-info resolver the host configured, so it cannot be serialized. Nothing is appended. The identical call cannot succeed until the type is declared, which is why this is thrown rather than reported as a failed AppendResult.
AppendWithOutboxStagingAsync(string, string, IEnumerable<IDomainEvent>, long, Func<IDbTransaction, CancellationToken, ValueTask>, CancellationToken)
Appends events and stages outbox messages within a single atomic database transaction.
public ValueTask<AppendResult> AppendWithOutboxStagingAsync(string aggregateId, string aggregateType, IEnumerable<IDomainEvent> events, long expectedVersion, Func<IDbTransaction, CancellationToken, ValueTask> stageOutbox, CancellationToken cancellationToken)
Parameters
aggregateIdstringThe aggregate identifier.
aggregateTypestringThe aggregate type name.
eventsIEnumerable<IDomainEvent>The events to append.
expectedVersionlongThe expected current version (-1 for a new aggregate).
stageOutboxFunc<IDbTransaction, CancellationToken, ValueTask>A callback that stages outbox messages on the supplied transaction. It is invoked only when the version check succeeds, before the events are appended and before commit. It must not depend on the version or global position the append assigns; neither is available to it.
cancellationTokenCancellationTokenCancellation token.
Returns
- ValueTask<AppendResult>
The result of the append operation.
Remarks
The store opens one connection and one transaction, performs the optimistic-concurrency
version check, invokes stageOutbox on the same transaction, appends the
events, then commits. A failed version pre-check does not invoke stageOutbox.
A later conflict can occur after staging; a proven rollback discards both events and staged rows.
Lost commit acknowledgement can leave both durable and must be reported as Unknown unless
reconciliation establishes the complete operation. Callback faults before commit propagate and
abort the store-owned transaction. The callback must not commit it, open independent writes or
perform external effects; the supplied transaction does not enforce that discipline by itself.
Staging runs before the events are appended, and the callback must not depend on anything the append produces. A provider with a global event position allocates it from a shared counter whose lock is held until commit, so every appender in the process is blocked for as long as that transaction runs. Staging is one round trip per message, so performing it after the append would place all of those round trips inside that window. The ordering is therefore a throughput property, not a correctness one — atomicity is identical either way — and it is only available because the callback receives the transaction and nothing else. Do not widen the callback to expose the assigned version or position: that would force staging back inside the window and reduce sustained append throughput for every consumer of the provider.
A concurrency conflict is classified the same way whether it is caught by the in-transaction version pre-check or lost to a genuine race that slips past it (two callers both pass the pre-check, then race at insert/commit — the database's own uniqueness constraint on the stream key decides the loser). Either shape yields CreateConcurrencyConflict(long, long?), matching AppendAsync(string, string, IEnumerable<IDomainEvent>, long, CancellationToken)'s contract on the same provider. A changed stream version after a lost commit acknowledgement does not establish a conflict: it may include this append. An inconclusive commit outcome is Unknown. Callback faults before commit propagate as their original exceptions. Cancellation propagates as cancellation, but cancellation after commit dispatch does not establish rollback; callers must reconcile the original operation before retrying or issuing dependent effects.
AppendWithProjectionsAsync(string, string, IReadOnlyList<IDomainEvent>, long, Func<ProjectionTransaction, CancellationToken, ValueTask>, CancellationToken)
Appends events and projection changes in one transaction.
public ValueTask<AppendResult> AppendWithProjectionsAsync(string aggregateId, string aggregateType, IReadOnlyList<IDomainEvent> events, long expectedVersion, Func<ProjectionTransaction, CancellationToken, ValueTask> apply, CancellationToken cancellationToken)
Parameters
aggregateIdstringStream identifier.
aggregateTypestringStream type.
eventsIReadOnlyList<IDomainEvent>New events.
expectedVersionlongExpected last persisted version, or -1 for a new stream.
applyFunc<ProjectionTransaction, CancellationToken, ValueTask>Callback before append, using authoritative history and the supplied transaction.
cancellationTokenCancellationTokenCancellation token. Cancellation does not prove rollback after commit dispatch.
Returns
- ValueTask<AppendResult>
The confirmed or uncertain append outcome.
EraseEventsAsync(string, string, Guid, CancellationToken)
Erases all event payloads for the specified aggregate, replacing them with a tombstone marker.
public Task<int> EraseEventsAsync(string aggregateId, string aggregateType, Guid erasureRequestId, CancellationToken cancellationToken)
Parameters
aggregateIdstringThe aggregate whose events should be erased.
aggregateTypestringThe aggregate type name.
erasureRequestIdGuidThe GDPR erasure request tracking ID for audit purposes.
cancellationTokenCancellationTokenCancellation token.
Returns
Remarks
Confined to the ambient tenant established for this store instance: tombstones events only in the
caller's own tenant's stream for aggregateId, and cannot reach or be triggered
by another tenant's stream under the same identifier.
IsErasedAsync(string, string, CancellationToken)
Checks whether erasure has been performed for the specified aggregate.
public Task<bool> IsErasedAsync(string aggregateId, string aggregateType, CancellationToken cancellationToken)
Parameters
aggregateIdstringThe aggregate identifier.
aggregateTypestringThe aggregate type name.
cancellationTokenCancellationTokenCancellation token.
Returns
Remarks
Confined to the ambient tenant established for this store instance: answers for the caller's own tenant's stream, never another tenant's stream under the same identifier.
LoadAsync(string, string, long, CancellationToken)
Loads events for an aggregate from a specific version.
public ValueTask<IReadOnlyList<StoredEvent>> LoadAsync(string aggregateId, string aggregateType, long fromVersion, CancellationToken cancellationToken)
Parameters
aggregateIdstringThe aggregate identifier. Must not be null, empty, or white space.
aggregateTypestringThe aggregate type name. Must not be null, empty, or white space.
fromVersionlongThe version to start loading from, exclusive: the result begins at the next version after this one. Versions are zero-based, so
-1loads the whole stream. See the version base stated on AppendAsync(string, string, IEnumerable<IDomainEvent>, long, CancellationToken).cancellationTokenCancellationTokenCancellation token.
Returns
- ValueTask<IReadOnlyList<StoredEvent>>
The events for the aggregate from the specified version in order.
Remarks
Confined identically to the zero-argument overload above: none of another tenant's events for
this aggregateId, and every one of the caller's own from
fromVersion onward.
Exceptions
- ArgumentException
aggregateIdoraggregateTypeis empty or white space.- ArgumentNullException
aggregateIdoraggregateTypeis null.
LoadAsync(string, string, CancellationToken)
Loads all events for an aggregate.
public ValueTask<IReadOnlyList<StoredEvent>> LoadAsync(string aggregateId, string aggregateType, CancellationToken cancellationToken)
Parameters
aggregateIdstringThe aggregate identifier. Must not be null, empty, or white space.
aggregateTypestringThe aggregate type name. Must not be null, empty, or white space.
cancellationTokenCancellationTokenCancellation token.
Returns
- ValueTask<IReadOnlyList<StoredEvent>>
The events for the aggregate in version order.
Remarks
Confined to the ambient tenant established for this store instance: returns none of another
tenant's events for this aggregateId, and every one of the caller's own — a
store that returns fewer than the caller's own full history satisfies neither this contract nor
the aggregate that must replay from it.
Exceptions
- ArgumentException
aggregateIdoraggregateTypeis empty or white space.- ArgumentNullException
aggregateIdoraggregateTypeis null.