@powersync/service-module-mongodb-storage 0.0.0-dev-20250507154604 → 0.0.0-dev-20250611110033

package/src/storage/implementation/MongoBucketBatch.ts

@@ -7,11 +7,19 @@ import {
   container,
   ErrorCode,
   errors,
-  logger,
+  Logger,
+  logger as defaultLogger,
   ReplicationAssertionError,
   ServiceError
 } from '@powersync/lib-services-framework';
-import { deserializeBson, InternalOpId, SaveOperationTag, storage, utils } from '@powersync/service-core';
+import {
+  BucketStorageMarkRecordUnavailable,
+  deserializeBson,
+  InternalOpId,
+  SaveOperationTag,
+  storage,
+  utils
+} from '@powersync/service-core';
 import * as timers from 'node:timers/promises';
 import { PowerSyncMongo } from './db.js';
 import { CurrentBucket, CurrentDataDocument, SourceKey, SyncRuleDocument } from './models.js';
@@ -46,12 +54,18 @@ export interface MongoBucketBatchOptions {
    * Set to true for initial replication.
    */
   skipExistingRows: boolean;
+
+  markRecordUnavailable: BucketStorageMarkRecordUnavailable | undefined;
+
+  logger?: Logger;
 }
 
 export class MongoBucketBatch
   extends BaseObserver<storage.BucketBatchStorageListener>
   implements storage.BucketStorageBatch
 {
+  private logger: Logger;
+
   private readonly client: mongo.MongoClient;
   public readonly db: PowerSyncMongo;
   public readonly session: mongo.ClientSession;
@@ -65,6 +79,7 @@ export class MongoBucketBatch
 
   private batch: OperationBatch | null = null;
   private write_checkpoint_batch: storage.CustomWriteCheckpointOptions[] = [];
+  private markRecordUnavailable: BucketStorageMarkRecordUnavailable | undefined;
 
   /**
    * Last LSN received associated with a checkpoint.
@@ -86,6 +101,7 @@ export class MongoBucketBatch
 
   constructor(options: MongoBucketBatchOptions) {
     super();
+    this.logger = options.logger ?? defaultLogger;
     this.client = options.db.client;
     this.db = options.db;
     this.group_id = options.groupId;
@@ -96,6 +112,7 @@ export class MongoBucketBatch
     this.sync_rules = options.syncRules;
     this.storeCurrentData = options.storeCurrentData;
     this.skipExistingRows = options.skipExistingRows;
+    this.markRecordUnavailable = options.markRecordUnavailable;
     this.batch = new OperationBatch();
 
     this.persisted_op = options.keepaliveOp ?? null;
@@ -112,12 +129,12 @@ export class MongoBucketBatch
     return this.last_checkpoint_lsn;
   }
 
-  async flush(): Promise<storage.FlushedResult | null> {
+  async flush(options?: storage.BucketBatchCommitOptions): Promise<storage.FlushedResult | null> {
     let result: storage.FlushedResult | null = null;
     // One flush may be split over multiple transactions.
     // Each flushInner() is one transaction.
     while (this.batch != null) {
-      let r = await this.flushInner();
+      let r = await this.flushInner(options);
       if (r) {
         result = r;
       }
@@ -127,7 +144,7 @@ export class MongoBucketBatch
     return result;
   }
 
-  private async flushInner(): Promise<storage.FlushedResult | null> {
+  private async flushInner(options?: storage.BucketBatchCommitOptions): Promise<storage.FlushedResult | null> {
     const batch = this.batch;
     if (batch == null) {
       return null;
@@ -137,7 +154,7 @@ export class MongoBucketBatch
     let resumeBatch: OperationBatch | null = null;
 
     await this.withReplicationTransaction(`Flushing ${batch.length} ops`, async (session, opSeq) => {
-      resumeBatch = await this.replicateBatch(session, batch, opSeq);
+      resumeBatch = await this.replicateBatch(session, batch, opSeq, options);
 
       last_op = opSeq.last();
     });
@@ -157,7 +174,8 @@ export class MongoBucketBatch
   private async replicateBatch(
     session: mongo.ClientSession,
     batch: OperationBatch,
-    op_seq: MongoIdSequence
+    op_seq: MongoIdSequence,
+    options?: storage.BucketBatchCommitOptions
   ): Promise<OperationBatch | null> {
     let sizes: Map<string, number> | undefined = undefined;
     if (this.storeCurrentData && !this.skipExistingRows) {
@@ -231,7 +249,9 @@ export class MongoBucketBatch
         current_data_lookup.set(cacheKey(doc._id.t, doc._id.k), doc);
       }
 
-      let persistedBatch: PersistedBatch | null = new PersistedBatch(this.group_id, transactionSize);
+      let persistedBatch: PersistedBatch | null = new PersistedBatch(this.group_id, transactionSize, {
+        logger: this.logger
+      });
 
       for (let op of b) {
         if (resumeBatch) {
@@ -253,7 +273,7 @@ export class MongoBucketBatch
         if (persistedBatch!.shouldFlushTransaction()) {
           // Transaction is getting big.
           // Flush, and resume in a new transaction.
-          await persistedBatch!.flush(this.db, this.session);
+          await persistedBatch!.flush(this.db, this.session, options);
           persistedBatch = null;
           // Computing our current progress is a little tricky here, since
           // we're stopping in the middle of a batch.
@@ -264,7 +284,7 @@ export class MongoBucketBatch
 
       if (persistedBatch) {
         transactionSize = persistedBatch.currentSize;
-        await persistedBatch.flush(this.db, this.session);
+        await persistedBatch.flush(this.db, this.session, options);
       }
     }
 
@@ -310,11 +330,18 @@ export class MongoBucketBatch
         // Not an error if we re-apply a transaction
         existing_buckets = [];
         existing_lookups = [];
-        // Log to help with debugging if there was a consistency issue
         if (this.storeCurrentData) {
-          logger.warn(
-            `Cannot find previous record for update on ${record.sourceTable.qualifiedName}: ${beforeId} / ${record.before?.id}`
-          );
+          if (this.markRecordUnavailable != null) {
+            // This will trigger a "resnapshot" of the record.
+            // This is not relevant if storeCurrentData is false, since we'll get the full row
+            // directly in the replication stream.
+            this.markRecordUnavailable(record);
+          } else {
+            // Log to help with debugging if there was a consistency issue
+            this.logger.warn(
+              `Cannot find previous record for update on ${record.sourceTable.qualifiedName}: ${beforeId} / ${record.before?.id}`
+            );
+          }
         }
       } else {
         existing_buckets = result.buckets;
@@ -331,8 +358,8 @@ export class MongoBucketBatch
         existing_buckets = [];
         existing_lookups = [];
         // Log to help with debugging if there was a consistency issue
-        if (this.storeCurrentData) {
-          logger.warn(
+        if (this.storeCurrentData && this.markRecordUnavailable == null) {
+          this.logger.warn(
             `Cannot find previous record for delete on ${record.sourceTable.qualifiedName}: ${beforeId} / ${record.before?.id}`
           );
         }
@@ -429,7 +456,7 @@ export class MongoBucketBatch
               }
             }
           );
-          logger.error(
+          this.logger.error(
             `Failed to evaluate data query on ${record.sourceTable.qualifiedName}.${record.after?.id}: ${error.error}`
           );
         }
@@ -469,7 +496,7 @@ export class MongoBucketBatch
               }
             }
           );
-          logger.error(
+          this.logger.error(
             `Failed to evaluate parameter query on ${record.sourceTable.qualifiedName}.${after.id}: ${error.error}`
           );
         }
@@ -523,7 +550,7 @@ export class MongoBucketBatch
             if (e instanceof mongo.MongoError && e.hasErrorLabel('TransientTransactionError')) {
               // Likely write conflict caused by concurrent write stream replicating
             } else {
-              logger.warn('Transaction error', e as Error);
+              this.logger.warn('Transaction error', e as Error);
             }
             await timers.setTimeout(Math.random() * 50);
             throw e;
@@ -548,7 +575,7 @@ export class MongoBucketBatch
     await this.withTransaction(async () => {
       flushTry += 1;
       if (flushTry % 10 == 0) {
-        logger.info(`${this.slot_name} ${description} - try ${flushTry}`);
+        this.logger.info(`${description} - try ${flushTry}`);
       }
       if (flushTry > 20 && Date.now() > lastTry) {
         throw new ServiceError(ErrorCode.PSYNC_S1402, 'Max transaction tries exceeded');
@@ -613,17 +640,18 @@ export class MongoBucketBatch
   async commit(lsn: string, options?: storage.BucketBatchCommitOptions): Promise<boolean> {
     const { createEmptyCheckpoints } = { ...storage.DEFAULT_BUCKET_BATCH_COMMIT_OPTIONS, ...options };
 
-    await this.flush();
+    await this.flush(options);
 
     if (this.last_checkpoint_lsn != null && lsn < this.last_checkpoint_lsn) {
       // When re-applying transactions, don't create a new checkpoint until
       // we are past the last transaction.
-      logger.info(`Re-applied transaction ${lsn} - skipping checkpoint`);
+      this.logger.info(`Re-applied transaction ${lsn} - skipping checkpoint`);
+      // Cannot create a checkpoint yet - return false
       return false;
     }
     if (lsn < this.no_checkpoint_before_lsn) {
       if (Date.now() - this.lastWaitingLogThottled > 5_000) {
-        logger.info(
+        this.logger.info(
           `Waiting until ${this.no_checkpoint_before_lsn} before creating checkpoint, currently at ${lsn}. Persisted op: ${this.persisted_op}`
         );
         this.lastWaitingLogThottled = Date.now();
@@ -647,11 +675,13 @@ export class MongoBucketBatch
         { session: this.session }
       );
 
+      // Cannot create a checkpoint yet - return false
       return false;
     }
 
     if (!createEmptyCheckpoints && this.persisted_op == null) {
-      return false;
+      // Nothing to commit - also return true
+      return true;
     }
 
     const now = new Date();
@@ -673,7 +703,8 @@ export class MongoBucketBatch
         _id: this.group_id
       },
       {
-        $set: update
+        $set: update,
+        $unset: { snapshot_lsn: 1 }
       },
       { session: this.session }
     );
@@ -695,7 +726,7 @@ export class MongoBucketBatch
     if (this.persisted_op != null) {
       // The commit may have been skipped due to "no_checkpoint_before_lsn".
       // Apply it now if relevant
-      logger.info(`Commit due to keepalive at ${lsn} / ${this.persisted_op}`);
+      this.logger.info(`Commit due to keepalive at ${lsn} / ${this.persisted_op}`);
       return await this.commit(lsn);
     }
 
@@ -709,7 +740,8 @@ export class MongoBucketBatch
           snapshot_done: true,
           last_fatal_error: null,
           last_keepalive_ts: new Date()
-        }
+        },
+        $unset: { snapshot_lsn: 1 }
       },
       { session: this.session }
     );
@@ -718,6 +750,22 @@ export class MongoBucketBatch
     return true;
   }
 
+  async setSnapshotLsn(lsn: string): Promise<void> {
+    const update: Partial<SyncRuleDocument> = {
+      snapshot_lsn: lsn
+    };
+
+    await this.db.sync_rules.updateOne(
+      {
+        _id: this.group_id
+      },
+      {
+        $set: update
+      },
+      { session: this.session }
+    );
+  }
+
   async save(record: storage.SaveOptions): Promise<storage.FlushedResult | null> {
     const { after, before, sourceTable, tag } = record;
     for (const event of this.getTableEvents(sourceTable)) {
@@ -742,7 +790,7 @@ export class MongoBucketBatch
       return null;
     }
 
-    logger.debug(`Saving ${record.tag}:${record.before?.id}/${record.after?.id}`);
+    this.logger.debug(`Saving ${record.tag}:${record.before?.id}/${record.after?.id}`);
 
     this.batch ??= new OperationBatch();
     this.batch.push(new RecordOperation(record));
@@ -813,7 +861,7 @@ export class MongoBucketBatch
           session: session
         });
         const batch = await cursor.toArray();
-        const persistedBatch = new PersistedBatch(this.group_id, 0);
+        const persistedBatch = new PersistedBatch(this.group_id, 0, { logger: this.logger });
 
         for (let value of batch) {
           persistedBatch.saveBucketData({
@@ -843,6 +891,37 @@ export class MongoBucketBatch
     return last_op!;
   }
 
+  async updateTableProgress(
+    table: storage.SourceTable,
+    progress: Partial<storage.TableSnapshotStatus>
+  ): Promise<storage.SourceTable> {
+    const copy = table.clone();
+    const snapshotStatus = {
+      totalEstimatedCount: progress.totalEstimatedCount ?? copy.snapshotStatus?.totalEstimatedCount ?? 0,
+      replicatedCount: progress.replicatedCount ?? copy.snapshotStatus?.replicatedCount ?? 0,
+      lastKey: progress.lastKey ?? copy.snapshotStatus?.lastKey ?? null
+    };
+    copy.snapshotStatus = snapshotStatus;
+
+    await this.withTransaction(async () => {
+      await this.db.source_tables.updateOne(
+        { _id: table.id },
+        {
+          $set: {
+            snapshot_status: {
+              last_key: snapshotStatus.lastKey == null ? null : new bson.Binary(snapshotStatus.lastKey),
+              total_estimated_count: snapshotStatus.totalEstimatedCount,
+              replicated_count: snapshotStatus.replicatedCount
+            }
+          }
+        },
+        { session: this.session }
+      );
+    });
+
+    return copy;
+  }
+
   async markSnapshotDone(tables: storage.SourceTable[], no_checkpoint_before_lsn: string) {
     const session = this.session;
     const ids = tables.map((table) => table.id);
@@ -853,6 +932,9 @@ export class MongoBucketBatch
         {
           $set: {
             snapshot_done: true
+          },
+          $unset: {
+            snapshot_status: 1
           }
         },
         { session }
@@ -876,17 +958,8 @@ export class MongoBucketBatch
       }
     });
     return tables.map((table) => {
-      const copy = new storage.SourceTable(
-        table.id,
-        table.connectionTag,
-        table.objectId,
-        table.schema,
-        table.table,
-        table.replicaIdColumns,
-        table.snapshotComplete
-      );
-      copy.syncData = table.syncData;
-      copy.syncParameters = table.syncParameters;
+      const copy = table.clone();
+      copy.snapshotComplete = true;
       return copy;
     });
   }
@@ -895,7 +968,7 @@ export class MongoBucketBatch
    * Gets relevant {@link SqlEventDescriptor}s for the given {@link SourceTable}
    */
   protected getTableEvents(table: storage.SourceTable): SqlEventDescriptor[] {
-    return this.sync_rules.event_descriptors.filter((evt) =>
+    return this.sync_rules.eventDescriptors.filter((evt) =>
       [...evt.getSourceTables()].some((sourceTable) => sourceTable.matches(table))
     );
   }

package/src/storage/implementation/MongoPersistedSyncRulesContent.ts

@@ -15,6 +15,7 @@ export class MongoPersistedSyncRulesContent implements storage.PersistedSyncRule
   public readonly last_fatal_error: string | null;
   public readonly last_keepalive_ts: Date | null;
   public readonly last_checkpoint_ts: Date | null;
+  public readonly active: boolean;
 
   public current_lock: MongoSyncRulesLock | null = null;
 
@@ -30,6 +31,7 @@ export class MongoPersistedSyncRulesContent implements storage.PersistedSyncRule
     this.last_fatal_error = doc.last_fatal_error;
     this.last_checkpoint_ts = doc.last_checkpoint_ts;
     this.last_keepalive_ts = doc.last_keepalive_ts;
+    this.active = doc.state == 'ACTIVE';
   }
 
   parsed(options: storage.ParseSyncRulesOptions) {

package/src/storage/implementation/MongoSyncBucketStorage.ts

@@ -116,9 +116,15 @@ export class MongoSyncBucketStorage
     const doc = await this.db.sync_rules.findOne(
       { _id: this.group_id },
       {
-        projection: { last_checkpoint: 1, last_checkpoint_lsn: 1 }
+        projection: { last_checkpoint: 1, last_checkpoint_lsn: 1, snapshot_done: 1 }
       }
     );
+    if (!doc?.snapshot_done) {
+      return {
+        checkpoint: 0n,
+        lsn: null
+      };
+    }
     return {
       checkpoint: doc?.last_checkpoint ?? 0n,
       lsn: doc?.last_checkpoint_lsn ?? null
@@ -138,6 +144,7 @@ export class MongoSyncBucketStorage
     const checkpoint_lsn = doc?.last_checkpoint_lsn ?? null;
 
     await using batch = new MongoBucketBatch({
+      logger: options.logger,
       db: this.db,
       syncRules: this.sync_rules.parsed(options).sync_rules,
       groupId: this.group_id,
@@ -146,7 +153,8 @@ export class MongoSyncBucketStorage
       noCheckpointBeforeLsn: doc?.no_checkpoint_before ?? options.zeroLSN,
       keepaliveOp: doc?.keepalive_op ? BigInt(doc.keepalive_op) : null,
       storeCurrentData: options.storeCurrentData,
-      skipExistingRows: options.skipExistingRows ?? false
+      skipExistingRows: options.skipExistingRows ?? false,
+      markRecordUnavailable: options.markRecordUnavailable
     });
     this.iterateListeners((cb) => cb.batchStarted?.(batch));
 
@@ -193,7 +201,8 @@ export class MongoSyncBucketStorage
           table_name: table,
           replica_id_columns: null,
           replica_id_columns2: columns,
-          snapshot_done: false
+          snapshot_done: false,
+          snapshot_status: undefined
         };
 
         await col.insertOne(doc, { session });
@@ -210,6 +219,14 @@ export class MongoSyncBucketStorage
       sourceTable.syncEvent = options.sync_rules.tableTriggersEvent(sourceTable);
       sourceTable.syncData = options.sync_rules.tableSyncsData(sourceTable);
       sourceTable.syncParameters = options.sync_rules.tableSyncsParameters(sourceTable);
+      sourceTable.snapshotStatus =
+        doc.snapshot_status == null
+          ? undefined
+          : {
+              lastKey: doc.snapshot_status.last_key?.buffer ?? null,
+              totalEstimatedCount: doc.snapshot_status.total_estimated_count,
+              replicatedCount: doc.snapshot_status.replicated_count
+            };
 
       let dropTables: storage.SourceTable[] = [];
       // Detect tables that are either renamed, or have different replica_id_columns
@@ -521,7 +538,8 @@ export class MongoSyncBucketStorage
         projection: {
           snapshot_done: 1,
           last_checkpoint_lsn: 1,
-          state: 1
+          state: 1,
+          snapshot_lsn: 1
         }
       }
     );
@@ -531,6 +549,7 @@ export class MongoSyncBucketStorage
 
     return {
       snapshot_done: doc.snapshot_done,
+      snapshot_lsn: doc.snapshot_lsn ?? null,
       active: doc.state == 'ACTIVE',
       checkpoint_lsn: doc.last_checkpoint_lsn
     };
@@ -572,6 +591,9 @@ export class MongoSyncBucketStorage
           last_checkpoint_lsn: null,
           last_checkpoint: null,
           no_checkpoint_before: null
+        },
+        $unset: {
+          snapshot_lsn: 1
         }
       },
       { maxTimeMS: lib_mongo.db.MONGO_CLEAR_OPERATION_TIMEOUT_MS }

package/src/storage/implementation/PersistedBatch.ts

@@ -3,7 +3,7 @@ import { JSONBig } from '@powersync/service-jsonbig';
 import { EvaluatedParameters, EvaluatedRow } from '@powersync/service-sync-rules';
 import * as bson from 'bson';
 
-import { logger } from '@powersync/lib-services-framework';
+import { Logger, logger as defaultLogger } from '@powersync/lib-services-framework';
 import { InternalOpId, storage, utils } from '@powersync/service-core';
 import { currentBucketKey, MAX_ROW_SIZE } from './MongoBucketBatch.js';
 import { MongoIdSequence } from './MongoIdSequence.js';
@@ -46,6 +46,7 @@ const MAX_TRANSACTION_DOC_COUNT = 2_000;
  * multiple transactions.
  */
 export class PersistedBatch {
+  logger: Logger;
   bucketData: mongo.AnyBulkWriteOperation<BucketDataDocument>[] = [];
   bucketParameters: mongo.AnyBulkWriteOperation<BucketParameterDocument>[] = [];
   currentData: mongo.AnyBulkWriteOperation<CurrentDataDocument>[] = [];
@@ -63,9 +64,11 @@ export class PersistedBatch {
 
   constructor(
     private group_id: number,
-    writtenSize: number
+    writtenSize: number,
+    options?: { logger?: Logger }
   ) {
     this.currentSize = writtenSize;
+    this.logger = options?.logger ?? defaultLogger;
   }
 
   private incrementBucket(bucket: string, op_id: InternalOpId) {
@@ -107,7 +110,7 @@ export class PersistedBatch {
         // the BSON size is small enough, but the JSON size is too large.
         // In these cases, we can't store the data, so we skip it, or generate a REMOVE operation if the row
         // was synced previously.
-        logger.error(`powersync_${this.group_id} Row ${key} too large: ${recordData.length} bytes. Removing.`);
+        this.logger.error(`Row ${key} too large: ${recordData.length} bytes. Removing.`);
         continue;
       }
 
@@ -206,7 +209,7 @@ export class PersistedBatch {
               k: sourceKey
             },
             lookup: binLookup,
-            bucket_parameters: result.bucket_parameters
+            bucket_parameters: result.bucketParameters
           }
         }
       });
@@ -270,9 +273,11 @@ export class PersistedBatch {
     );
   }
 
-  async flush(db: PowerSyncMongo, session: mongo.ClientSession) {
+  async flush(db: PowerSyncMongo, session: mongo.ClientSession, options?: storage.BucketBatchCommitOptions) {
     const startAt = performance.now();
+    let flushedSomething = false;
     if (this.bucketData.length > 0) {
+      flushedSomething = true;
       await db.bucket_data.bulkWrite(this.bucketData, {
         session,
         // inserts only - order doesn't matter
@@ -280,6 +285,7 @@ export class PersistedBatch {
       });
     }
     if (this.bucketParameters.length > 0) {
+      flushedSomething = true;
       await db.bucket_parameters.bulkWrite(this.bucketParameters, {
         session,
         // inserts only - order doesn't matter
@@ -287,6 +293,7 @@ export class PersistedBatch {
       });
     }
     if (this.currentData.length > 0) {
+      flushedSomething = true;
       await db.current_data.bulkWrite(this.currentData, {
         session,
         // may update and delete data within the same batch - order matters
@@ -295,6 +302,7 @@ export class PersistedBatch {
     }
 
     if (this.bucketStates.size > 0) {
+      flushedSomething = true;
       await db.bucket_state.bulkWrite(this.getBucketStateUpdates(), {
         session,
         // Per-bucket operation - order doesn't matter
@@ -302,12 +310,43 @@ export class PersistedBatch {
       });
     }
 
-    const duration = performance.now() - startAt;
-    logger.info(
-      `powersync_${this.group_id} Flushed ${this.bucketData.length} + ${this.bucketParameters.length} + ${
-        this.currentData.length
-      } updates, ${Math.round(this.currentSize / 1024)}kb in ${duration.toFixed(0)}ms. Last op_id: ${this.debugLastOpId}`
-    );
+    if (flushedSomething) {
+      const duration = Math.round(performance.now() - startAt);
+      if (options?.oldestUncommittedChange != null) {
+        const replicationLag = Math.round((Date.now() - options.oldestUncommittedChange.getTime()) / 1000);
+
+        this.logger.info(
+          `Flushed ${this.bucketData.length} + ${this.bucketParameters.length} + ${
+            this.currentData.length
+          } updates, ${Math.round(this.currentSize / 1024)}kb in ${duration}ms. Last op_id: ${this.debugLastOpId}. Replication lag: ${replicationLag}s`,
+          {
+            flushed: {
+              duration: duration,
+              size: this.currentSize,
+              bucket_data_count: this.bucketData.length,
+              parameter_data_count: this.bucketParameters.length,
+              current_data_count: this.currentData.length,
+              replication_lag_seconds: replicationLag
+            }
+          }
+        );
+      } else {
+        this.logger.info(
+          `Flushed ${this.bucketData.length} + ${this.bucketParameters.length} + ${
+            this.currentData.length
+          } updates, ${Math.round(this.currentSize / 1024)}kb in ${duration}ms. Last op_id: ${this.debugLastOpId}`,
+          {
+            flushed: {
+              duration: duration,
+              size: this.currentSize,
+              bucket_data_count: this.bucketData.length,
+              parameter_data_count: this.bucketParameters.length,
+              current_data_count: this.currentData.length
+            }
+          }
+        );
+      }
+    }
 
     this.bucketData = [];
     this.bucketParameters = [];

package/src/storage/implementation/models.ts

@@ -1,4 +1,4 @@
-import { storage } from '@powersync/service-core';
+import { storage, TableSnapshotStatus } from '@powersync/service-core';
 import { SqliteJsonValue } from '@powersync/service-sync-rules';
 import * as bson from 'bson';
 
@@ -73,6 +73,13 @@ export interface SourceTableDocument {
   replica_id_columns: string[] | null;
   replica_id_columns2: { name: string; type_oid?: number; type?: string }[] | undefined;
   snapshot_done: boolean | undefined;
+  snapshot_status: SourceTableDocumentSnapshotStatus | undefined;
+}
+
+export interface SourceTableDocumentSnapshotStatus {
+  total_estimated_count: number;
+  replicated_count: number;
+  last_key: bson.Binary | null;
 }
 
 /**
@@ -110,6 +117,13 @@ export interface SyncRuleDocument {
    */
   snapshot_done: boolean;
 
+  /**
+   * If snapshot_done = false, this may be the lsn at which we started the snapshot.
+   *
+   * This can be used for resuming the snapshot after a restart.
+   */
+  snapshot_lsn: string | undefined;
+
   /**
    * The last consistent checkpoint.
    *