An append that the database did not accept, classified by what a caller can do about it.
append_to_stream/4 returns five failures of the
appender's statements as plain atoms, because they are domain answers:
{:error, :wrong_expected_version}, {:error, :duplicate_event},
{:error, :not_found}, {:error, :append_condition_failed} and (retried once
outside a caller's transaction, see below) {:error, :duplicate_stream_uuid}.
Every other failure of those statements is returned as
{:error, %Decree.Store.AppendError{}}, with these fields:
class— what a caller can do::unavailable— the database could not be reached, stopped serving, or cannot say whether the statement took effect. Retry after a wait, if the append is safe to retry (see below).:retryable— the same request may succeed if sent again.:rejected— the request itself was refused. Retrying the same request will not help.
code— the Postgres error code name (Postgrex.Error'spostgres.code, such as:serialization_failure), ornilwhen the error carries no SQLSTATE.reason— the original error term, kept for callers. The store never logs it whole:message/1reduces it withDecree.Store.LogTerms.reduce/1, as it can carry the failing row's values.
Classes
| class | SQLSTATE classes | SQLSTATE codes | other errors |
|---|---|---|---|
:unavailable | 08 (connection exception), 53 (insufficient resources), 57 (operator intervention) | 25P03 idle_in_transaction_session_timeout, 25006 read_only_sql_transaction, 40003 statement_completion_unknown, 58000 system_error, 58030 io_error | DBConnection.ConnectionError; a Postgrex.Error without SQLSTATE fields (Postgrex's disconnect when the connection breaks mid-query) |
:retryable | 40 (transaction rollback), 55 (object not in prerequisite state) | ||
:rejected | any other | 40002 transaction_integrity_constraint_violation | Postgrex.QueryError, DBConnection.OwnershipError, any other term |
A code listed in the codes column overrides its class. Notes on some entries:
- class 57 includes
query_canceled(57014), which astatement_timeoutalso raises, andadmin_shutdown,crash_shutdown,cannot_connect_now,idle_session_timeout,database_dropped; read_only_sql_transactionis a write that reached a primary a failover has demoted;idle_in_transaction_session_timeoutmeans the server ended the session;statement_completion_unknownleaves the outcome unknown, as a lost connection does;transaction_integrity_constraint_violationis a deferred constraint failure, which fails again on a retry;58P01undefined_fileand58P02duplicate_filestay:rejected.
Retrying
An :unavailable failure does not say whether the events were written. A
retry is safe only when the append is idempotent: the events have pinned
event ids (a retry of a written append then answers
{:error, :duplicate_event}), or the append names an expected version that a
committed earlier attempt has moved past (it then answers
{:error, :wrong_expected_version}). An event without an event_id gets a
fresh one on every call, so a retry with :any_version can write the events
twice.
A :retryable failure rolled back. append_to_stream/4 retries
deadlock_detected (40P01) once itself, from its stream-info read, and answers
the %AppendError{} if it comes back. It does not retry inside a caller's
transaction (:conn given a transaction): that transaction is aborted, and what
happens next is the caller's decision. Every other :retryable failure is the
caller's to retry.
Aggregates
An aggregate whose append answers an :unavailable error stops (exit reason
{:shutdown, :append_outcome_unknown}), whatever its lifespan says: the
events may have been written while its state is still the one before the
append, so the next command opens a fresh aggregate that rebuilds its state
from the stream. A command already queued for the stopped aggregate is
retried on the fresh one. A :retryable or :rejected error is a statement
Postgres rolled back, so the aggregate's state is still the stream's and it
keeps running; AppendError is a plain struct, not an exception, so
Decree.Aggregates.DefaultLifespan answers :infinity for it.
{:error, :duplicate_stream_uuid} means two writers raced to create the same
stream. append_to_stream/4 retries it once and then answers
{:error, {:already_retried_once, :duplicate_stream_uuid}}. It does not retry
inside a caller's transaction, which the race aborted: it answers
{:error, :duplicate_stream_uuid}.
Summary
Functions
Classify an error the appender's statement returned.
A one-line description for a log line: the class, the code, and the original
error reduced to its type and its code or reason (Decree.Store.LogTerms.reduce/1),
never its message, which can carry the values of the row it failed on.
Types
Functions
Classify an error the appender's statement returned.
A one-line description for a log line: the class, the code, and the original
error reduced to its type and its code or reason (Decree.Store.LogTerms.reduce/1),
never its message, which can carry the values of the row it failed on.