Versioning & migrations

pgmem keeps two version numbers on purpose: the app version (the Python package) and the schema version (the SQL layer). They move independently, so a client upgrade doesn't force a migration and vice versa. The schema evolves through immutable, append-only migrations.

Two decoupled versions

• App version — the published SDK, tracked in version.txt.
• Schema version — the SQL layer, recorded in the pgmem.control table (currently 0.9.0).

A given app version works against a range of schema versions. Check the schema version installed on your database against what your SDK expects using the query below.

The migration contract

• Migrations under sql/migrations/ are versioned and immutable — once released, a migration file is never edited; new changes ship as new files.
• The packaged extension SQL (sql/extension/pgmem--*.sql) is generated from those migrations, not hand-edited.

See sql/migrations/README.md for the full immutable-migration / upgrade contract.

Checking and upgrading

See the schema version applied to your database:

psql "$DATABASE_URL" -c "SELECT version FROM pgmem.schema_migrations ORDER BY version;"

To upgrade, pull the new SDK, then re-run the idempotent installer against your database — it's safe to run at any version and brings the schema up to date:

psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f sql/migrations/install.sql

Because migrations are append-only, the installer only ever adds what's missing — it never rewrites or drops what's already there.

Related

• Deployment — applying the schema in production
• Installation — first-time setup
• SQL layer & schema — what the migrations define