Adds configurable keys, tables, and migrations - #13
Merged
Conversation
Plan for ADR-0002's pre-migration deliverables, worked as the sp-4an.3 epic's first task: the key-generator behaviour, the use StatifierPersistence.Ecto macro, and the versioned migrations helper, plus the epic-entry decisions (Ecto in-package behind optional ecto_sql; real Postgres as the test harness) to be recorded as ADR-0005. Four phases, each independently gate-green; critic-reviewed. Docs only, so the quality gate does not apply to this commit. Refs: sp-02x
Records the two epic-entry decisions as ADR-0005: the Ecto layer ships in this package behind optional ecto_sql (uxid required, postgrex test-only), and the test harness is real Postgres with the SQL sandbox - no skip tag when the server is absent. Amends ADR-0002: the V01 table set collapses to charts/positions/runs, and tenancy columns remain unimplemented option surface. Adds the harness itself: docker-compose.yml (postgres:17), TestRepo configured from PG* env vars, database creation and sandbox setup in test_helper.exs, a connectivity smoke test that fails loudly without a server, a Postgres service container in CI, and a "Running the tests" README note. Replaces mix.exs's recorded dependency-shape question with a pointer to ADR-0005. Refs: sp-02x
Adds StatifierPersistence.Ecto.KeyGenerator: the behaviour a key
scheme implements (ecto_type/1, migration_type/1, autogenerate/2)
plus resolve/1 mapping ADR-0002's spellings - :uxid, :uuid,
:bigserial, {module, opts} - onto implementations, refusing modules
that do not implement the behaviour.
Ships the three implementations: UXID (string/text, per-table
prefixes chart_/pos_/run_), UUIDv7 (RFC 9562 v7 generated locally,
Ecto.UUID column type, guarded so the package compiles without
ecto_sql), and Bigserial (database-assigned). Pure layer, no
database; live DDL follows with the migrations helper.
Refs: sp-02x
Adds StatifierPersistence.Ecto.Config, the single resolver for the host's compile-time options: repo (required), key (default :uxid via KeyGenerator.resolve/1), table_prefix (default statifier_), per-table overrides, and a separate Postgres-schema prefix, rejecting unknown options with a clear ArgumentError at compile time. Adds the use macro: it exposes the resolved config through __statifier_persistence__/1 and defines Chart, Position, and Run schema modules on the host - configured primary key (generated MFA or database-assigned), engine identity columns verbatim, sources from Config.table/2. The whole module sits behind the ensure_loaded guard so the package compiles without ecto_sql. Phase 4's migrations helper consumes the same Config so schemas and DDL cannot disagree. Refs: sp-02x
Adds StatifierPersistence.Ecto.Migrations in the Oban.Migration mold: up/down through two doors - for: HostModule reading the compiled Config, or the same literal options use takes - both funneled through the one Config resolver so schemas and DDL cannot disagree. V01 creates charts, positions, and runs per Config, with the engine identity columns and their unique indexes independent of the configured key, honoring the Postgres-schema prefix and per-table overrides; down drops in reverse. Proves it live against Postgres: per-key round trips through the generated schemas, information_schema assertions that identity columns and unique indexes are identical across uxid, uuid, and bigserial configs, duplicate-identity inserts refused, and clean down migrations. Closes sp-02x's acceptance criteria. Refs: sp-02x
Records the new public surface: use StatifierPersistence.Ecto, the KeyGenerator behaviour with its uxid/uuid/bigserial schemes, the versioned Migrations helper, and the dependency changes (uxid required, ecto_sql optional). Refs: sp-02x
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The Ecto adapter epic (sp-4an.3) needs the pieces ADR-0002 requires ahead of the first migration: a key-generator behaviour, the
use StatifierPersistence.Ectoconfiguration macro, and a versioned migrations helper - plus the two epic-entry decisions the charter deliberately left open (dependency shape, test harness).What
ecto_sql(uxidrequired,postgrextest-only,Code.ensure_loaded?guards), and the test harness is real Postgres - compose locally, service container in CI, no skip tag when the server is absent. ADR-0002 gains a dated amendment: the V01 table set collapses tocharts/positions/runs.TestRepofromPG*env vars, SQL sandbox, a connectivity smoke test that fails loudly, CI service container.StatifierPersistence.Ecto.KeyGenerator: behaviour plus:uxid(default, per-table prefixeschart_/pos_/run_),:uuid(RFC 9562 v7, generated locally),:bigserial(database-assigned), and{module, opts}viaresolve/1.use StatifierPersistence.Ecto: oneConfigresolver validating every option at compile time; the macro definesChart/Position/Runschemas on the host with the configured PK and the engine identity columns verbatim.StatifierPersistence.Ecto.Migrations: Oban.Migration-styleup/down,for: HostModuleor literal options, both through the sameConfigso schemas and DDL cannot disagree. Proven live: per-key round trips,information_schemaassertions that identity columns and unique indexes are identical across all three key configs, duplicate-identity inserts refused, clean down.Notes
mix qualitygreen and attested per phase (final: 103 tests, 95.6% coverage, dialyzer clean). Gate stages this project does not check at all: doctor, gettext, sobelow (not installed).mix qualityrun here now requires a reachable Postgres (docker compose up -d db) - that is ADR-0005 decision 2 working as designed, not an accident.lock_run/3as a row lock, conformance suite) is the epic's next task.docs/plans/260822-sp-02x-keys-tables-migrations.md(CI green on this branch,psql \deyeball, naming judgment).Closes sp-02x