Pseudocode for Schema Migration

Author: schmidt-sebastian

packages/firestore/src/local/indexeddb_migrations.ts

@@ -15,28 +15,20 @@
  */
 import {
   DbDocumentMutation, DbInstance,
-  DbMutationBatch, DbMutationQueue, DbOwner, DbRemoteDocument, DbTarget,
+  DbMutationBatch, DbMutationQueue, DbOwner,
+  DbRemoteDocument, DbTarget,
   DbTargetDocument, DbTargetGlobal
 } from './indexeddb_schema';
-import {fail} from '../util/assert';
+import {assert, fail} from '../util/assert';
 
-export function createDb(db: IDBDatabase): void {
-  db.createObjectStore(DbMutationQueue.store, {
-    keyPath: DbMutationQueue.keyPath
-  });
-
-  // TODO(mikelehen): Get rid of "as any" if/when TypeScript fixes their
-  // types. https://github.com/Microsoft/TypeScript/issues/14322
-  db.createObjectStore(
-      DbMutationBatch.store,
-      // tslint:disable-next-line:no-any
-      { keyPath: DbMutationBatch.keyPath as any }
-  );
+// TODO(mikelehen): Get rid of "as any" if/when TypeScript fixes their types.
+// https://github.com/Microsoft/TypeScript/issues/14322
+type KeyPath = any; // tslint:disable-line:no-any
 
+function createCache(db: IDBDatabase): void {
   const targetDocumentsStore = db.createObjectStore(
       DbTargetDocument.store,
-      // tslint:disable-next-line:no-any
-      { keyPath: DbTargetDocument.keyPath as any }
+      { keyPath: DbTargetDocument.keyPath as KeyPath }
   );
   targetDocumentsStore.createIndex(
       DbTargetDocument.documentTargetsIndex,
@@ -47,45 +39,72 @@ export function createDb(db: IDBDatabase): void {
   const targetStore = db.createObjectStore(DbTarget.store, {
     keyPath: DbTarget.keyPath
   });
+
   // NOTE: This is unique only because the TargetId is the suffix.
   targetStore.createIndex(
       DbTarget.queryTargetsIndexName,
       DbTarget.queryTargetsKeyPath,
       { unique: true }
   );
+  db.createObjectStore(DbRemoteDocument.store);
+  db.createObjectStore(DbTargetGlobal.store);
+}
+
+function dropCache(db: IDBDatabase): void {
+  db.deleteObjectStore(DbTargetDocument.store);
+  db.deleteObjectStore(DbTarget.keyPath);
+  db.deleteObjectStore(DbRemoteDocument.store);
+  db.deleteObjectStore(DbTargetGlobal.store);
+}
 
-  const instanceStore = db.createObjectStore(DbInstance.store, {
-    keyPath: DbInstance.keyPath as any
+function createOwnerStore(db: IDBDatabase) : void {
+  db.createObjectStore(DbOwner.store);
+}
+
+function createInstanceStore(db: IDBDatabase) : void {
+  db.createObjectStore(DbInstance.store, {
+    keyPath: DbInstance.keyPath as KeyPath
   });
+}
+
+function createMutationQueue(db: IDBDatabase) : void {
+  db.createObjectStore(DbMutationQueue.store, {
+    keyPath: DbMutationQueue.keyPath
+  });
+
+  db.createObjectStore(
+      DbMutationBatch.store,
+      { keyPath: DbMutationBatch.keyPath as KeyPath }
+  );
 
   // NOTE: keys for these stores are specified explicitly rather than using a
   // keyPath.
   db.createObjectStore(DbDocumentMutation.store);
-  db.createObjectStore(DbRemoteDocument.store);
-  db.createObjectStore(DbOwner.store);
-  db.createObjectStore(DbTargetGlobal.store);
 }
 
-export function upgradeDbFromV1(db: IDBDatabase): void {
+/**
+ * Runs any migrations needed to bring the given database up to the current
+ * schema version.
+ */
+export function createOrUpgradeDb(db: IDBDatabase, oldVersion: number, newVersion: number): void   {
+  assert(oldVersion >= 0 || oldVersion <= 1, 'Unexpected upgrade from version ' + oldVersion);
+  assert(newVersion >= 1 || newVersion <= 2, 'Unexpected upgrade to version ' + newVersion);
 
-}
+  const createV1 = newVersion >= 1 && oldVersion <= 1;
+  const dropV1 = oldVersion >= 1;
+  const createV2 = newVersion >= 2 && oldVersion <= 2;
 
-export class IndexedDbMigrations {
-  /**
-   * Runs any migrations needed to bring the given database up to the current
-   * schema version.
-   */
-  static runMigrations(db: IDBDatabase, oldVersion: number) {
-    if (oldVersion == 0) {
-      createDb(db, oldVersion);
-      return;
-    }
+  if (dropV1) {
+    dropCache(db);
+  }
 
-    if (oldVersion == 1) {
-      upgradeDbFromV1(db, oldVersion);
-      return;
-    }
+  if (createV1) {
+    createOwnerStore(db);
+    createMutationQueue(db);
+    createCache(db);
+  }
 
-    fail('Unexpected upgrade from version ' + oldVersion);
+  if (createV2) {
+    createInstanceStore(db);
   }
 }

packages/firestore/src/local/indexeddb_persistence.ts

@@ -26,15 +26,15 @@ import { IndexedDbMutationQueue } from './indexeddb_mutation_queue';
 import { IndexedDbQueryCache } from './indexeddb_query_cache';
 import { IndexedDbRemoteDocumentCache } from './indexeddb_remote_document_cache';
 import { ALL_STORES, DbOwner, DbOwnerKey } from './indexeddb_schema';
-import { createOrUpgradeDb, SCHEMA_VERSION } from './indexeddb_schema';
+import { SCHEMA_VERSION } from './indexeddb_schema';
 import { LocalSerializer } from './local_serializer';
 import { MutationQueue } from './mutation_queue';
 import { Persistence } from './persistence';
 import { PersistencePromise } from './persistence_promise';
 import { QueryCache } from './query_cache';
 import { RemoteDocumentCache } from './remote_document_cache';
 import { SimpleDb, SimpleDbTransaction } from './simple_db';
-import {IndexedDbMigrations} from './indexeddb_migrations';
+import {createOrUpgradeDb} from './indexeddb_migrations';
 
 const LOG_TAG = 'IndexedDbPersistence';
 
@@ -128,7 +128,7 @@ export class IndexedDbPersistence implements Persistence {
     assert(!this.started, 'IndexedDbPersistence double-started!');
     this.started = true;
 
-    return SimpleDb.openOrCreate(this.dbName, SCHEMA_VERSION, IndexedDbMigrations.runMigrations)
+    return SimpleDb.openOrCreate(this.dbName, SCHEMA_VERSION, createOrUpgradeDb)
       .then(db => {
         this.simpleDb = db;
       })

packages/firestore/src/local/indexeddb_schema.ts

@@ -21,6 +21,7 @@ import { ResourcePath } from '../model/path';
 import { assert } from '../util/assert';
 
 import { encode, EncodedResourcePath } from './encoded_resource_path';
+import {SnapshotVersion} from '../core/snapshot_version';
 
 export const SCHEMA_VERSION = 1;
 
@@ -86,7 +87,15 @@ export class DbMutationQueue {
      * After sending this token, earlier tokens may not be used anymore so
      * only a single stream token is retained.
      */
-    public lastStreamToken: string
+    public lastStreamToken: string,
+
+    /**
+     * An identifier for the highest numbered batch that has been acknowledged
+     * by the server. All MutationBatches in this queue with batchIds less
+     * than or equal to this value are considered to have been acknowledged by
+     * the server.
+     */
+    public highestPendingBatchId: number,
   ) {}
 }
 
@@ -345,8 +354,8 @@ export class DbTargetDocument {
   /** Name of the IndexedDb object store.  */
   static store = 'targetDocuments';
 
-  /** Keys are automatically assigned via the targetId, path properties. */
-  static keyPath = ['targetId', 'path'];
+  /** Keys are automatically assigned via the targetId, snapshotVersion, and path properties. */
+  static keyPath = ['targetId', 'snapshotVersion', 'path'];
 
   /** The index name for the reverse index. */
   static documentTargetsIndex = 'documentTargetsIndex';
@@ -359,6 +368,8 @@ export class DbTargetDocument {
      * The targetId identifying a target.
      */
     public targetId: TargetId,
+
+    public snapshotVersion: number,
     /**
      * The path to the document, as encoded in the key.
      */
@@ -420,8 +431,7 @@ export class DbInstance {
   constructor(
       public userId: string,
       public instanceId: string,
-      public updateTimeMs: number,
-      public visibilityState: VisibilityState
+      public updateTimeMs: number
   ) {}
 }
 
@@ -437,5 +447,6 @@ export const ALL_STORES = [
   DbTarget.store,
   DbOwner.store,
   DbTargetGlobal.store,
-  DbTargetDocument.store
+  DbTargetDocument.store,
+  DbInstance.store
 ];

packages/firestore/src/local/simple_db.ts

@@ -19,6 +19,7 @@ import { debug } from '../util/log';
 import { AnyDuringMigration } from '../util/misc';
 
 import { PersistencePromise } from './persistence_promise';
+import {SCHEMA_VERSION} from './indexeddb_schema';
 
 const LOG_TAG = 'SimpleDb';
 
@@ -34,7 +35,7 @@ export class SimpleDb {
   static openOrCreate(
     name: string,
     version: number,
-    runUpgrade: (db: IDBDatabase, oldVersion: number) => void
+    runUpgrade: (db: IDBDatabase, oldVersion: number, newVersion: number) => void
   ): Promise<SimpleDb> {
     assert(
       SimpleDb.isAvailable(),
@@ -70,7 +71,7 @@ export class SimpleDb {
         // cheating and just passing the raw IndexedDB in, since
         // createObjectStore(), etc. are synchronous.
         const db = (event.target as IDBOpenDBRequest).result;
-        runUpgrade(db, event.oldVersion);
+        runUpgrade(db, event.oldVersion, SCHEMA_VERSION);
       };
     }).toPromise();
   }