Database upgrade notes¶
This page records the application and database compatibility contract for each release line. Alpha releases are not supported production artifacts. Read every entry after the version you run, through the version you plan to deploy. Any change to the Alembic head must update this ledger in the same pull request.
0.1.0¶
Status: Applies to the 0.1.0-alpha.N release series.
The alpha series establishes this compatibility contract:
| Field | Contract |
|---|---|
| Database head | 0010_authority_discovery_cursor |
| Head change | Yes; authority discovery now records progress across quota pauses and replica takeover. |
| Supported source releases | 0.1.0-alpha.58 through 0.1.0-alpha.61 at 0009_conditional_request_budget, 0.1.0-alpha.56 and 0.1.0-alpha.57 at 0008_recovery_api_budget, 0.1.0-alpha.43 at 0007_reconciliation_completion, 0.1.0-alpha.42 at 0006_webhook_trace_links, or 0.1.0-alpha.14 at 0005_reconciliation_state_index, after a controlled migration. |
| Target application compatible before migration | No; startup requires the exact head. |
| Required process state | Stop webhook ingress and every older worker before applying 0010_authority_discovery_cursor. Remove the HPA and either commit a zero-replica drain state or suspend GitOps reconciliation before scaling down; see the drain procedure. |
| In-place database downgrade | Not supported. |
| Rollback after head change | Restore the verified pre-migration backup. An older image rejects this head. |
| Backup required | Yes, before deployment and before every pre-release schema adoption. |
Revision 0001_initial_schema creates the queue, webhook-delivery,
authority-epoch, lease, audit, and compatibility tables. Revision
0002_retry_dead_jobs reactivates any pre-release evaluation_jobs or
authority_jobs row in the terminal dead state. It changes the row to
pending, resets the attempt count and error, clears the lease, and makes the
row immediately available. Before any reactivated work can publish a check,
the worker fetches current GitHub and policy evidence.
Revision 0003_shared_head_epochs adds a durable generation for each
installation, repository, and head commit. The same row records the newest
generation whose exact-head invalidation finished, plus retry and lease state.
An evaluation may publish only when its captured generation is current and
invalidated.
The revision also records the generation on each evaluation job and stores the
pull-request identity and exact generation token with each direct webhook
delivery. Carried jobs with a known head are grouped by installation,
repository, and head. Each group receives generation 1 with invalidation
pending, and its jobs receive token 1.
Carried jobs without a head receive token 0. Their first authoritative
pull-request read advances or creates a pending exact-head generation and binds
the job to it in the same transaction. A superseded or lost claim rolls back
the tentative generation. Existing delivery rows have no token and keep their
pre-migration deduplication semantics. The revision changes the application
compatibility marker from 1 to 2.
Revision 0004_responsive_work_queue records whether an evaluation and
exact-head invalidation came from a direct event or periodic recovery. Direct
work promotes recovery work in place, so a later scan cannot downgrade it.
The revision also adds a completion fingerprint for each reconciled pull
request and a shared GitHub rate-limit circuit. The compatibility marker moves
from 2 to 3.
Revision 0005_reconciliation_state_index finishes the carry-over
classification for periodic work that was already queued when revision 0004
arrived. An exact-head fence becomes recovery work only when every carried job
for that head was periodic; any direct evidence keeps it interactive. The
revision also indexes the timestamp used to prune stale reconciliation
fingerprints, so cleanup stays bounded as the history grows. It moves the
compatibility marker from 3 to 4.
Revision 0006_webhook_trace_links adds nullable producer trace fields to
retained webhook deliveries. When tracing samples a verified direct webhook,
the worker can later link its separate attempt trace to that acceptance span.
The link is diagnostic only: it does not change queue ordering, evaluation, or
Check Run publication. Existing and unsampled deliveries remain unlinked. The
compatibility marker moves from 4 to 5.
Revision 0007_reconciliation_completion adds a nullable confirmation timestamp
to each retained reconciliation completion. New workers write it together with
the completion time. The reconciler honors the usual recheck interval only
when the two timestamps match. The compatibility marker moves from 5 to 6.
Older workers could discard a stale evaluation and still record its completion. The migration leaves those records unconfirmed, so the next scan queues them even if their configured recheck interval hasn't elapsed. An older writer that inserts or updates a completion cannot supply the matching confirmation. This also prevents its records from suppressing recovery after an interrupted upgrade. The marker is cache validation, not approval evidence.
Expect one additional evaluation of each retained open PR after migration. GitHub backpressure and the recovery queue still apply; this is not a promise that all checks refresh during the first scan. Follow the independent check inventory in the upgrade procedure.
Revision 0008_recovery_api_budget adds an installation-wide REST core budget
and repository discovery cursor. It moves the compatibility marker from 6
to 7; existing queues, checks, and reconciliation completions are unchanged.
The table starts empty. Each installation's first recovery request probes its
quota, and subsequent requests use the observed headers. No configured or
assumed request allowance is loaded during migration.
An already-running process does not revalidate the Alembic head before every
claim. Stop every older ingress, worker, and reconciler before this revision
runs. Start only the target artifact after database check reports
0010_authority_discovery_cursor and validates that artifact's
required-release-contract. Readiness removes an old process from webhook
traffic after migration, but it does not cancel work that process already
claimed. For Kubernetes, a zero-replica Deployment is not proof of a drain
while an HPA or GitOps controller can recreate pods. Keep autoscaling disabled
for the migration update, wait out both worker and reconciler leases, and
verify the target pod and database contract. Apply the reviewed final
autoscaling state in a separate update before resuming GitOps; an HPA should
exist only when those values enable it.
Revision 0009_conditional_request_budget adds an accounting revision and an
unfinished-repository PR cursor to each installation budget. The cursor lets
a cold replica resume work across quota windows without repeatedly spending
the budget on the same PRs. Conditional discovery responses use the fixed
not_modified outcome and may refund one local debit only when the response's
receipt still matches the row revision. A concurrent replica debit or stricter
quota observation makes that refund ineligible. The compatibility marker moves
from 7 to 8.
The discovery cache is disposable and local to each process. Current releases
keep large pages separate from branch references and empty check listings;
see the cache limits. Every cached response is
revalidated over authenticated HTTP before reuse. A 304 still
uses a physical HTTP request and can encounter secondary limits; it is not a
local cache hit or a quota guarantee.
Revision 0010_authority_discovery_cursor records the next listing page,
the last listed PR number, and handled observations on an unfinished page.
Each fingerprint covers the PR number, head, target branch, and update timestamp.
A completed page clears those fingerprints and advances the listing position,
even when every PR on it is closed. A quota pause or another replica resumes
without replaying completed pages. Matching observations on the unfinished
page are skipped; changed or reopened entries on that page are reconsidered.
A separate numeric high-water mark is retained only for diagnostics.
At most the unfinished page of 100 PRs may repeat. New evidence for the same
scope retains one full follow-up pass with the latest reason instead of erasing
the current pass. Existing jobs start at page one with no handled observations;
their fences and retry state are retained, except where legacy branch rows
must merge into one repository job as described below.
An ordinary branch push does not reset a pending repository-wide scan. Instead,
the row stores up to 100 distinct branch rechecks for one follow-up batch.
The current batch has its own target-branch map with the same limit. Both maps
retain the latest reason for each branch. An empty current map means every base;
overflow and branch names longer than 255 characters use that fallback.
All branches in a batch share one historical PR listing. Completion resets the
same row for its follow-up batch, preserving the repository fence between passes.
Migration consolidates legacy branch rows for each repository into that job. A pre-existing repository-wide row or more than 100 branch targets produces a batch covering every base. Otherwise, the target map preserves the branches and their reasons. A single legacy row retains its retry state; merging multiple rows clears their leases, resets retry attempts, and advances the generation. Authority row counts can therefore decrease without losing discovery coverage. Compare that coverage as well as other queue counts when validating a restore. Installation jobs use the next-page checkpoint and a nullable expected repository count. Their child fences and page progress commit together. A changed count restarts enumeration without discarding existing child progress. GitHub doesn't promise snapshot isolation or repository ordering; same-count membership changes still rely on installation events and reconciliation. Repository-removal corroboration has a separate membership-page checkpoint and expected count, initialized to page one and null. It retains the complete-list and fresh repository-installation evidence requirement before retirement.
Evaluation jobs also gain a nullable target-branch scheduling hint. Direct
events wake the shared repository fence even when the hint is unknown or outside
its selected branches. Publication still uses fresh evidence and its authority
guard. Migration initializes that hint
and the expected count to null, the pending branch map empty, the rescan flag
false, and the pending rescan reason to null.
The compatibility marker moves from 8 to 9.
These records describe discovery work, not approval evidence. Workers still fetch current PR and check information for each remaining PR, and queued evaluations fetch current policy before publishing their result. An invalid or failed page cannot advance that page's checkpoint; completed earlier pages remain recorded. The authority fence stays active until the listing reaches its end. Discovery enumerates open and closed PRs in creation order. This costs more requests for repositories with a large closed history, but avoids pagination shifts caused by updates or closing a PR. REST does not provide snapshot isolation; direct events and periodic reconciliation handle later changes to completed pages.
The revision also records an interactive wake counter. Failure backoff preserves an immediate retry when a direct event arrives during the claim. An unchanged persistent failure still backs off, even while the same direct event waits.
Stop webhook ingress and every older worker before this revision runs. Take and
verify a backup first. Apply the migration with the target artifact, then run
the target database check before starting two replicas. An older artifact
rejects the new head; rollback requires restoring the verified pre-migration
backup.
No supported application release predates the planned 0.1.0. Databases
created by pre-release builds have no Alembic revision, so the current 0.1.0
source provides the one-time --adopt-pre-alembic-schema path. Adoption
succeeds only when the unversioned database matches immutable revision
0001_initial_schema exactly and the operator has verified a backup.
That comparison covers tables, columns, types, lengths, nullability, primary keys, named indexes and unique constraints, the compatibility marker, column defaults, owned sequences, identity and computed behavior, PostgreSQL timestamp time-zone mode, and index predicates and options. It also rejects unexpected tables, indexes, foreign keys, and check constraints. A partial, modified, or provenance-ambiguous schema needs a separately reviewed recovery plan.