Enum SqliteEventStoreError
#[non_exhaustive]pub enum SqliteEventStoreError {
Show 17 variants
Sqlite(Error),
ConnectionPoisoned,
Worker(JoinError),
NoRuntime(TryCurrentError),
InvalidPosition(i64),
StoredEventType(InvalidEventType),
StoredTag(InvalidTag),
UnsupportedSchemaVersion {
found: u32,
supported: u32,
},
SchemaNeedsMigration {
found: u32,
required: u32,
},
MissingIdentity,
MalformedIdentity {
len: usize,
},
IdentityMoved {
handle: StoreId,
persisted: StoreId,
},
UnstampedEvent {
position: SequencePosition,
},
CorruptTags,
OriginPositionOutOfRange {
position: SequencePosition,
},
StoredGuard {
first: SequencePosition,
source: GuardCodecError,
},
GroupOrder(GroupOrderError),
}event-store only.Expand description
How SqliteEventStore fails.
Every variant names something rusqlite or the surrounding runtime can
actually produce. Append-condition violations are not here: they travel
through AppendError::ConditionViolated, so a caller can tell “rebuild the
decision model and retry” from “something broke” without knowing which
adapter it holds.
Variants (Non-exhaustive)§
This enum is marked as non-exhaustive
Sqlite(Error)
The driver failed: I/O, SQLITE_BUSY, a constraint, a bad statement.
On an append this arrives in one of two arms. A SQLITE_BUSY or
SQLITE_LOCKED from BEGIN IMMEDIATE — the write lock not acquired
within the busy timeout, before anything was written — is carried by
AppendError::Busy; every other driver failure, a busy code raised
later included, by AppendError::Store.
ConnectionPoisoned
A thread panicked while holding the connection mutex.
Carried as a unit variant rather than wrapping
std::sync::PoisonError, because that type is generic over the guard
and the guard borrows the connection — it is neither 'static nor
Send, and EventStore::Error
requires 'static.
Worker(JoinError)
The blocking task carrying a query panicked or was cancelled.
NoRuntime(TryCurrentError)
A stream was polled outside a tokio runtime, so no blocking task could be spawned.
See the module documentation for why this is an error rather
than the panic spawn_blocking would otherwise raise.
InvalidPosition(i64)
A stored row carried a position SQLite accepted and the contract does
not: SequencePosition wraps a NonZeroU64, so zero and negatives
are unrepresentable.
StoredEventType(InvalidEventType)
A stored row carried an event type that no longer validates.
StoredTag(InvalidTag)
A stored row carried a tag that no longer validates.
UnsupportedSchemaVersion
The file was written by a build that knows a later migration.
Refusing is the point: operating on an unknown schema is how a later migration loses data, and the version marker exists precisely so that migration 2 has something to test against.
SchemaNeedsMigration
The file is at an older schema version than this build writes, and
SqliteEventStore::new, which never migrates, was asked to wrap it.
Refused here rather than at the first append, which would otherwise
fail with an untyped driver error naming a column the older schema
lacks. Open the file with SqliteEventStore::open_on or
SqliteEventStore::open, which apply the missing migrations, and
wrap it with new afterwards if that is still wanted.
MissingIdentity
The schema is present and its incarnation row is not.
A distinct variant rather than a driver error, because the honest
alternative — minting a replacement — re-issues EventIds under a new
origin for events that already exist, and that failure has no error path
and no observable symptom until a replication peer sees one identity
twice.
MalformedIdentity
The incarnation row is present and is not sixteen bytes.
IdentityMoved
This handle mints identities under an incarnation the file has retired.
remint_identity’s documented
procedure says to run it “with nothing else holding the database open”,
and until this variant existed nothing enforced it. A handle reads the
incarnation once, at construction, so a handle that outlives a re-mint
goes on stamping EventIds under the retired one — which is the
failure VT-6’s own Rejects: paragraph calls “the one failure mode in
the replication design with no error path and no observable symptom”.
The narrow case, and it is deliberately narrow. VT-6 accepts the undetectable ones — a file restored from a backup by another process, a copy taken while nothing was running — because SQLite cannot see them. This is the one a program can see: the split happened inside this process, and the persisted identity is readable under the lock the writer is already holding.
Both incarnations are carried because one of them is not actionable: the answer is drop this handle and reopen, and knowing which handle is stale is the whole of the diagnosis.
Fields
UnstampedEvent
A stored row carries no event identity.
Unreachable if the write path is correct — append stamps the origin
pair onto every row of the batch before it commits — and reported rather
than panicked so that a schema mistake surfaces as a failing rule naming
this store rather than as a crash naming the suite.
Fields
position: SequencePositionWhere the unstamped row sits.
CorruptTags
The canonical tag column of a stored row is not UTF-8.
OriginPositionOutOfRange
sync only.A replicated event’s origin position does not fit SQLite’s INTEGER.
Refused rather than saturated, because on the ingest path a position is
half an EventId: two such events from one origin would collapse onto
one stored identity and the second would be counted as a re-delivery.
Produced only by ingest, behind sync. The enum is #[non_exhaustive],
so a variant that appears under a feature breaks no exhaustive match.
Fields
position: SequencePositionThe position the origin assigned.
StoredGuard
sync only.A write group’s guard could not be put into, or read back out of,
group_guard in happenstance-sync’s stored form (#420).
On a read it means the column holds bytes no build of that codec
wrote, a format from a newer build or a damaged file, and the read
stops rather than forward the group without the guard it arrived
under. Behind sync, with the codec.
Fields
first: SequencePositionThe write group the guard belongs to.
source: GuardCodecErrorWhy the codec refused it.
GroupOrder(GroupOrderError)
sync only.A row’s write_group names a group the read had already passed, so the
log cannot be paged in whole groups. This store writes every group’s
rows contiguously and names each by its first, so only a damaged or
hand-edited file holds one.
Trait Implementations§
§impl Classify for SqliteEventStoreError
Available on crate feature sync only.SY-36’s class for each way this adapter fails.
impl Classify for SqliteEventStoreError
sync only.SY-36’s class for each way this adapter fails.
Exhaustive over this crate’s own enum, with no wildcard, so a new variant
does not compile until somebody decides its class. A busy code reaching
Store is Transient too: it is the same contention, raised after
BEGIN IMMEDIATE, and the transaction rolled back. So are a full disk, a
failed read or write and an exhausted allocator, which an operator or time
can fix while the batch waits. Every other driver failure is Stop: a
constraint, a corrupt file or a misused statement fails the same way again.
§fn class(&self) -> FailureClass
fn class(&self) -> FailureClass
§impl Debug for SqliteEventStoreError
impl Debug for SqliteEventStoreError
§impl Display for SqliteEventStoreError
impl Display for SqliteEventStoreError
§impl Error for SqliteEventStoreError
impl Error for SqliteEventStoreError
§fn source(&self) -> Option<&(dyn Error + 'static)>
fn source(&self) -> Option<&(dyn Error + 'static)>
1.0.0 · Source§fn description(&self) -> &str
fn description(&self) -> &str
use the Display impl or to_string()