docs: the chain guide, migrating from alembic, and a README that shows the whole tool - #7
Merged
Conversation
New docs/the-chain.md: the two-workflow model (push vs chain), the
three verbs (revision/migrate/stamp), the file format with a real
generated example, migrate's gates, CONCURRENTLY replay semantics,
the backfill workflow, the hand-authored 0000_extensions.sql pattern,
the public.sqlpush_versions registry, and an honest-limitations
section.
The 0000_extensions pattern was verified live against a scratch DB on
the dev server (localhost:5433, timescaledb-ha:pg17), never against
sqlpush_test:
- migrate on an empty scratch DB applied a hand-authored
0000_extensions.sql (header `-- sqlpush: revision=0000 risk=SAFE`,
one labeled op, CREATE EXTENSION IF NOT EXISTS postgis +
timescaledb): applied: 1, exit 0; both extensions present in
pg_extension afterwards; registry row ('0000_extensions.sql',
sha256) recorded. This also proves parse accepts the hand-authored
header/op-label form.
- Idempotency: with the registry row deleted, migrate re-EXECUTED the
file cleanly (IF NOT EXISTS); with the row present, it skipped.
- stamp on a second fresh scratch DB: applied: 0, skipped
(registered): 1, registry row present, postgis NOT installed ->
nothing was executed. (timescaledb appears on every new DB on this
image via template1 preload; postgis does not, so it is the clean
indicator.)
- Numbering after 0000: next_revision_id on a dir containing only
0000 returns 0001; a real `sqlpush revision` run against the
scratch DB (at chain head) generated 0001_create_users.sql with
header revision=0001.
- End to end: migrate applied 0001 (0000 skipped), then `sqlpush
check` against the same DB exited 0.
The refugee recipe, honest about what does not exist: no automated conversion of alembic revisions, the old chain stays untouched (alembic_version is pruned from every diff forever). Four phases: observe parity first (check + --exclude for legacy objects), baseline the empty chain (0000_extensions link), run both then switch, and a scratch-DB equivalence replay. Command map included; downgrade is none, forward-only, stated plainly.
…-DB story Surface the whole tool: a "When you want files: the chain" section after the push-style pitch (three chain verbs + link to the guide), the comparison row now honest (files optional), and guides links for the chain, alembic and migra. Exit codes table covers all six verbs; a compact per-verb flags table folds in the lock/timeout/concurrency knobs. New "An inherited database" section explains first-check drift and the --exclude / --allow-destructive escape hatches. Scoping paragraph under How it works (extension schemas, public registry, alembic_version pruning). asyncpg translation note in the lifespan section. Roadmap heading de-versioned; pitch softened to "no migration files required".
Replace the internal spec reference in the released 0.5.0 Known limitations section with wording that stands alone (the trade-off is named, not cited). Add the [Unreleased] entry for the two guides and the README's six-verb documentation surface.
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.
Summary
The documentation release: the front page now represents the whole tool, and the two workflows have complete guides. Docs-only — zero src/tests changes (
git diff main..HEAD --stattouches README.md, CHANGELOG.md, docs/ only).New:
docs/the-chain.mdThe chain guide — the three verbs (
revision/migrate/stamp), the file format with a real generated example, migrate's gates (destructive header gate, checksum gate with thestamp --forceescape, strict order, shared bounded advisory lock, per-file budgets), CONCURRENTLY replay semantics (whole-text fast path dollar-quote safe; label-delimited plain-first hybrid for CONCURRENTLY files), the data-backfill workflow (append a-- op N [raw_sql]UPDATE before first apply: schema change and data change ship as one reviewable file), the hand-authored0000_extensions.sqlpattern (fresh environments get PostGIS/TimescaleDB before any generated file; existing ones adopt withstamp;IF NOT EXISTSkeeps re-runs safe) — the pattern was derived and verified live against scratch databases (migrate applies, stamp never executes, next revision numbers 0001, end-to-end revision→migrate→check clean), the registry, and an honest-limitations list.New:
docs/migrating-from-alembic.mdThe refugee recipe, no automated conversion stated up front: command map (autogenerate→revision, upgrade→migrate, stamp→stamp, downgrade→none, forward-only), then four phases — observe parity (
alembic_versionpruned from every diff, exit 0/2/3,--excludeacceptance for legacy objects), baseline the empty chain (+0000_extensions), run both then switch (coexistence forever, the old chain becomes an archive), and a scratch-DB equivalence proof (baseline dump →migratehead-to-toe →checkexit 0).README rewrite
All six verbs on the front page: a "When you want files: the chain" section after the push-style pitch, the full exit-codes table (per cli.py), a per-verb flags reference, the inherited-database story (first
checkdrift, exit 3,--exclude/--allow-destructiveescape hatches), schema-scoping facts (search_path default, extension-owned schemas, registry always inpublic, pruned), the asyncpg translation note, an honest comparison row ("migration files: optional"), and the stale roadmap lines removed.CHANGELOG
New
[Unreleased]Added bullet for the docs; the 0.5.0 limitation wording made self-contained — "(pinned chain spec §7)" replaced with plain wording (no references to untracked specs anywhere in public surface).Verification
166 passed, 1 xfailedunchanged (docs-only confirmed);ruff/tycleanRelease plan
On merge, cut
v0.5.1(docs-only patch) so the PyPI description picks up the new README.