# `Continuum.Partitions`
[🔗](https://github.com/Yyeger/Continuum/blob/main/lib/continuum/partitions.ex#L1)

Maintains the monthly `continuum_events` partition horizon.

`ensure/1` is cluster-safe and idempotent. It serializes maintenance with a
PostgreSQL advisory lock, creates a default partition when one is missing,
and creates the requested monthly partitions. If the default partition
already contains rows for a newly-created month, those rows are moved into
the month partition in the same transaction.

The database user running this operation needs permission to create and lock
tables. Applications that separate migration and runtime database roles can
call this API from a release task instead of enabling the optional runtime
maintainer.

# `summary`

```elixir
@type summary() :: %{
  optional(:reason) => :maintenance_locked,
  status: :ok | :skipped,
  instance: atom() | nil,
  horizon_start: String.t(),
  horizon_end: String.t(),
  required: [String.t()],
  created: [String.t()],
  existing: [String.t()],
  moved_row_count: non_neg_integer(),
  default_partition: String.t() | nil,
  default_created?: boolean(),
  default_row_count: non_neg_integer()
}
```

# `ensure`
*since 0.6.2* 

```elixir
@spec ensure(keyword()) :: {:ok, summary()} | {:error, term()}
```

Ensures a future horizon of monthly event partitions.

This operation is safe to call concurrently from multiple cluster nodes.
The default lock mode waits for the current maintainer and then rechecks the
horizon. Pass `lock: :try` for scheduled best-effort maintenance that should
return `%{status: :skipped, reason: :maintenance_locked}` instead of waiting.

See `plan/1` for the common options. `:timeout` controls the transaction
timeout and defaults to 30 seconds. `:source` is copied to telemetry metadata.

# `plan`
*since 0.6.2* 

```elixir
@spec plan(keyword()) :: {:ok, map()} | {:error, term()}
```

Returns the current partition plan without changing the database.

Options:

  * `:instance` or `:repo` selects the database.
  * `:months` is the positive future horizon, defaulting to 4 and capped at
    120.
  * `:start_month` accepts a first-of-month `Date` or `YYYY-MM` string. The
    database clock's current month is used by default.

---

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