Rheo.Backend.Ecto (rheo v1.0.0)

Copy Markdown View Source

SQL implementation of Rheo.Backend on top of a host-owned Ecto.Repo.

Requires {:ecto_sql, "~> 3.11"} plus the adapter your repo uses ({:postgrex, "~> 0.19"} or {:ecto_sqlite3, "~> 0.17"}).

Supports PostgreSQL (Ecto.Adapters.Postgres) and SQLite (Ecto.Adapters.SQLite3). Prefer the Rheo facade for application code.

Supervision example

Your app supervises the repo; Rheo only borrows it.

children = [
  MyApp.Repo,
  {Rheo, name: MyRheo, backend: {Rheo.Backend.Ecto, repo: MyApp.Repo}}
]

The opaque handle is the registered name of Rheo.Backend.Ecto.Server, which holds the resolved repo, dialect, and options.

Tables

See Rheo.Backend.Ecto.Migrations. Rheo.ensure_indexes/1 creates them idempotently; hosts that prefer explicit migrations can run mix rheo.ecto.gen_migration instead.

Options

  • :repo — required Ecto.Repo module
  • :name — handle / process name (default default_handle/0)
  • :prefix — PostgreSQL schema holding the Rheo tables (default nil)
  • :notify — when true, NOTIFY rheo_events after every append (PostgreSQL only, default false)

Dialect differences

PostgreSQL claims work use FOR UPDATE SKIP LOCKED, so many nodes can fetch concurrently (distributed: true). SQLite has a single writer and claims inside a plain transaction, so it is declared distributed: false — correct for one node, not for a shared network filesystem.

Callback semantics are documented on Rheo.Backend.

Summary

Functions

capabilities(dialect)

Capabilities for a specific dialect or running handle.

child_spec(opts)

Child spec for the configuration process that acts as the backend handle.

default_handle()

Default handle name for the Rheo instance.

Functions

capabilities(dialect)

@spec capabilities(:postgres | :sqlite | Rheo.Backend.handle()) ::
  Rheo.Backend.Capabilities.t()

Capabilities for a specific dialect or running handle.

capabilities/0 describes the PostgreSQL defaults. Pass :sqlite (or a live handle) to get the flags that actually apply to an instance, including whether :notify was enabled.

Arguments

  • dialect_or_handle — :postgres, :sqlite, or a backend handle

Examples

iex> Rheo.Backend.Ecto.capabilities(:sqlite).guarantees.distributed
false

iex> Rheo.Backend.Ecto.capabilities(:postgres).guarantees.distributed
true

Returns

A Rheo.Backend.Capabilities struct.

child_spec(opts)

@spec child_spec(keyword()) :: Supervisor.child_spec()

Child spec for the configuration process that acts as the backend handle.

Arguments

  • opts — keyword options, see the "Options" section above

Examples

iex> spec = Rheo.Backend.Ecto.child_spec(repo: MyApp.Repo, name: :demo_sql)
iex> {spec.id, elem(spec.start, 0)}
{{Rheo.Backend.Ecto.Server, :demo_sql}, Rheo.Backend.Ecto.Server}

Returns

A supervisor child spec map.

Errors / raises

Raises ArgumentError when :repo is missing.

default_handle()

@spec default_handle() :: atom()

Default handle name for the Rheo instance.

Examples

iex> Rheo.Backend.Ecto.default_handle()
Rheo.Ecto

Returns

A process name atom.