PhoenixKitProjects.Migrations.Schema (PhoenixKitProjects v0.21.0)

Copy Markdown View Source

Module-owned versioned migrations for phoenix_kit_projects.

Implements the versioned-migration protocol core's mix phoenix_kit.update discovers via migration_module/0 (current_version/0 + migrated_version_runtime/1 + up/1). Reference implementations: PhoenixKitBookings.Migrations.Schema, PhoenixKitStats.Migrations.Schema.

Relationship to core's migration chain

The projects tables were historically created by core's chain (V101 / V112 / V125 / V127 / V128). Those sections remain in core and stay authoritative for installs migrating through them — this chain requires core ≥ V128 and takes over from that composed shape:

  • V1 is a baseline: an idempotent (IF NOT EXISTS) restatement of the exact table shape core's chain produces today. On any core-migrated install every statement no-ops; the version marker is simply stamped. migrated_version_runtime/1 treats a marker-less-but-present phoenix_kit_projects table as already at V1, so existing installs never regenerate a pointless migration.
  • V2+ (future) hold the hub-rework tables (extension enablement, members, ledger, …) and never ship through core.

Version marker

COMMENT ON TABLE <prefix>.phoenix_kit_projects IS 'pkp_schema:<N>' — same mechanism as core's marker on phoenix_kit, namespaced (pkp_schema:) so the bare-integer core convention can never be confused with ours.

Idempotency

Every statement in every version guards itself (CREATE TABLE IF NOT EXISTS, CREATE INDEX IF NOT EXISTS), so up/1 always runs the full chain start-to-finish and re-running is safe. down/1 exists for protocol completeness; on installs whose tables were created by core's chain a module-level down is NOT a supported operation (core's marker still claims the tables) — it drops data and is meant for scratch schemas only.

Summary

Functions

current_version()

Target schema version of the projects module chain.

down(opts \\ [])

Rolls back TO :version (the semantics mix phoenix_kit.update's generated host migration passes): each chain version above the target drops ITS OWN tables and the marker restamps at the target. A missing/0 target is the full teardown — scratch-schema use only.

migrated_version_runtime(opts \\ [])

Currently applied projects-chain version, read from the database.

up(opts \\ [])

Applies the projects module chain (all versions, idempotent), then stamps the marker. Accepts :prefix as keyword list or map.

Functions

current_version()

Target schema version of the projects module chain.

down(opts \\ [])

Rolls back TO :version (the semantics mix phoenix_kit.update's generated host migration passes): each chain version above the target drops ITS OWN tables and the marker restamps at the target. A missing/0 target is the full teardown — scratch-schema use only.

The version-aware shape is load-bearing (panel find R1-1): the generated host migration wires down to Schema.down(prefix: …, version: N), so a plain mix ecto.rollback after an update must undo ONLY that update — the earlier unconditional full drop destroyed every projects table on the first rollback while core's own marker still claimed them.

migrated_version_runtime(opts \\ [])

Currently applied projects-chain version, read from the database.

Returns 0 when phoenix_kit_projects does not exist, the integer from the pkp_schema:<N> table comment when present, and 1 when the table exists without our marker (a core-chain-built install that predates this module chain). opts accepts :prefix (keyword list or map).

up(opts \\ [])

Applies the projects module chain (all versions, idempotent), then stamps the marker. Accepts :prefix as keyword list or map.