u

src/providers/schemaMigrations.js

@@ -138,8 +138,11 @@ export function makeVersionContext(file, getVersion, setVersion) {
  * @returns {Promise<number>} Number of steps applied.
  */
 export async function migrateSchema({ direction, dirUrl, current, target, runStep, log = console.log }) {
-  if (direction === 'upgrade' && target < current) {
+  if (direction === 'upgrade' && current > target) {
-    throw new Error(`Database schema version ${current} is newer than this application supports (${target})`);
+    throw new Error(
+      `Refusing to start: database schema version (${current}) is higher than the highest version in the upgrade folder (${target}). ` +
+      `The database was updated by a newer version of the application. Please update the application code or downgrade the database schema.`
+    );
   }
   if (direction === 'downgrade' && target > current) {
     throw new Error(`Cannot downgrade schema from version ${current} to higher version ${target}`);

test/migration.test.js

@@ -108,5 +108,26 @@ test('schema migrations & posterminal version 2', async (t) => {
     assert.ok(cols.includes('enabled'), 'enabled column should be restored');
     assert.ok(cols.includes('clientversion'), 'clientversion column should be restored');
   });
+
+  await t.test('refuses to initialize if db schema version is higher than highest upgrade version', async () => {
+    // Manually set database meta version to a future version (e.g. 99)
+    provider.db.prepare(`UPDATE meta SET value = '99' WHERE "key" = 'version'`).run();
+    const futureVersion = await provider.getSchemaVersion();
+    assert.equal(futureVersion, 99);
+
+    await assert.rejects(
+      async () => {
+        await provider.initialize();
+      },
+      (err) => {
+        assert.match(err.message, /Refusing to start: database schema version \(99\) is higher than the highest version in the upgrade folder \(2\)/);
+        return true;
+      },
+      'Should throw and refuse to initialize'
+    );
+
+    // Restore to version 2 so cleanup/subsequent steps stay consistent
+    provider.db.prepare(`UPDATE meta SET value = '2' WHERE "key" = 'version'`).run();
+  });
 });