sqlite-migrate.core — io.github.unisoma/sqlite-migrate 0.1.0-SNAPSHOT

The sqlite-migrate pipeline: snapshot -> diff -> plan -> check -> apply!.

Introspects live and declared schemas into verbatim Snapshots, diffs them under the full Diff model (fine-grained entries inside changed tables — ADR 0003, 0004), and plans in-place ops with honest Refusals for everything that needs a rebuild (ADR 0006, 0007). check runs the Plan's Gates — its data preconditions — read-only as a pre-flight; apply! checks them by default inside the Frame (ADR 0008, 0011). Every effectful edge speaks to a sqlite-migrate.protocols/SQLiteExecutor.

apply! clj

(apply! conn plan)

(apply! conn plan opts)

Execute plan on conn inside the executor-owned Frame — a dumb fold over the ops in plan order, all-or-nothing. Refuses (:drift-refused, no override) when the live schema_version fingerprint no longer matches the Plan's source Snapshot metadata; refuses (:unhandled-refused) when the Plan has unhandled entries and :allow-unhandled? is not set. By default every Gate is checked up-front once the Frame's transaction is open (TOCTOU-free — ADR 0008); a failing Gate rolls back and throws :gate-failed carrying the Check result verbatim under :check. :check-gates? false opts out (ADR 0011) — for the operator who just ran check and wants to skip a second full scan. A mid-apply SQLite failure throws :sqlite-error carrying the failing Op verbatim, its plan index (:op-index), and the specific SQL statement that failed. Returns a minimal Apply report — the Check result rides it under :check, absent when gate-checking was skipped; throws on every non-success.

by-object clj

(by-object diff)

Regroup diff's flat entries under the object each belongs to: a vector of {:path [<kind> <name>] :entries [...]} groups in the locked entry order, a changed table's table-level entry reunited with its fine-grained children, entries verbatim and in order. The one nesting view — an empty Diff yields []. See sqlite-migrate.impl.report/by-object for the full contract (ADR 0005).

check clj

(check conn plan)

Run every Gate of plan read-only against conn and return the Check result — the pre-flight over the plan's data preconditions (ADR 0008): {:pass? bool :gates [...]}, one result map per Gate in op order — the Gate itself under :gate, its op's plan index (:op-index), :pass?, the sampled :violations count, :more? when the count hit the Gate's baked limit ("limit or more"), and the violating :sample-rows (row order is SQLite's — outside the determinism contract). Refuses (:drift-refused, no override) when the live schema_version fingerprint no longer matches the Plan's source Snapshot metadata. Never mutates the database; SQLite's own enforcement remains the backstop.

check-report clj

(check-report check-result)

Render a Check result into a deterministic plain-text check report: a one-line verdict, then one block per failing Gate — code, path, op index, explanation, violation count ("limit or more" when the sample hit the Gate's baked limit), and the sample rows verbatim. Pure and single-arity; renders from a deserialized Check result alone. Presentation-only — the text is not a parse contract, the EDN Check result is the machine surface. See sqlite-migrate.impl.report/check-report for the full contract (ADR 0012).

declared-snapshot clj

(declared-snapshot conn declaration)

Realize declaration (a SQL statement string or seq of statement strings) into the pristine database behind conn and introspect it. Guards the pristine premise (throws :malformed-input if the database already contains objects) and refuses loudly — with which-statement context — any statement whose effect introspection cannot capture: DML, ATTACH, PRAGMA side effects, temp objects.

diff clj

(diff live declared)

Compare two Snapshots (live, declared) into a Diff: a flat :entries vector plus both sides' Snapshot metadata. Each entry is one self-contained Semantic difference — target-relative :kind (:added/:removed/:changed), :path, both sides' verbatim sub-values with stored CREATE sql embedded, and for :changed the :facts set — in a locked deterministic order, plain EDN all the way down. Empty :entries iff the Snapshots are Equivalent. See sqlite-migrate.impl.diff/diff for the full contract (ADR 0003, 0004).

drift-report clj

(drift-report diff)

Render diff into a deterministic plain-text drift report: one block per entry in the locked entry order — per-fact both-sides lines for a :changed entry, the object's whole verbatim CREATE sql for an :added/:removed one. Pure and single-arity; renders from a deserialized Diff alone; an empty Diff yields the empty string. Presentation-only — the text is not a parse contract, the EDN Diff is the machine surface. See sqlite-migrate.impl.report/drift-report for the full contract (ADR 0005).

drift? clj

(drift? diff)

True when diff has entries — the live schema is not Equivalent to the declared one. A Diff is empty iff its two Snapshots are Equivalent (ADR 0003's no-op property), so this is the single predicate over the Equivalence relation.

plan clj

(plan diff)

(plan diff opts)

Plan a Diff into an ordered, self-contained Plan: {:ops [...] :unhandled [...] :live-metadata ... :declared-metadata ... :capabilities ... :directives [...] :unused-directives [...]} — list position is execution order, every Diff entry either served by ≥1 op or honestly unhandled with its full Refusal vector, byte-identical for identical inputs. Opts: :capabilities (defaults: the live Snapshot's SQLite version plus :rebuild? true), :directives (the intent channel, ADR 0009 — per-object Directive maps that lift :needs-intent refusals: :rename-table, :rename-column, :drop-table, :drop-column; a conflicting set throws :malformed-input, an unmatched directive is inert and reported under :unused-directives in input order, and apply! never consults them), and :live-snapshot/:declared-snapshot (required planning context whenever the Diff contains a changed table). See sqlite-migrate.impl.plan/plan for the full contract (ADR 0006, 0007, 0009).

plan-report clj

(plan-report plan)

Render plan into a deterministic plain-text plan report — the pre-apply review artifact: a header with both sides' identity, the Ops in execution order with kind, object path, Gates (code and explanation), and full SQL always; then the unhandled entries with each Refusal's class, code, and explanation; then the unused Directives verbatim. Pure and single-arity; renders from a deserialized Plan alone. Presentation-only — the text is not a parse contract, the EDN Plan is the machine surface. See sqlite-migrate.impl.report/plan-report for the full contract (ADR 0012).

snapshot clj

(snapshot conn)

Introspect the live main schema of conn into a Snapshot: tables (with columns, indexes, and triggers nested), views (with their triggers), and opaque virtual tables — identifiers as strings, columns in storage (cid) order. Engine-internal objects (sqlite_*, shadow tables, automatic indexes) are excluded. Provenance never affects Snapshot equality: each object map carries its stored CREATE sql verbatim as Clojure metadata ({:sql ...} via clojure.core/meta), and the Snapshot map itself carries {:sqlite-version ... :schema-version ...} the same way.