Add query-contraction check against the previous release

[iplay88keys]

Description

Adds a static check that a migration on this branch doesn't break the queries a prior release still runs — the backward-compatibility property that makes a one-step rollback (and a rolling deploy) safe.

It compiles a prior release's sqlc queries against the current schema (derived from the migration files) and fails if a migration dropped, renamed, or retyped a column or table an older query still references. Runs in normal CI on every PR — no database, no cluster.

Targets

Checks two prior versions (deduplicated when they coincide):

• the latest release reachable from HEAD — the adjacent previous release, and
• the previous stable line's latest patch (the release/vX.Y.x tip) — the rollback-window floor.

Running

make -C go check-query-contraction

Override the targets with TARGET_VERSIONS (space-separated, no leading v).

Notes

• Verified it passes today and fails on a simulated column drop.
• Catches column/table/type-shape contractions; it does not catch data rewrites (no DDL to inspect) or semantic changes a query still compiles against.
• Complements the contraction-declaration check in Add checks for schema-agnostic sql and declaring db contractions #2067: that one requires destructive DDL to be acknowledged; this one verifies a prior release's queries actually survive the new schema.
• Also documents the existing sqlc generate gate (schema derived from migrations) as the forward-direction equivalent for current-release queries.
• This branch carries its own copies of the helper scripts, which are shared with Add database upgrade and rollback compatibility tests #2084, so that will require a trivial merge conflict resolution.

[Copilot]

Pull request overview

Adds a static, offline CI gate that verifies backward compatibility of database schema migrations by compiling a previous release’s sqlc queries against the current schema derived from migrations. This supports safer rollbacks and rolling deploys by catching schema contractions (drops/renames/type changes) that would break older binaries.

Changes:

• Add scripts/check-query-contraction.sh to compile prior-release sqlc queries against the current migration-derived schema.
• Add scripts/prev-stable-version.sh to resolve the rollback-floor target (latest patch on the previous stable release line).
• Wire the check into CI and go/Makefile, and document the relationship with the existing sqlc generate schema gate.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
scripts/prev-stable-version.sh	Determines the latest patch tag on the stable line below the currently-built line.
scripts/check-query-contraction.sh	Stages current migrations + previous-release queries and runs sqlc compile as a compatibility gate.
go/Makefile	Adds a check-query-contraction target for local/CI invocation.
go/core/internal/database/sqlc.yaml	Documents how schema-from-migrations makes sqlc generate a forward-compatibility safety gate and points to the new backward check.
.github/workflows/ci.yaml	Adds a dedicated Query Contraction Check job and switches Go setup to go-version-file in multiple jobs.
.claude/skills/kagent-dev/references/database-migrations.md	Updates the migrations guide to describe/enumerate the new query-level compatibility check.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[EItanya]

Just the one nit about script placement since it's only used there

[EItanya]

nit: should we just put this script in go/scripts?

[EItanya]

good idea

[EItanya]

Can this be used by both this PR and the upgrade tests?