Decree.Store.AppendError (decree v0.1.0)

Copy Markdown View Source

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's postgres.code, such as :serialization_failure), or nil when the error carries no SQLSTATE.
  • reason — the original error term, kept for callers. The store never logs it whole: message/1 reduces it with Decree.Store.LogTerms.reduce/1, as it can carry the failing row's values.

Classes

classSQLSTATE classesSQLSTATE codesother errors
:unavailable08 (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_errorDBConnection.ConnectionError; a Postgrex.Error without SQLSTATE fields (Postgrex's disconnect when the connection breaks mid-query)
:retryable40 (transaction rollback), 55 (object not in prerequisite state)
:rejectedany other40002 transaction_integrity_constraint_violationPostgrex.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 a statement_timeout also raises, and admin_shutdown, crash_shutdown, cannot_connect_now, idle_session_timeout, database_dropped;
  • read_only_sql_transaction is a write that reached a primary a failover has demoted;
  • idle_in_transaction_session_timeout means the server ended the session;
  • statement_completion_unknown leaves the outcome unknown, as a lost connection does;
  • transaction_integrity_constraint_violation is a deferred constraint failure, which fails again on a retry;
  • 58P01 undefined_file and 58P02 duplicate_file stay :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

class()

@type class() :: :unavailable | :retryable | :rejected

t()

@type t() :: %Decree.Store.AppendError{
  class: class(),
  code: atom() | nil,
  reason: term()
}

Functions

from_error(error)

@spec from_error(term()) :: t()

Classify an error the appender's statement returned.

message(append_error)

@spec message(t()) :: String.t()

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.