@rocicorp/zero 0.2.2024101101 → 0.3.2024102500

package/out/zero-cache/src/db/migration-lite.js

@@ -6,47 +6,45 @@ import { Database } from '../../../zqlite/src/db.js';
  * Ensures that the schema is compatible with the current code, updating and
  * migrating the schema if necessary.
  */
-export async function runSchemaMigrations(log, debugName, dbPath, versionMigrationMap) {
+export async function runSchemaMigrations(log, debugName, dbPath, setupMigration, incrementalMigrationMap) {
     log = log.withContext('initSchema', randInt(0, Number.MAX_SAFE_INTEGER).toString(36));
     const db = new Database(log, dbPath);
     db.pragma('foreign_keys = OFF');
     try {
-        const versionMigrations = sorted(versionMigrationMap);
-        if (versionMigrations.length === 0) {
-            log.info?.(`No versions/migrations to manage.`);
-            return;
-        }
-        const codeSchemaVersion = versionMigrations[versionMigrations.length - 1][0];
-        log.info?.(`Checking schema for compatibility with ${debugName} at schema v${codeSchemaVersion}`);
-        let meta = await runTransaction(log, db, tx => {
-            const meta = getSchemaVersions(tx);
-            if (codeSchemaVersion < meta.minSafeRollbackVersion) {
-                throw new Error(`Cannot run ${debugName} at schema v${codeSchemaVersion} because rollback limit is v${meta.minSafeRollbackVersion}`);
+        const versionMigrations = sorted(incrementalMigrationMap);
+        assert(versionMigrations.length, `Must specify a at least one version migration`);
+        assert(versionMigrations[0][0] > 0, `Versions must be non-zero positive numbers`);
+        const codeVersion = versionMigrations[versionMigrations.length - 1][0];
+        log.info?.(`Checking schema for compatibility with ${debugName} at schema v${codeVersion}`);
+        let versions = await runTransaction(log, db, tx => {
+            const versions = getVersionHistory(tx);
+            if (codeVersion < versions.minSafeVersion) {
+                throw new Error(`Cannot run ${debugName} at schema v${codeVersion} because rollback limit is v${versions.minSafeVersion}`);
             }
-            if (meta.version > codeSchemaVersion) {
-                log.info?.(`Schema is at v${meta.version}. Resetting to v${codeSchemaVersion}`);
-                return setSchemaVersion(tx, meta, codeSchemaVersion);
+            if (versions.dataVersion > codeVersion) {
+                log.info?.(`Data is at v${versions.dataVersion}. Resetting to v${codeVersion}`);
+                return updateVersionHistory(log, tx, versions, codeVersion);
             }
-            return meta;
+            return versions;
         });
-        if (meta.version < codeSchemaVersion) {
-            for (const [dest, migration] of versionMigrations) {
-                if (meta.version < dest) {
-                    log.info?.(`Migrating schema from v${meta.version} to v${dest}`);
+        if (versions.dataVersion < codeVersion) {
+            const migrations = versions.dataVersion === 0
+                ? // For the empty database v0, only run the setup migration.
+                    [[codeVersion, setupMigration]]
+                : versionMigrations;
+            for (const [dest, migration] of migrations) {
+                if (versions.dataVersion < dest) {
+                    log.info?.(`Migrating schema from v${versions.dataVersion} to v${dest}`);
                     void log.flush(); // Flush logs before each migration to help debug crash-y migrations.
                     db.pragma('synchronous = OFF'); // For schema migrations we'll wait for the disk flush after the migration.
-                    // Run the optional PreMigration step before starting the transaction.
-                    if ('pre' in migration) {
-                        await migration.pre(log, db);
-                    }
-                    meta = await runTransaction(log, db, async (tx) => {
+                    versions = await runTransaction(log, db, async (tx) => {
                         // Fetch meta from within the transaction to make the migration atomic.
-                        let meta = getSchemaVersions(tx);
-                        if (meta.version < dest) {
-                            meta = await migrateSchemaVersion(log, tx, meta, dest, migration);
-                            assert(meta.version === dest);
+                        let versions = getVersionHistory(tx);
+                        if (versions.dataVersion < dest) {
+                            versions = await runMigration(log, tx, versions, dest, migration);
+                            assert(versions.dataVersion === dest);
                         }
-                        return meta;
+                        return versions;
                     });
                     db.pragma('synchronous = NORMAL');
                     db.exec('VACUUM');
@@ -56,8 +54,8 @@ export async function runSchemaMigrations(log, debugName, dbPath, versionMigrati
                 }
             }
         }
-        assert(meta.version === codeSchemaVersion);
-        log.info?.(`Running ${debugName} at schema v${codeSchemaVersion}`);
+        assert(versions.dataVersion === codeVersion);
+        log.info?.(`Running ${debugName} at schema v${codeVersion}`);
     }
     catch (e) {
         log.error?.('Error in ensureSchemaMigrated', e);
@@ -68,80 +66,102 @@ export async function runSchemaMigrations(log, debugName, dbPath, versionMigrati
         void log.flush(); // Flush the logs but do not block server progress on it.
     }
 }
-function sorted(versionMigrationMap) {
+function sorted(incrementalMigrationMap) {
     const versionMigrations = [];
-    for (const [v, m] of Object.entries(versionMigrationMap)) {
+    for (const [v, m] of Object.entries(incrementalMigrationMap)) {
         versionMigrations.push([Number(v), m]);
     }
     return versionMigrations.sort(([a], [b]) => a - b);
 }
 // Exposed for tests.
-export const schemaVersions = v.object({
-    version: v.number(),
-    maxVersion: v.number(),
-    minSafeRollbackVersion: v.number(),
+export const versionHistory = v.object({
+    /**
+     * The `schemaVersion` is highest code version that has ever been run
+     * on the database, and is used to delineate the structure of the tables
+     * in the database. A schemaVersion only moves forward; rolling back to
+     * an earlier (safe) code version does not revert schema changes that
+     * have already been applied.
+     */
+    schemaVersion: v.number(),
+    /**
+     * The data version is the code version of the latest server that ran.
+     * Note that this may be less than the schemaVersion in the case that
+     * a server is rolled back to an earlier version after a schema change.
+     * In such a case, data (but not schema), may need to be re-migrated
+     * when rolling forward again.
+     */
+    dataVersion: v.number(),
+    /**
+     * The minimum code version that is safe to run. This is used when
+     * a schema migration is not backwards compatible with an older version
+     * of the code.
+     */
+    minSafeVersion: v.number(),
 });
 // Exposed for tests
-export function getSchemaVersions(db) {
+export function getVersionHistory(db) {
     // Note: The `lock` column transparently ensures that at most one row exists.
     db.prepare(`
-    CREATE TABLE IF NOT EXISTS "_zero.SchemaVersions" (
-      version INTEGER NOT NULL,
-      maxVersion INTEGER NOT NULL,
-      minSafeRollbackVersion INTEGER NOT NULL,
+    CREATE TABLE IF NOT EXISTS "_zero.versionHistory" (
+      dataVersion INTEGER NOT NULL,
+      schemaVersion INTEGER NOT NULL,
+      minSafeVersion INTEGER NOT NULL,
 
       lock INTEGER PRIMARY KEY DEFAULT 1 CHECK (lock=1)
     );
   `).run();
     const result = db
-        .prepare('SELECT version, maxVersion, minSafeRollbackVersion FROM "_zero.SchemaVersions"')
+        .prepare('SELECT dataVersion, schemaVersion, minSafeVersion FROM "_zero.versionHistory"')
         .get();
-    return result ?? { version: 0, maxVersion: 0, minSafeRollbackVersion: 0 };
+    return result ?? { dataVersion: 0, schemaVersion: 0, minSafeVersion: 0 };
 }
-function setSchemaVersion(db, prev, newVersion) {
+function updateVersionHistory(log, db, prev, newVersion, minSafeVersion) {
     assert(newVersion > 0);
     const meta = {
         ...prev,
-        version: newVersion,
-        maxVersion: Math.max(newVersion, prev.maxVersion),
+        dataVersion: newVersion,
+        // The schemaVersion never moves backwards.
+        schemaVersion: Math.max(newVersion, prev.schemaVersion),
+        minSafeVersion: getMinSafeVersion(log, prev, minSafeVersion),
     };
     db.prepare(`
-    INSERT INTO "_zero.SchemaVersions" (version, maxVersion, minSafeRollbackVersion, lock)
-    VALUES (@version, @maxVersion, @minSafeRollbackVersion, 1)
+    INSERT INTO "_zero.versionHistory" (dataVersion, schemaVersion, minSafeVersion, lock)
+    VALUES (@dataVersion, @schemaVersion, @minSafeVersion, 1)
     ON CONFLICT (lock) DO UPDATE
-    SET version=EXCLUDED.version, 
-        maxVersion=EXCLUDED.maxVersion,
-        minSafeRollbackVersion=EXCLUDED.minSafeRollbackVersion
+    SET dataVersion=@dataVersion,
+        schemaVersion=@schemaVersion,
+        minSafeVersion=@minSafeVersion
   `).run(meta);
     return meta;
 }
-async function migrateSchemaVersion(log, tx, meta, destinationVersion, migration) {
-    if ('run' in migration) {
-        await migration.run(log, tx);
+async function runMigration(log, tx, versions, destinationVersion, migration) {
+    if (versions.schemaVersion < destinationVersion) {
+        await migration.migrateSchema?.(log, tx);
     }
-    else {
-        meta = ensureRollbackLimit(migration.minSafeRollbackVersion, log, meta);
+    if (versions.dataVersion < destinationVersion) {
+        await migration.migrateData?.(log, tx);
     }
-    return setSchemaVersion(tx, meta, destinationVersion);
+    return updateVersionHistory(log, tx, versions, destinationVersion, migration.minSafeVersion);
 }
 /**
  * Bumps the rollback limit [[toAtLeast]] the specified version.
  * Leaves the rollback limit unchanged if it is equal or greater.
  */
-function ensureRollbackLimit(toAtLeast, log, meta) {
+function getMinSafeVersion(log, current, proposedSafeVersion) {
+    if (proposedSafeVersion === undefined) {
+        return current.minSafeVersion;
+    }
     // Sanity check to maintain the invariant that running code is never
     // earlier than the rollback limit.
-    assert(toAtLeast <= meta.version + 1);
-    if (meta.minSafeRollbackVersion >= toAtLeast) {
+    assert(proposedSafeVersion <= current.dataVersion + 1);
+    if (current.minSafeVersion >= proposedSafeVersion) {
         // The rollback limit must never move backwards.
-        log.debug?.(`rollback limit is already at ${meta.minSafeRollbackVersion}, don't need to bump to ${toAtLeast}`);
-        return meta;
+        log.debug?.(`rollback limit is already at ${current.minSafeVersion}, ` +
+            `don't need to bump to ${proposedSafeVersion}`);
+        return current.minSafeVersion;
     }
-    log.info?.(`bumping rollback limit from ${meta.minSafeRollbackVersion} to ${toAtLeast}`);
-    return {
-        ...meta,
-        minSafeRollbackVersion: toAtLeast,
-    };
+    log.info?.(`bumping rollback limit from ${current.minSafeVersion} to ${proposedSafeVersion}`);
+    return proposedSafeVersion;
 }
 // Note: We use a custom transaction wrapper (instead of db.begin(...)) in order
 // to support async operations within the transaction.

package/out/zero-cache/src/db/migration-lite.js.map

@@ -1 +1 @@
-{"version":3,"file":"migration-lite.js","sourceRoot":"","sources":["../../../../../zero-cache/src/db/migration-lite.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,MAAM,EAAC,MAAM,gCAAgC,CAAC;AACtD,OAAO,EAAC,OAAO,EAAC,MAAM,6BAA6B,CAAC;AACpD,OAAO,KAAK,CAAC,MAAM,+BAA+B,CAAC;AAEnD,OAAO,EAAC,QAAQ,EAAC,MAAM,2BAA2B,CAAC;AAyBnD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,GAAe,EACf,SAAiB,EACjB,MAAc,EACd,mBAAwC;IAExC,GAAG,GAAG,GAAG,CAAC,WAAW,CACnB,YAAY,EACZ,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,gBAAgB,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CACjD,CAAC;IACF,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACrC,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;IAEhC,IAAI,CAAC;QACH,MAAM,iBAAiB,GAAG,MAAM,CAAC,mBAAmB,CAAC,CAAC;QACtD,IAAI,iBAAiB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACnC,GAAG,CAAC,IAAI,EAAE,CAAC,mCAAmC,CAAC,CAAC;YAChD,OAAO;QACT,CAAC;QACD,MAAM,iBAAiB,GACrB,iBAAiB,CAAC,iBAAiB,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACrD,GAAG,CAAC,IAAI,EAAE,CACR,0CAA0C,SAAS,eAAe,iBAAiB,EAAE,CACtF,CAAC;QAEF,IAAI,IAAI,GAAG,MAAM,cAAc,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE;YAC5C,MAAM,IAAI,GAAG,iBAAiB,CAAC,EAAE,CAAC,CAAC;YACnC,IAAI,iBAAiB,GAAG,IAAI,CAAC,sBAAsB,EAAE,CAAC;gBACpD,MAAM,IAAI,KAAK,CACb,cAAc,SAAS,eAAe,iBAAiB,+BAA+B,IAAI,CAAC,sBAAsB,EAAE,CACpH,CAAC;YACJ,CAAC;YAED,IAAI,IAAI,CAAC,OAAO,GAAG,iBAAiB,EAAE,CAAC;gBACrC,GAAG,CAAC,IAAI,EAAE,CACR,iBAAiB,IAAI,CAAC,OAAO,mBAAmB,iBAAiB,EAAE,CACpE,CAAC;gBACF,OAAO,gBAAgB,CAAC,EAAE,EAAE,IAAI,EAAE,iBAAiB,CAAC,CAAC;YACvD,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC,CAAC,CAAC;QAEH,IAAI,IAAI,CAAC,OAAO,GAAG,iBAAiB,EAAE,CAAC;YACrC,KAAK,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,iBAAiB,EAAE,CAAC;gBAClD,IAAI,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,CAAC;oBACxB,GAAG,CAAC,IAAI,EAAE,CAAC,0BAA0B,IAAI,CAAC,OAAO,QAAQ,IAAI,EAAE,CAAC,CAAC;oBACjE,KAAK,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,qEAAqE;oBAEvF,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC,CAAC,2EAA2E;oBAE3G,sEAAsE;oBACtE,IAAI,KAAK,IAAI,SAAS,EAAE,CAAC;wBACvB,MAAM,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;oBAC/B,CAAC;oBAED,IAAI,GAAG,MAAM,cAAc,CAAC,GAAG,EAAE,EAAE,EAAE,KAAK,EAAC,EAAE,EAAC,EAAE;wBAC9C,uEAAuE;wBACvE,IAAI,IAAI,GAAG,iBAAiB,CAAC,EAAE,CAAC,CAAC;wBACjC,IAAI,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,CAAC;4BACxB,IAAI,GAAG,MAAM,oBAAoB,CAAC,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;4BAClE,MAAM,CAAC,IAAI,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC;wBAChC,CAAC;wBACD,OAAO,IAAI,CAAC;oBACd,CAAC,CAAC,CAAC;oBAEH,EAAE,CAAC,MAAM,CAAC,sBAAsB,CAAC,CAAC;oBAClC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;oBAClB,GAAG,CAAC,IAAI,EAAE,CAAC,kBAAkB,CAAC,CAAC;oBAC/B,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;oBACxB,GAAG,CAAC,IAAI,EAAE,CAAC,mBAAmB,CAAC,CAAC;gBAClC,CAAC;YACH,CAAC;QACH,CAAC;QAED,MAAM,CAAC,IAAI,CAAC,OAAO,KAAK,iBAAiB,CAAC,CAAC;QAC3C,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,SAAS,eAAe,iBAAiB,EAAE,CAAC,CAAC;IACrE,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,GAAG,CAAC,KAAK,EAAE,CAAC,+BAA+B,EAAE,CAAC,CAAC,CAAC;QAChD,MAAM,CAAC,CAAC;IACV,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,KAAK,EAAE,CAAC;QACX,KAAK,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,yDAAyD;IAC7E,CAAC;AACH,CAAC;AAED,SAAS,MAAM,CACb,mBAAwC;IAExC,MAAM,iBAAiB,GAA0B,EAAE,CAAC;IACpD,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,mBAAmB,CAAC,EAAE,CAAC;QACzD,iBAAiB,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AACrD,CAAC;AAED,qBAAqB;AACrB,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,sBAAsB,EAAE,CAAC,CAAC,MAAM,EAAE;CACnC,CAAC,CAAC;AAKH,oBAAoB;AACpB,MAAM,UAAU,iBAAiB,CAAC,EAAM;IACtC,6EAA6E;IAC7E,EAAE,CAAC,OAAO,CACR;;;;;;;;GAQD,CACA,CAAC,GAAG,EAAE,CAAC;IACR,MAAM,MAAM,GAAG,EAAE;SACd,OAAO,CACN,gFAAgF,CACjF;SACA,GAAG,EAAoB,CAAC;IAC3B,OAAO,MAAM,IAAI,EAAC,OAAO,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,sBAAsB,EAAE,CAAC,EAAC,CAAC;AAC1E,CAAC;AAED,SAAS,gBAAgB,CACvB,EAAM,EACN,IAAoB,EACpB,UAAkB;IAElB,MAAM,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC;IACvB,MAAM,IAAI,GAAG;QACX,GAAG,IAAI;QACP,OAAO,EAAE,UAAU;QACnB,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,UAAU,CAAC;KAClD,CAAC;IAEF,EAAE,CAAC,OAAO,CACR;;;;;;;GAOD,CACA,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAEZ,OAAO,IAAI,CAAC;AACd,CAAC;AAED,KAAK,UAAU,oBAAoB,CACjC,GAAe,EACf,EAAM,EACN,IAAoB,EACpB,kBAA0B,EAC1B,SAAoB;IAEpB,IAAI,KAAK,IAAI,SAAS,EAAE,CAAC;QACvB,MAAM,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IAC/B,CAAC;SAAM,CAAC;QACN,IAAI,GAAG,mBAAmB,CAAC,SAAS,CAAC,sBAAsB,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,gBAAgB,CAAC,EAAE,EAAE,IAAI,EAAE,kBAAkB,CAAC,CAAC;AACxD,CAAC;AAED;;;GAGG;AACH,SAAS,mBAAmB,CAC1B,SAAiB,EACjB,GAAe,EACf,IAAoB;IAEpB,oEAAoE;IACpE,mCAAmC;IACnC,MAAM,CAAC,SAAS,IAAI,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;IAEtC,IAAI,IAAI,CAAC,sBAAsB,IAAI,SAAS,EAAE,CAAC;QAC7C,gDAAgD;QAChD,GAAG,CAAC,KAAK,EAAE,CACT,gCAAgC,IAAI,CAAC,sBAAsB,2BAA2B,SAAS,EAAE,CAClG,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,GAAG,CAAC,IAAI,EAAE,CACR,+BAA+B,IAAI,CAAC,sBAAsB,OAAO,SAAS,EAAE,CAC7E,CAAC;IACF,OAAO;QACL,GAAG,IAAI;QACP,sBAAsB,EAAE,SAAS;KAClC,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,sDAAsD;AACtD,KAAK,UAAU,cAAc,CAC3B,GAAe,EACf,EAAM,EACN,EAA8B;IAE9B,EAAE,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,GAAG,EAAE,CAAC;IACpC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;QAC5B,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG,EAAE,CAAC;QAC3B,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,GAAG,EAAE,CAAC;QAC7B,GAAG,CAAC,KAAK,EAAE,CAAC,kCAAkC,EAAE,CAAC,CAAC,CAAC;QACnD,MAAM,CAAC,CAAC;IACV,CAAC;AACH,CAAC"}
+{"version":3,"file":"migration-lite.js","sourceRoot":"","sources":["../../../../../zero-cache/src/db/migration-lite.ts"],"names":[],"mappings":"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"}

package/out/zero-cache/src/db/migration.d.ts

@@ -1,38 +1,79 @@
 import type { LogContext } from '@rocicorp/logger';
 import type postgres from 'postgres';
 import * as v from '../../../shared/src/valita.js';
+import type { PostgresDB, PostgresTransaction } from '../types/pg.js';
+type Operations = (log: LogContext, tx: PostgresTransaction) => Promise<void>;
 /**
- * A PreMigrationFn executes logic outside of a database transaction, and is
- * suitable for potentially long running polling operations.
- */
-type PreMigrationFn = (log: LogContext, db: postgres.Sql) => Promise<void>;
-type MigrationFn = (log: LogContext, tx: postgres.TransactionSql) => Promise<void>;
-/**
- * Encapsulates the logic for upgrading to a new schema. After the
+ * Encapsulates the logic for setting up or upgrading to a new schema. After the
  * Migration code successfully completes, {@link runSchemaMigrations}
  * will update the schema version and commit the transaction.
  */
 export type Migration = {
-    pre?: PreMigrationFn;
-    run: MigrationFn;
-} | {
-    minSafeRollbackVersion: number;
+    /**
+     * Perform database operations that create or alter table structure. This is
+     * called at most once during lifetime of the application. If a `migrateData()`
+     * operation is defined, that will be performed after `migrateSchema()` succeeds.
+     */
+    migrateSchema?: Operations;
+    /**
+     * Perform database operations to migrate data to the new schema. This is
+     * called after `migrateSchema()` (if defined), and may be called again
+     * to re-migrate data after the server was rolled back to an earlier version,
+     * and rolled forward again.
+     *
+     * Consequently, the logic in `migrateData()` must be idempotent.
+     */
+    migrateData?: Operations;
+    /**
+     * Sets the `minSafeVersion` to the specified value, prohibiting running
+     * any earlier code versions.
+     */
+    minSafeVersion?: number;
 };
-/** Mapping from schema version to their respective migrations. */
-export type VersionMigrationMap = {
+/**
+ * Mapping of incremental migrations to move from the previous old code
+ * version to next one. Versions must be non-zero.
+ *
+ * The schema resulting from performing incremental migrations should be
+ * equivalent to that of the `setupMigration` on a blank database.
+ *
+ * The highest destinationVersion of this map denotes the current
+ * "code version", and is also used as the destination version when
+ * running the initial setup migration on a blank database.
+ */
+export type IncrementalMigrationMap = {
     [destinationVersion: number]: Migration;
 };
 /**
  * Ensures that the schema is compatible with the current code, updating and
  * migrating the schema if necessary.
  */
-export declare function runSchemaMigrations(log: LogContext, debugName: string, schemaName: string, db: postgres.Sql, versionMigrationMap: VersionMigrationMap): Promise<void>;
-export declare const schemaVersions: v.ObjectType<{
-    version: v.Type<number>;
-    maxVersion: v.Type<number>;
-    minSafeRollbackVersion: v.Type<number>;
+export declare function runSchemaMigrations(log: LogContext, debugName: string, schemaName: string, db: PostgresDB, setupMigration: Migration, incrementalMigrationMap: IncrementalMigrationMap): Promise<void>;
+export declare const versionHistory: v.ObjectType<{
+    /**
+     * The `schemaVersion` is highest code version that has ever been run
+     * on the database, and is used to delineate the structure of the tables
+     * in the database. A schemaVersion only moves forward; rolling back to
+     * an earlier (safe) code version does not revert schema changes that
+     * have already been applied.
+     */
+    schemaVersion: v.Type<number>;
+    /**
+     * The data version is the code version of the latest server that ran.
+     * Note that this may be less than the schemaVersion in the case that
+     * a server is rolled back to an earlier version after a schema change.
+     * In such a case, data (but not schema), may need to be re-migrated
+     * when rolling forward again.
+     */
+    dataVersion: v.Type<number>;
+    /**
+     * The minimum code version that is safe to run. This is used when
+     * a schema migration is not backwards compatible with an older version
+     * of the code.
+     */
+    minSafeVersion: v.Type<number>;
 }, undefined>;
-export type SchemaVersions = v.Infer<typeof schemaVersions>;
-export declare function getSchemaVersions(sql: postgres.Sql, schemaName: string): Promise<SchemaVersions>;
+export type VersionHistory = v.Infer<typeof versionHistory>;
+export declare function getVersionHistory(sql: postgres.Sql, schemaName: string): Promise<VersionHistory>;
 export {};
 //# sourceMappingURL=migration.d.ts.map

package/out/zero-cache/src/db/migration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migration.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/db/migration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,QAAQ,MAAM,UAAU,CAAC;AAGrC,OAAO,KAAK,CAAC,MAAM,+BAA+B,CAAC;AAEnD;;;GAGG;AACH,KAAK,cAAc,GAAG,CAAC,GAAG,EAAE,UAAU,EAAE,EAAE,EAAE,QAAQ,CAAC,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE3E,KAAK,WAAW,GAAG,CACjB,GAAG,EAAE,UAAU,EACf,EAAE,EAAE,QAAQ,CAAC,cAAc,KACxB,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB;;;;GAIG;AACH,MAAM,MAAM,SAAS,GACjB;IAAC,GAAG,CAAC,EAAE,cAAc,CAAC;IAAC,GAAG,EAAE,WAAW,CAAA;CAAC,GAExC;IAAC,sBAAsB,EAAE,MAAM,CAAA;CAAC,CAAC;AAErC,kEAAkE;AAClE,MAAM,MAAM,mBAAmB,GAAG;IAChC,CAAC,kBAAkB,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC,CAAC;AAEF;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,UAAU,EACf,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,QAAQ,CAAC,GAAG,EAChB,mBAAmB,EAAE,mBAAmB,GACvC,OAAO,CAAC,IAAI,CAAC,CAyEf;AAaD,eAAO,MAAM,cAAc;;;;aAIzB,CAAC;AAGH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAG5D,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,QAAQ,CAAC,GAAG,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,cAAc,CAAC,CAsBzB"}
+{"version":3,"file":"migration.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/db/migration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,QAAQ,MAAM,UAAU,CAAC;AAGrC,OAAO,KAAK,CAAC,MAAM,+BAA+B,CAAC;AACnD,OAAO,KAAK,EAAC,UAAU,EAAE,mBAAmB,EAAC,MAAM,gBAAgB,CAAC;AAEpE,KAAK,UAAU,GAAG,CAAC,GAAG,EAAE,UAAU,EAAE,EAAE,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE9E;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB;;;;OAIG;IACH,aAAa,CAAC,EAAE,UAAU,CAAC;IAE3B;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,UAAU,CAAC;IAEzB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,CAAC,kBAAkB,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC,CAAC;AAEF;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,UAAU,EACf,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,UAAU,EACd,cAAc,EAAE,SAAS,EACzB,uBAAuB,EAAE,uBAAuB,GAC/C,OAAO,CAAC,IAAI,CAAC,CA+Ef;AAaD,eAAO,MAAM,cAAc;IACzB;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;OAIG;;aAEH,CAAC;AAGH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAG5D,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,QAAQ,CAAC,GAAG,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,cAAc,CAAC,CAsBzB"}

package/out/zero-cache/src/db/migration.js

@@ -5,50 +5,48 @@ import * as v from '../../../shared/src/valita.js';
  * Ensures that the schema is compatible with the current code, updating and
  * migrating the schema if necessary.
  */
-export async function runSchemaMigrations(log, debugName, schemaName, db, versionMigrationMap) {
+export async function runSchemaMigrations(log, debugName, schemaName, db, setupMigration, incrementalMigrationMap) {
     log = log.withContext('initSchema', randInt(0, Number.MAX_SAFE_INTEGER).toString(36));
     try {
-        const versionMigrations = sorted(versionMigrationMap);
-        if (versionMigrations.length === 0) {
-            log.info?.(`No versions/migrations to manage.`);
-            return;
-        }
-        const codeSchemaVersion = versionMigrations[versionMigrations.length - 1][0];
-        log.info?.(`Checking schema for compatibility with ${debugName} at schema v${codeSchemaVersion}`);
-        let meta = await db.begin(async (tx) => {
-            const meta = await getSchemaVersions(tx, schemaName);
-            if (codeSchemaVersion < meta.minSafeRollbackVersion) {
-                throw new Error(`Cannot run ${debugName} at schema v${codeSchemaVersion} because rollback limit is v${meta.minSafeRollbackVersion}`);
+        const versionMigrations = sorted(incrementalMigrationMap);
+        assert(versionMigrations.length, `Must specify at least one version migration`);
+        assert(versionMigrations[0][0] > 0, `Versions must be non-zero positive numbers`);
+        const codeVersion = versionMigrations[versionMigrations.length - 1][0];
+        log.info?.(`Checking schema for compatibility with ${debugName} at schema v${codeVersion}`);
+        let versions = await db.begin(async (tx) => {
+            const versions = await getVersionHistory(tx, schemaName);
+            if (codeVersion < versions.minSafeVersion) {
+                throw new Error(`Cannot run ${debugName} at schema v${codeVersion} because rollback limit is v${versions.minSafeVersion}`);
             }
-            if (meta.version > codeSchemaVersion) {
-                log.info?.(`Schema is at v${meta.version}. Resetting to v${codeSchemaVersion}`);
-                return setSchemaVersion(tx, schemaName, meta, codeSchemaVersion);
+            if (versions.dataVersion > codeVersion) {
+                log.info?.(`Data is at v${versions.dataVersion}. Resetting to v${codeVersion}`);
+                return updateVersionHistory(log, tx, schemaName, versions, codeVersion);
             }
-            return meta;
+            return versions;
         });
-        if (meta.version < codeSchemaVersion) {
-            for (const [dest, migration] of versionMigrations) {
-                if (meta.version < dest) {
-                    log.info?.(`Migrating schema from v${meta.version} to v${dest}`);
+        if (versions.dataVersion < codeVersion) {
+            const migrations = versions.dataVersion === 0
+                ? // For the empty database v0, only run the setup migration.
+                    [[codeVersion, setupMigration]]
+                : versionMigrations;
+            for (const [dest, migration] of migrations) {
+                if (versions.dataVersion < dest) {
+                    log.info?.(`Migrating schema from v${versions.dataVersion} to v${dest}`);
                     void log.flush(); // Flush logs before each migration to help debug crash-y migrations.
-                    // Run the optional PreMigration step before starting the transaction.
-                    if ('pre' in migration) {
-                        await migration.pre(log, db);
-                    }
-                    meta = await db.begin(async (tx) => {
+                    versions = await db.begin(async (tx) => {
                         // Fetch meta from within the transaction to make the migration atomic.
-                        let meta = await getSchemaVersions(tx, schemaName);
-                        if (meta.version < dest) {
-                            meta = await migrateSchemaVersion(log, schemaName, tx, meta, dest, migration);
-                            assert(meta.version === dest);
+                        let versions = await getVersionHistory(tx, schemaName);
+                        if (versions.dataVersion < dest) {
+                            versions = await runMigration(log, schemaName, tx, versions, dest, migration);
+                            assert(versions.dataVersion === dest);
                         }
-                        return meta;
+                        return versions;
                     });
                 }
             }
         }
-        assert(meta.version === codeSchemaVersion);
-        log.info?.(`Running ${debugName} at schema v${codeSchemaVersion}`);
+        assert(versions.dataVersion === codeVersion);
+        log.info?.(`Running ${debugName} at schema v${codeVersion}`);
     }
     catch (e) {
         log.error?.('Error in ensureSchemaMigrated', e);
@@ -58,82 +56,101 @@ export async function runSchemaMigrations(log, debugName, schemaName, db, versio
         void log.flush(); // Flush the logs but do not block server progress on it.
     }
 }
-function sorted(versionMigrationMap) {
+function sorted(incrementalMigrationMap) {
     const versionMigrations = [];
-    for (const [v, m] of Object.entries(versionMigrationMap)) {
+    for (const [v, m] of Object.entries(incrementalMigrationMap)) {
         versionMigrations.push([Number(v), m]);
     }
     return versionMigrations.sort(([a], [b]) => a - b);
 }
 // Exposed for tests.
-export const schemaVersions = v.object({
-    version: v.number(),
-    maxVersion: v.number(),
-    minSafeRollbackVersion: v.number(),
+export const versionHistory = v.object({
+    /**
+     * The `schemaVersion` is highest code version that has ever been run
+     * on the database, and is used to delineate the structure of the tables
+     * in the database. A schemaVersion only moves forward; rolling back to
+     * an earlier (safe) code version does not revert schema changes that
+     * have already been applied.
+     */
+    schemaVersion: v.number(),
+    /**
+     * The data version is the code version of the latest server that ran.
+     * Note that this may be less than the schemaVersion in the case that
+     * a server is rolled back to an earlier version after a schema change.
+     * In such a case, data (but not schema), may need to be re-migrated
+     * when rolling forward again.
+     */
+    dataVersion: v.number(),
+    /**
+     * The minimum code version that is safe to run. This is used when
+     * a schema migration is not backwards compatible with an older version
+     * of the code.
+     */
+    minSafeVersion: v.number(),
 });
 // Exposed for tests
-export async function getSchemaVersions(sql, schemaName) {
-    // Note: The `schema_meta.lock` column transparently ensures that at most one row exists.
+export async function getVersionHistory(sql, schemaName) {
+    // Note: The `lock` column transparently ensures that at most one row exists.
     const results = await sql `
     CREATE SCHEMA IF NOT EXISTS ${sql(schemaName)};
-    CREATE TABLE IF NOT EXISTS ${sql(schemaName)}."SchemaVersions" (
-      version int NOT NULL,
-      "maxVersion" int NOT NULL,
-      "minSafeRollbackVersion" int NOT NULL,
+    CREATE TABLE IF NOT EXISTS ${sql(schemaName)}."versionHistory" (
+      "dataVersion" int NOT NULL,
+      "schemaVersion" int NOT NULL,
+      "minSafeVersion" int NOT NULL,
 
       lock char(1) NOT NULL CONSTRAINT DF_schema_meta_lock DEFAULT 'v',
       CONSTRAINT PK_schema_meta_lock PRIMARY KEY (lock),
       CONSTRAINT CK_schema_meta_lock CHECK (lock='v')
     );
-    SELECT version, "maxVersion", "minSafeRollbackVersion" FROM ${sql(schemaName)}."SchemaVersions";
+    SELECT "dataVersion", "schemaVersion", "minSafeVersion" FROM ${sql(schemaName)}."versionHistory";
   `.simple();
     const rows = results[1];
     if (rows.length === 0) {
-        return { version: 0, maxVersion: 0, minSafeRollbackVersion: 0 };
+        return { schemaVersion: 0, dataVersion: 0, minSafeVersion: 0 };
     }
-    return v.parse(rows[0], schemaVersions);
+    return v.parse(rows[0], versionHistory);
 }
-async function setSchemaVersion(sql, schemaName, prev, newVersion) {
+async function updateVersionHistory(log, sql, schemaName, prev, newVersion, minSafeVersion) {
     assert(newVersion > 0);
-    const meta = {
-        ...prev,
-        version: newVersion,
-        maxVersion: Math.max(newVersion, prev.maxVersion),
+    const versions = {
+        dataVersion: newVersion,
+        // The schemaVersion never moves backwards.
+        schemaVersion: Math.max(newVersion, prev.schemaVersion),
+        minSafeVersion: getMinSafeVersion(log, prev, minSafeVersion),
     };
-    if (prev.version === 0) {
-        await sql `INSERT INTO ${sql(schemaName)}."SchemaVersions" ${sql(meta)}`;
-    }
-    else {
-        await sql `UPDATE ${sql(schemaName)}."SchemaVersions" set ${sql(meta)}`;
-    }
-    return meta;
+    await sql `
+    INSERT INTO ${sql(schemaName)}."versionHistory" ${sql(versions)}
+      ON CONFLICT (lock) DO UPDATE SET ${sql(versions)}
+  `;
+    return versions;
 }
-async function migrateSchemaVersion(log, schemaName, tx, meta, destinationVersion, migration) {
-    if ('run' in migration) {
-        await migration.run(log, tx);
+async function runMigration(log, schemaName, tx, versions, destinationVersion, migration) {
+    if (versions.schemaVersion < destinationVersion) {
+        await migration.migrateSchema?.(log, tx);
     }
-    else {
-        meta = ensureRollbackLimit(migration.minSafeRollbackVersion, log, meta);
+    if (versions.dataVersion < destinationVersion) {
+        await migration.migrateData?.(log, tx);
     }
-    return setSchemaVersion(tx, schemaName, meta, destinationVersion);
+    return updateVersionHistory(log, tx, schemaName, versions, destinationVersion, migration.minSafeVersion);
 }
 /**
  * Bumps the rollback limit [[toAtLeast]] the specified version.
  * Leaves the rollback limit unchanged if it is equal or greater.
  */
-function ensureRollbackLimit(toAtLeast, log, meta) {
+function getMinSafeVersion(log, current, proposedSafeVersion) {
+    if (proposedSafeVersion === undefined) {
+        return current.minSafeVersion;
+    }
     // Sanity check to maintain the invariant that running code is never
     // earlier than the rollback limit.
-    assert(toAtLeast <= meta.version + 1);
-    if (meta.minSafeRollbackVersion >= toAtLeast) {
+    assert(proposedSafeVersion <= current.dataVersion + 1);
+    if (current.minSafeVersion >= proposedSafeVersion) {
         // The rollback limit must never move backwards.
-        log.debug?.(`rollback limit is already at ${meta.minSafeRollbackVersion}, don't need to bump to ${toAtLeast}`);
-        return meta;
+        log.debug?.(`rollback limit is already at ${current.minSafeVersion}, ` +
+            `don't need to bump to ${proposedSafeVersion}`);
+        return current.minSafeVersion;
     }
-    log.info?.(`bumping rollback limit from ${meta.minSafeRollbackVersion} to ${toAtLeast}`);
-    return {
-        ...meta,
-        minSafeRollbackVersion: toAtLeast,
-    };
+    log.info?.(`bumping rollback limit from ${current.minSafeVersion} to ${proposedSafeVersion}`);
+    return proposedSafeVersion;
 }
 //# sourceMappingURL=migration.js.map