feat: migration handling

apps/pidb-kanban-example/src/lib/prisma-idb/client/idb-interface.ts

@@ -27,6 +27,10 @@ export interface PrismaIDBSchema extends DBSchema {
     key: [model: string, key: IDBValidKey];
     value: ChangeMetaRecord;
   };
+  _idb_meta: {
+    key: string;
+    value: string;
+  };
 }
 export interface OutboxEventRecord {
   id: string;

apps/pidb-kanban-example/src/lib/prisma-idb/client/idb-schema-hash.ts

@@ -0,0 +1,2 @@
+// Auto-generated by idb-client-generator — always regenerated
+export const IDB_SCHEMA_HASH = "56b52d79";

apps/pidb-kanban-example/src/lib/prisma-idb/client/index.ts

@@ -2,3 +2,4 @@ export * from "./prisma-idb-client";
 export * from "./idb-interface";
 export * from "./idb-utils";
 export * from "./apply-pull";
+export * from "./idb-schema-hash";

apps/pidb-kanban-example/src/lib/prisma-idb/client/prisma-idb-client.ts

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/no-unused-vars */
-import { openDB } from "idb";
+import { openDB, deleteDB } from "idb";
 import type { IDBPDatabase, StoreNames, IDBPTransaction } from "idb";
 import type { Prisma } from "./generated/client";
 import * as IDBUtils from "./idb-utils";
@@ -14,8 +14,10 @@ import type { PushResult } from "../server/batch-processor";
 import { validators, keyPathValidators, modelRecordToKeyPath } from "../validators";
 import type { LogWithStringifiedRecord } from "../server/batch-processor";
 import { applyPull, type ApplyPullResult } from "./apply-pull";
+import { IDB_SCHEMA_HASH } from "./idb-schema-hash";
 import { v4 as uuidv4 } from "uuid";
 const IDB_VERSION = 1;
+const DROP_DB_ON_SCHEMA_VERSION_MISMATCH = false;
 type CreateSyncWorkerOptions = {
   push: {
     handler: (events: OutboxEventRecord[]) => Promise<PushResult[]>;
@@ -52,6 +54,18 @@ export class PrismaIDBClient {
     if (!PrismaIDBClient.instance) {
       const client = new PrismaIDBClient();
       await client.initialize();
+      const storedHash = await client._db.get("_idb_meta", "schemaHash");
+      if (storedHash !== undefined && storedHash !== IDB_SCHEMA_HASH) {
+        client._db.close();
+        if (!DROP_DB_ON_SCHEMA_VERSION_MISMATCH) {
+          throw new Error(
+            `IDB schema mismatch: stored hash "${storedHash}" does not match expected "${IDB_SCHEMA_HASH}". Set dropDbOnSchemaVersionMismatch = true in your generator config to automatically reset the database.`
+          );
+        }
+        await deleteDB("prisma-idb");
+        return PrismaIDBClient.createClient();
+      }
+      await client._db.put("_idb_meta", IDB_SCHEMA_HASH, "schemaHash");
       PrismaIDBClient.instance = client;
     }
     return PrismaIDBClient.instance;
@@ -439,16 +453,21 @@ export class PrismaIDBClient {
     };
   }
   private async initialize() {
-    this._db = await openDB<PrismaIDBSchema>("prisma-idb", IDB_VERSION, {
+    const db = await openDB<PrismaIDBSchema>("prisma-idb", IDB_VERSION, {
       upgrade(db) {
         db.createObjectStore("Board", { keyPath: ["id"] });
         db.createObjectStore("Todo", { keyPath: ["id"] });
         const UserStore = db.createObjectStore("User", { keyPath: ["id"] });
         UserStore.createIndex("emailIndex", ["email"], { unique: true });
         db.createObjectStore("OutboxEvent", { keyPath: ["id"] });
         db.createObjectStore("VersionMeta", { keyPath: ["model", "key"] });
+        db.createObjectStore("_idb_meta");
+      },
+      blocking() {
+        db.close();
       },
     });
+    this._db = db;
     this.board = new BoardIDBClass(this, ["id"]);
     this.todo = new TodoIDBClass(this, ["id"]);
     this.user = new UserIDBClass(this, ["id"]);

apps/usage/src/lib/prisma-idb/client/idb-interface.ts

@@ -74,4 +74,8 @@ export interface PrismaIDBSchema extends DBSchema {
     key: [id: Prisma.Todo["id"]];
     value: Prisma.Todo;
   };
+  _idb_meta: {
+    key: string;
+    value: string;
+  };
 }

apps/usage/src/lib/prisma-idb/client/idb-schema-hash.ts

@@ -0,0 +1,2 @@
+// Auto-generated by idb-client-generator — always regenerated
+export const IDB_SCHEMA_HASH = "d1c83f66";

apps/usage/src/lib/prisma-idb/client/index.ts

@@ -1,3 +1,4 @@
 export * from "./prisma-idb-client";
 export * from "./idb-interface";
 export * from "./idb-utils";
+export * from "./idb-schema-hash";

apps/usage/src/lib/prisma-idb/client/prisma-idb-client.ts

@@ -1,12 +1,14 @@
 /* eslint-disable @typescript-eslint/no-unused-vars */
-import { openDB } from "idb";
+import { openDB, deleteDB } from "idb";
 import type { IDBPDatabase, StoreNames, IDBPTransaction } from "idb";
 import type { Prisma } from "../../generated/prisma/client";
 import * as IDBUtils from "./idb-utils";
 import type { PrismaIDBSchema } from "./idb-interface";
+import { IDB_SCHEMA_HASH } from "./idb-schema-hash";
 import { createId } from "@paralleldrive/cuid2";
 import { v4 as uuidv4 } from "uuid";
 const IDB_VERSION = 1;
+const DROP_DB_ON_SCHEMA_VERSION_MISMATCH = false;
 export class PrismaIDBClient {
   private static instance: PrismaIDBClient;
   _db!: IDBPDatabase<PrismaIDBSchema>;
@@ -51,6 +53,18 @@ export class PrismaIDBClient {
     if (!PrismaIDBClient.instance) {
       const client = new PrismaIDBClient();
       await client.initialize();
+      const storedHash = await client._db.get("_idb_meta", "schemaHash");
+      if (storedHash !== undefined && storedHash !== IDB_SCHEMA_HASH) {
+        client._db.close();
+        if (!DROP_DB_ON_SCHEMA_VERSION_MISMATCH) {
+          throw new Error(
+            `IDB schema mismatch: stored hash "${storedHash}" does not match expected "${IDB_SCHEMA_HASH}". Set dropDbOnSchemaVersionMismatch = true in your generator config to automatically reset the database.`
+          );
+        }
+        await deleteDB("prisma-idb");
+        return PrismaIDBClient.createClient();
+      }
+      await client._db.put("_idb_meta", IDB_SCHEMA_HASH, "schemaHash");
       PrismaIDBClient.instance = client;
     }
     return PrismaIDBClient.instance;
@@ -64,7 +78,7 @@ export class PrismaIDBClient {
     return this.outboxEnabled && this.includedModels.has(modelName);
   }
   private async initialize() {
-    this._db = await openDB<PrismaIDBSchema>("prisma-idb", IDB_VERSION, {
+    const db = await openDB<PrismaIDBSchema>("prisma-idb", IDB_VERSION, {
       upgrade(db) {
         db.createObjectStore("User", { keyPath: ["id"] });
         db.createObjectStore("Group", { keyPath: ["id"] });
@@ -86,8 +100,13 @@ export class PrismaIDBClient {
         const ModelWithUniqueAttributesStore = db.createObjectStore("ModelWithUniqueAttributes", { keyPath: ["id"] });
         ModelWithUniqueAttributesStore.createIndex("codeIndex", ["code"], { unique: true });
         db.createObjectStore("Todo", { keyPath: ["id"] });
+        db.createObjectStore("_idb_meta");
+      },
+      blocking() {
+        db.close();
       },
     });
+    this._db = db;
     this.user = new UserIDBClass(this, ["id"]);
     this.group = new GroupIDBClass(this, ["id"]);
     this.userGroup = new UserGroupIDBClass(this, ["groupId", "userId"]);

package.json

@@ -12,7 +12,7 @@
     "test": "turbo run test",
     "test:client": "turbo run test --filter=@prisma-idb/usage",
     "test:sync": "turbo run test --filter=@prisma-idb/pidb-kanban-example",
-    "test:schema-gen": "turbo run test --filter=@prisma-idb/tests",
+    "test:schema-gen": "turbo run test --filter=@prisma-idb/schema-gen-tests",
     "test:watch": "turbo run test:watch --no-cache",
     "generate": "turbo run generate",
     "clean": "turbo clean && rm -rf node_modules",

packages/generator/src/fileCreators/apply-pull/create.ts

@@ -2,7 +2,14 @@ import CodeBlockWriter from "code-block-writer";
 import { Model } from "../types";
 import { getUniqueIdentifiers } from "../../helpers/utils";
 
-export function createApplyPullFile(writer: CodeBlockWriter, models: Model[], versionMetaModelName: string) {
+export function createApplyPullFile(
+  writer: CodeBlockWriter,
+  options: {
+    models: Model[];
+    versionMetaModelName: string;
+  }
+) {
+  const { models, versionMetaModelName } = options;
   // Write imports
   writer.writeLine(`import type { LogWithStringifiedRecord } from '../server/batch-processor';`);
   writer.writeLine(`import { validators, keyPathValidators } from '../validators';`);

packages/generator/src/fileCreators/batch-processor/create.ts

@@ -59,10 +59,13 @@ function buildAuthorizationPath(
 
 export function createBatchProcessorFile(
   writer: CodeBlockWriter,
-  models: readonly Model[],
-  prismaClientImport: string,
-  rootModel: Model
+  options: {
+    models: readonly Model[];
+    prismaClientImport: string;
+    rootModel: Model;
+  }
 ) {
+  const { models, prismaClientImport, rootModel } = options;
   const modelNames = models.map((m) => m.name);
 
   // Write imports

packages/generator/src/fileCreators/idb-interface/create.ts

@@ -5,12 +5,23 @@ import CodeBlockWriter from "code-block-writer";
 
 export function createIDBInterfaceFile(
   writer: CodeBlockWriter,
-  models: DMMF.Datamodel["models"],
-  prismaClientImport: string,
-  outboxSync: boolean,
-  outboxModelName: string,
-  versionMetaModelName: string
+  options: {
+    models: DMMF.Datamodel["models"];
+    prismaClientImport: string;
+    outboxSync: boolean;
+    outboxModelName: string;
+    versionMetaModelName: string;
+    hasMigrations?: boolean;
+  }
 ) {
+  const {
+    models,
+    prismaClientImport,
+    outboxSync,
+    outboxModelName,
+    versionMetaModelName,
+    hasMigrations = false,
+  } = options;
   writer.writeLine(`import type { DBSchema } from "idb";`);
   writer.writeLine(`import type * as Prisma from "${prismaClientImport}";`);
   if (outboxSync) {
@@ -42,6 +53,13 @@ export function createIDBInterfaceFile(
         writer.writeLine(`value: ChangeMetaRecord;`);
       });
     }
+
+    if (hasMigrations) {
+      writer.writeLine(`_idb_meta: `).block(() => {
+        writer.writeLine(`key: string;`);
+        writer.writeLine(`value: string;`);
+      });
+    }
   });
 
   // Add type definition for OutboxEventRecord

packages/generator/src/fileCreators/idb-schema-hash/create.ts

@@ -0,0 +1,10 @@
+import CodeBlockWriter from "code-block-writer";
+
+/**
+ * Generate the idb-schema-hash.ts file content.
+ * This file is always regenerated on every `prisma generate` run.
+ */
+export function createSchemaHashFile(writer: CodeBlockWriter, hash: string) {
+  writer.writeLine(`// Auto-generated by idb-client-generator — always regenerated`);
+  writer.writeLine(`export const IDB_SCHEMA_HASH = ${JSON.stringify(hash)};`);
+}

packages/generator/src/fileCreators/idb-utils/create.ts

@@ -30,10 +30,13 @@ import { addAreUint8ArraysEqualHelper } from "./helpers/areUint8ArraysEqual";
 
 export function createUtilsFile(
   writer: CodeBlockWriter,
-  models: readonly Model[],
-  prismaClientImport: string,
-  outboxSync: boolean = false
+  options: {
+    models: readonly Model[];
+    prismaClientImport: string;
+    outboxSync?: boolean;
+  }
 ) {
+  const { models, prismaClientImport, outboxSync = false } = options;
   writer.writeLine(`import type { IDBPTransaction, StoreNames } from "idb";`);
   writer.writeLine(`import type { PrismaIDBSchema } from "./idb-interface";`);
   writer.writeLine(`import type { Prisma } from "${prismaClientImport}";`);

packages/generator/src/fileCreators/index/create-client-index.ts

@@ -1,10 +1,20 @@
 import type CodeBlockWriter from "code-block-writer";
 
-export function createClientIndexFile(writer: CodeBlockWriter, outboxSync: boolean) {
+export function createClientIndexFile(
+  writer: CodeBlockWriter,
+  options: {
+    outboxSync: boolean;
+    hasMigrations?: boolean;
+  }
+) {
+  const { outboxSync, hasMigrations = false } = options;
   writer.writeLine(`export * from './prisma-idb-client';`);
   writer.writeLine(`export * from './idb-interface';`);
   writer.writeLine(`export * from './idb-utils';`);
   if (outboxSync) {
     writer.writeLine(`export * from './apply-pull';`);
   }
+  if (hasMigrations) {
+    writer.writeLine(`export * from './idb-schema-hash';`);
+  }
 }