# `Rheo.Backend.Ecto`
[🔗](https://github.com/thanos/rheo/blob/v1.0.0/lib/rheo/backend/ecto.ex#L3)

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`.

# `capabilities`

```elixir
@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`

```elixir
@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`

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*