StatifierPersistence.Ecto.KeyGenerator behaviour (StatifierPersistence v0.1.0)

Copy Markdown View Source

Behaviour a surrogate-key scheme implements for the Ecto layer.

ADR-0002 makes the surrogate primary keys of this package's tables compile-time configurable per host: :uxid (the default), :uuid (UUIDv7), :bigserial, or any {module, opts} implementing this behaviour. A key scheme must answer three questions - the Ecto schema field type, the migration column type, and how a key is generated (or that the database assigns it) - and both the generated schemas and the migrations helper read their answers from the same resolved generator, so the two cannot disagree.

Engine identities (the chart content hash, the engine session id, the caller's run id) are stored verbatim and are not touched by any key generator - ADR-0002 decision 1.

The bundled implementations:

Summary

Types

spelling()

ADR-0002's key option spellings.

table()

The tables whose rows carry a generated surrogate key.

Callbacks

autogenerate(table, opts)

The {module, function, args} an Ecto schema uses to autogenerate a primary key for a row of table, or nil when the database assigns the key itself.

ecto_type(opts)

The Ecto schema field type for the primary key, e.g. :string, Ecto.UUID, or :id.

migration_type(opts)

The column type the migrations helper emits for the primary key, e.g. :text, :uuid, or :bigserial.

Functions

resolve(other)

Resolves one of ADR-0002's key option spellings to {module, opts}.

Types

spelling()

@type spelling() :: :uxid | :uuid | :bigserial | {module(), keyword()}

ADR-0002's key option spellings.

table()

@type table() :: :charts | :positions | :runs

The tables whose rows carry a generated surrogate key.

Callbacks

autogenerate(table, opts)

@callback autogenerate(table(), opts :: keyword()) :: {module(), atom(), [term()]} | nil

The {module, function, args} an Ecto schema uses to autogenerate a primary key for a row of table, or nil when the database assigns the key itself.

ecto_type(opts)

@callback ecto_type(opts :: keyword()) :: atom()

The Ecto schema field type for the primary key, e.g. :string, Ecto.UUID, or :id.

migration_type(opts)

@callback migration_type(opts :: keyword()) :: atom()

The column type the migrations helper emits for the primary key, e.g. :text, :uuid, or :bigserial.

Functions

resolve(other)

@spec resolve(spelling()) :: {module(), keyword()}

Resolves one of ADR-0002's key option spellings to {module, opts}.

:uxid, :uuid, and :bigserial map onto the bundled implementations. A {module, opts} tuple passes through after a check that module declares this behaviour; anything else raises ArgumentError.