PhoenixKitInbox.Migrations (PhoenixKitInbox v0.2.0)

Copy Markdown View Source

Versioned migration coordinator for phoenix_kit_inbox — the module returned from PhoenixKitInbox.migration_module/0.

This module owns its DDL. Historically PhoenixKit modules shipped their tables inside core's versioned chain (the V90+ scheme); that put every module's schema in one repo and made a module release depend on a core release. Inbox follows the newer, self-contained pattern already used by phoenix_kit_boards, phoenix_kit_web_analytics, phoenix_kit_legal, and phoenix_kit_stats: the tables live here, versioned here, released here.

mix phoenix_kit.update discovers this module, compares migrated_version_runtime/1 (what's installed) against current_version/0 (what the code needs), and when behind generates a host migration whose up/0 calls up/1 here. Hosts never hand-write a migration, and named-schema (--prefix) installs are honored.

Version tracking

Version lives in a COMMENT ON TABLE on phoenix_kit_inbox_mailboxes, mirroring core's own PhoenixKit.Migrations.Postgres. It is deliberately not a bare "does the table exist?" check — that can't tell "not installed" from "installed at V1", which is exactly what a future V2 needs to know.

Versions:

  • 0 — not installed
  • 1 — mailboxes, mailbox grants, messages, deliveries

Adding a version

  1. Add lib/phoenix_kit_inbox/migrations/v02.ex with up/1 and down/1.
  2. Bump @current_version here and add the 2 -> ... clause to apply_step/2.
  3. Never edit a shipped version module — hosts already past it will not re-run it.

Summary

Functions

current_version()

The version this code expects the schema to be at.

down(opts \\ [])

Roll back to the target version (default: 0, i.e. everything). Migration-context only.

migrated_version(opts \\ [])

The version currently installed in the database (0 if absent). Migration-context only — reads via Ecto.Migration.repo/0.

migrated_version_runtime(opts \\ [])

Runtime-safe version of migrated_version/1 — uses PhoenixKit's configured repo instead of the Ecto.Migration repo() helper, so it can be called from Mix tasks and other non-migration contexts (mix phoenix_kit.update).

up(opts \\ [])

Run migrations up to (and including) the target version. Migration-context only.

Functions

current_version()

@spec current_version() :: pos_integer()

The version this code expects the schema to be at.

down(opts \\ [])

@spec down(keyword()) :: :ok

Roll back to the target version (default: 0, i.e. everything). Migration-context only.

migrated_version(opts \\ [])

@spec migrated_version(keyword()) :: non_neg_integer()

The version currently installed in the database (0 if absent). Migration-context only — reads via Ecto.Migration.repo/0.

migrated_version_runtime(opts \\ [])

@spec migrated_version_runtime(keyword()) :: non_neg_integer()

Runtime-safe version of migrated_version/1 — uses PhoenixKit's configured repo instead of the Ecto.Migration repo() helper, so it can be called from Mix tasks and other non-migration contexts (mix phoenix_kit.update).

Returns 0 on any failure. catch :exit matters as much as rescue here: a dead or unstarted connection pool exits rather than raising, and this function is called by mix phoenix_kit.status / mix phoenix_kit.update across every installed module — an uncaught exit from one coordinator takes the whole report down with it.

up(opts \\ [])

@spec up(keyword()) :: :ok

Run migrations up to (and including) the target version. Migration-context only.