feat(postgres): version PG extension from cloudsync.h, gate releases on a migration check

[andinux]

Summary

Make the PostgreSQL extension version derive automatically from CLOUDSYNC_VERSION, ship per-release upgrade scripts so existing deployments can ALTER EXTENSION cloudsync UPDATE instead of
dropping/recreating, and fail CI when a release breaks the semver contract.

Why

Today default_version in cloudsync.control is pinned to '1.0' across all 16 releases. Every user's pg_extension.extversion reports '1.0' regardless of which .so they have loaded, no
per-release upgrade scripts exist, and no CI check flags missing ones. A version bump that changes SQL surface can silently leave users unable to reach the new release via ALTER EXTENSION cloudsync UPDATE — forcing them into a destructive DROP EXTENSION ... CASCADE; CREATE EXTENSION ... workaround or, worse, leaving them in a split-brain state where cloudsync.so is the new
code but pg_extension.extversion is stale and the SQL bindings in pg_proc may not match the new ABI.

What changes

Single source of truth. The PG extension version is derived from CLOUDSYNC_VERSION in src/cloudsync.h (what the rest of the repo already tracks). docker/Makefile.postgresql reads it and
generates cloudsync.control and cloudsync--<version>.sql at build time from new .control.in / .sql.in templates; the generated files are gitignored.

MAJOR.MINOR extension version. EXTVERSION exposes only the first two semver components — for example, 1.0.17 installs as extension version 1.0. PATCH bumps are binary-only: replace the
.so, no ALTER EXTENSION needed, installed_version stays put. MINOR/MAJOR bumps move EXTVERSION and require a per-release upgrade script. cloudsync_version() in the .so still reports
the full semver for debugging. This matches the convention used by mature PG extensions (PostGIS, pgvector, hstore, pg_stat_statements).

Per-release upgrade scripts. New src/postgresql/migrations/ directory holds hand-written cloudsync--<from>--<to>.sql files. postgres-install, postgres-package, and all three release
Dockerfiles (Dockerfile.release, Dockerfile.supabase, Dockerfile.supabase.release) install them alongside the main script via wildcard so every release ships the full chain.

Structural CI guard. scripts/check-postgres-migration.sh + a postgres-check-migration Make target + a new postgres-migration-check workflow job (which postgres-test and
postgres-build block on) enforce the contract in two modes:

• Same EXTVERSION since the previous tag (PATCH release): render both the previous tag's install script and the current cloudsync.sql.in with their respective @EXTVERSION@ substitutions,
  diff them, and fail with a unified diff if they differ. Accidental SQL drift in a PATCH release would silently break users whose installed_version stays at the old value; this guard makes that
  impossible.
• EXTVERSION moved (MINOR/MAJOR release): require a matching cloudsync--<prev>--<new>.sql in the migrations directory.

The check runs in <1s; gates every PR.

Docs. New top-level "Versioning" section in README.md describing the project-wide semver contract (PATCH never alters API) and the PG extension's MAJOR.MINOR catalog-version exception. New
"Upgrading a later release" subsection in docs/postgresql/quickstarts/postgres.md explaining when users need to run ALTER EXTENSION cloudsync UPDATE. Versioning policy (with
patch-vs-minor-vs-major decision table) in src/postgresql/migrations/README.md. Version-hardcoded filenames swept out of docker/README.md and docs/internal/supabase-flyio.md.

No version bump. This branch contains only build/CI infrastructure — no functional extension changes — so CLOUDSYNC_VERSION stays at 1.0.16. The next real fix or feature will bump the
version naturally.

Test plan

• make postgres-check-migration passes against the current state ("patch-only release candidate; SQL surface identical")
• Drift detection: appended a fake CREATE OR REPLACE FUNCTION cloudsync_oops() to cloudsync.sql.in → check fails with unified diff and remediation options
• MINOR bump pass: temporarily set CLOUDSYNC_VERSION to 1.1.0 and added a stub cloudsync--1.0--1.1.sql → check passes
• MINOR bump fail: same header bump without the migration file → check fails with the expected file path
• End-to-end upgrade (run before the MAJOR.MINOR policy revision, when EXTVERSION still tracked the full semver): rebuilt the local debug container with a persistent volume at
  installed_version = '1.0', ran ALTER EXTENSION cloudsync UPDATE, confirmed installed_version moved to 1.0.17. Under the final MAJOR.MINOR scheme, this transition is a no-op (PATCH only);
  the upgrade path will be exercised live when the next MINOR release lands.
• New postgres-migration-check job goes green in CI on this PR
• Existing postgres-test (pg15 + pg17) and postgres-build matrix jobs stay green