# `PeriodicalEcto`
[🔗](https://github.com/joetjen/periodical_ecto/blob/main/lib/periodical_ecto.ex#L1)

A `Periodical.Coordinator` that keeps claims in a database table through Ecto.

Every instance that shares a named Periodical schedule claims each run in
one table, keyed on the schedule; the instance whose claim takes the row runs
the callback. Leases are computed and compared by the database's clock, so
the instances' own clock skew does not affect them.

Supported repositories: `Ecto.Adapters.Postgres` (PostgreSQL) and
`Ecto.Adapters.MyXQL` (MariaDB, MySQL).

## Setup

Create the table with a migration:

    defmodule MyApp.Repo.Migrations.AddPeriodicalClaims do
      use Ecto.Migration

      def up, do: PeriodicalEcto.Migration.up()
      def down, do: PeriodicalEcto.Migration.down()
    end

and configure the coordinator:

    config :periodical, Periodical.Config,
      coordinator: {PeriodicalEcto, repo: MyApp.Repo}

Options (the same for the migration where they apply):

- `:repo` (required) — the Ecto repository.
- `:table` — the table name; `"periodical_claims"` by default.
- `:prefix` — the schema (PostgreSQL) or database (MariaDB/MySQL) the table
  lives in; the repository's default when omitted.

The repository must be started before Periodical fires its first
coordinated occurrence. A database that is unreachable makes claims fail
with an error, which Periodical's `:coordinator_error` policy handles.

## How a claim decides

PostgreSQL decides in one statement: an `INSERT … ON CONFLICT (key) DO
UPDATE … WHERE expires_at <= now` takes the row when it is free or its lease
has expired, and touches nothing otherwise; one affected row means the claim
won.

MariaDB/MySQL has no conditional upsert that reports the outcome reliably,
so a claim deletes the key's row if its lease has expired and then inserts
with `INSERT IGNORE`. Of concurrent claims, only one insert can succeed on
the primary key.

## Expired rows

A row is replaced when its schedule is next claimed, so a table holds at
most one row per coordinated schedule. Rows of schedules that no longer
exist stay; `prune/1` deletes every expired row, and can itself be a
Periodical schedule.

# `claim`

```elixir
@spec claim(Periodical.Coordinator.Claim.t(), keyword()) ::
  :won | :lost | {:error, term()}
```

Claims the schedule's row for `claim.ttl_ms`.

Returns `:won` when this claim took the row, `:lost` when another claim's
lease is still running, and `{:error, reason}` when the database failed.

# `prune`

```elixir
@spec prune(keyword()) :: {:ok, non_neg_integer()} | {:error, term()}
```

Deletes every row whose lease has expired, returning how many.

Takes the same options as the coordinator:

    PeriodicalEcto.prune(repo: MyApp.Repo)
    #=> {:ok, 3}

# `renew`

```elixir
@spec renew(Periodical.Coordinator.Claim.t(), keyword()) ::
  :ok | :lost | {:error, term()}
```

Extends the lease to `claim.ttl_ms` from now while the row still holds this claim's token.

Returns `:lost` when the lease expired or the row belongs to another claim.

---

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