Skip to main content

SqliteEventStoreError

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),
}
Available on crate feature 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
Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.
§

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.

Fields

§found: u32

The version the file carries.

§supported: u32

The version this build knows.

§

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.

Fields

§found: u32

The version the file carries.

§required: u32

The version this build writes.

§

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.

Fields

§len: usize

How many bytes the row actually held.

§

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

§handle: StoreId

What this handle read at construction, and would have stamped with.

§persisted: StoreId

What the file carries now.

§

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: SequencePosition

Where the unstamped row sits.

§

CorruptTags

The canonical tag column of a stored row is not UTF-8.

§

OriginPositionOutOfRange

Available on crate feature 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: SequencePosition

The position the origin assigned.

§

StoredGuard

Available on crate feature 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: SequencePosition

The write group the guard belongs to.

§source: GuardCodecError

Why the codec refused it.

§

GroupOrder(GroupOrderError)

Available on crate feature 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.

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

The remedy this failure calls for.
§

impl Debug for SqliteEventStoreError

§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
§

impl Display for SqliteEventStoreError

§

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
§

impl Error for SqliteEventStoreError

§

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any. Read more
1.0.0 · Source§

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

1.0.0 · Source§

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

Source§

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)
Provides type-based access to context intended for error reports. Read more
§

impl From<Error> for SqliteEventStoreError

§

fn from(source: Error) -> Self

Converts to this type from the input type.
§

impl From<GroupOrderError> for SqliteEventStoreError

§

fn from(source: GroupOrderError) -> Self

Converts to this type from the input type.
§

impl From<InvalidEventType> for SqliteEventStoreError

§

fn from(source: InvalidEventType) -> Self

Converts to this type from the input type.
§

impl From<InvalidTag> for SqliteEventStoreError

§

fn from(source: InvalidTag) -> Self

Converts to this type from the input type.
§

impl From<JoinError> for SqliteEventStoreError

§

fn from(source: JoinError) -> Self

Converts to this type from the input type.
§

impl From<TryCurrentError> for SqliteEventStoreError

§

fn from(source: TryCurrentError) -> Self

Converts to this type from the input type.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToString for T
where T: Display + ?Sized,

Source§

fn to_string(&self) -> String

Converts the given value to a String. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.