IF Commons GitHub

Parallel versions

0020Active

0020-sql-parallel-versions · owner if · domain data

What the tables hold

FR-001checkpassing

expandSchema MUST give, from the latest version's logical schema and those of the older live versions, the logical schema the tables are made to during the overlap: the latest's, with each column and table of an older version that the latest does not have (matched by words, and for a column that governance says was renamed, by the name it had) added as an optional column or table with no default, and each column the latest has and an older version lacks made optional.

Enforced (check): .github: cd commons/data && bun run verify — suite/rollout.test.ts: the expanded schema is the latest with what older versions still use kept as optional and what only the latest has made optional, a renamed column being the same column

Proved by: data/suite/rollout.test.ts

Written in: data/sql/extensions/rollout/expand.ts, data/sql/extensions/rollout/mod.ts

Tests: passed: suite/rollout.test.ts the expanded schema is the latest with what older versions still use kept as optional and

Cited by: Data, sql/extensions/rollout/expand

FR-002checkpassing

The plan from the tables as they are to that schema MUST be an expand: it MUST contain no step that drops a column, a table or rows, and a column renamed by governance MUST be a rename in place.

Enforced (check): .github: cd commons/data && bun run verify — suite/rollout.test.ts: on PostgreSQL two versions use one database at once under their own names, the expand destroys nothing, retiring the older drops its schema, and the contract quarantines what only it used

Proved by: data/suite/rollout.test.ts

Tests: passed: suite/rollout.test.ts on PostgreSQL two versions use one database at once under their own names, the expand dest

What each version sees

FR-003checkpassing

For each live version versionViews MUST make a schema api_<label> (the pattern is a setting) and in it a view of each table of that version with that version's names for the table and its columns, over the tables of FR-001, where a column the version knows by another name than the tables use is selected under the version's name; it MUST be made as a unit that the lifecycle applies again when the tables change.

Enforced (check): .github: cd commons/data && bun run verify — suite/rollout.test.ts: on PostgreSQL two versions use one database at once under their own names, the expand destroys nothing, retiring the older drops its schema, and the contract quarantines what only it used; suite/rollout.test.ts: the schema's pattern and the primary version are settings, DuckDB's views read, and SQLite's views carry the version's label in their names

Proved by: data/suite/rollout.test.ts

Written in: data/sql/extensions/rollout/views.ts

Tests: passed: suite/rollout.test.ts on PostgreSQL two versions use one database at once under their own names, the expand dest; passed: suite/rollout.test.ts the schema's pattern and the primary version are settings, DuckDB's views read, and SQLite

Cited by: Data, sql/extensions/rollout/views

FR-004checkpassing

A version's view MUST show a column of its version and no other: not what only a newer version added, not what is kept for an older one.

Enforced (check): .github: cd commons/data && bun run verify — suite/rollout.test.ts: on PostgreSQL two versions use one database at once under their own names, the expand destroys nothing, retiring the older drops its schema, and the contract quarantines what only it used

Proved by: data/suite/rollout.test.ts

Written in: data/sql/extensions/rollout/views.ts

Tests: passed: suite/rollout.test.ts on PostgreSQL two versions use one database at once under their own names, the expand dest

FR-005checkpassing

A row written through the view of any live version MUST be read through the view of every other under that version's names, with no copy and no trigger, on PostgreSQL where its views are updatable; and an older version's insert MUST NOT be refused for a column it does not know.

Enforced (check): .github: cd commons/data && bun run verify — suite/rollout.test.ts: on PostgreSQL two versions use one database at once under their own names, the expand destroys nothing, retiring the older drops its schema, and the contract quarantines what only it used

Proved by: data/suite/rollout.test.ts

Written in: data/sql/extensions/rollout/views.ts

Tests: passed: suite/rollout.test.ts on PostgreSQL two versions use one database at once under their own names, the expand dest

Retiring a version

FR-006checkpassing

Retiring a version MUST be the statements that drop its schema, and the contract MUST be the ordinary plan from the tables to the latest schema; after both, the older version's schema MUST be gone, what only it used MUST be in quarantine and what only the latest needed MUST be required.

Enforced (check): .github: cd commons/data && bun run verify — suite/rollout.test.ts: on PostgreSQL two versions use one database at once under their own names, the expand destroys nothing, retiring the older drops its schema, and the contract quarantines what only it used

Proved by: data/suite/rollout.test.ts

Written in: data/sql/extensions/rollout/views.ts

Tests: passed: suite/rollout.test.ts on PostgreSQL two versions use one database at once under their own names, the expand dest

Cited by: Data, sql/extensions/rollout/views

Settings

FR-007checkpassing

The pattern of a version's schema, the label of the version whose views the protection layer makes (so that they are not made twice), and the roles that may use each version's views (from governance's security.access) MUST each have a default and be changeable.

Enforced (check): .github: cd commons/data && bun run verify — suite/rollout.test.ts: the schema's pattern and the primary version are settings, DuckDB's views read, and SQLite's views carry the version's label in their names

Proved by: data/suite/rollout.test.ts

Tests: passed: suite/rollout.test.ts the schema's pattern and the primary version are settings, DuckDB's views read, and SQLite

What the database holds

FR-008checkpassing

On PostgreSQL, a database at the older version, expanded, MUST serve both versions at once (FR-005), contracted MUST serve the latest alone and keep what the older used in quarantine; on DuckDB the views MUST read (they are read-only) and on SQLite the views MUST read under the version's label in their names.

Enforced (check): .github: cd commons/data && bun run verify — suite/rollout.test.ts: on PostgreSQL two versions use one database at once under their own names, the expand destroys nothing, retiring the older drops its schema, and the contract quarantines what only it used; suite/rollout.test.ts: the schema's pattern and the primary version are settings, DuckDB's views read, and SQLite's views carry the version's label in their names

Proved by: data/suite/rollout.test.ts

Tests: passed: suite/rollout.test.ts on PostgreSQL two versions use one database at once under their own names, the expand dest; passed: suite/rollout.test.ts the schema's pattern and the primary version are settings, DuckDB's views read, and SQLite

Out of scope

  • A change of a column's type, or a split or a merge of columns, which needs the old and the new column kept in step by a trigger: a later specification; the plan says it needs a step.
  • Choosing when to retire a version: the project's, from what it knows of its clients.
  • Routing a client to a version: its connection's search path or its schema name.

Edge cases

  • A table that a newer version added: not in the older version's schema, per FR-004.
  • A column an older version used that the latest dropped: kept optional until the contract, per FR-001.
  • DuckDB cannot alter a table that other tables reference, so an in-place expand of such a table is the rewrite's work; its views are created after the expand, per FR-008.
  • The older version's views must be retired before the contract, since a view holds the column the contract quarantines, per FR-006.
  • An older version that inserts without a column the latest requires: the column is optional during the overlap, per FR-001 and FR-005.
  • A version retired twice: the drop is IF EXISTS, per FR-006.
  • Only one live version: the views of that version and no retained columns, per FR-001.

Assumptions

  • Versions are given oldest first, each with the logical schema it was made from.
  • The retained columns are the older version's, as it knew them.

Open questions

OQ-1open question

Whether the overlap's tables are also described in the governance tables, with the version that still needs each retained column.

Key entities

  • Live version - a version of the application that is still in use, with its schema.
  • Expanded schema - what the tables hold while versions overlap.
  • Version schema - the views one version uses.

Success criteria

SC-001success criterion

A release of the application and a release of the database need not happen together, and nothing is lost at either.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

Data, sql/extensions/rollout/expand, sql/extensions/rollout/views

Titles, headings, exports, tables, columns and requirements. Esc closes.