@powersync/service-module-mongodb-storage 0.0.0-dev-20260602073133 → 0.0.0-dev-20260909133214

package/src/storage/implementation/v1/MongoParameterCompactorV1.ts

@@ -1,4 +1,5 @@
 import { mongo } from '@powersync/lib-service-mongodb';
+import { bson, InternalOpId } from '@powersync/service-core';
 import { MongoParameterCompactor } from '../MongoParameterCompactor.js';
 import { VersionedPowerSyncMongoV1 } from './VersionedPowerSyncMongoV1.js';
 
@@ -9,18 +10,33 @@ export class MongoParameterCompactorV1 extends MongoParameterCompactor {
     return [this.db.parameterIndexV1 as unknown as mongo.Collection<mongo.Document>];
   }
 
-  protected collectionFilter(): mongo.Document {
-    return {
-      'key.g': this.group_id
-    };
+  // The shared V1 collection is scanned using only its default `_id` index. Filter the stream in
+  // code so compaction does not require an index on `key.g`.
+  protected override shouldCompactDocument(doc: { key: mongo.Document }): boolean {
+    return doc.key.g === this.replicationStreamId;
   }
 
-  protected deleteFilter(doc: mongo.Document): mongo.Document {
+  /**
+   * Uses the legacy `{ 'key.g': 1, lookup: 1, _id: 1 }` index to narrow the stream, lookup and
+   * operation-id range. `key` is not part of that index at all, so it is a residual predicate applied
+   * to every document the range scan returns.
+   *
+   * That scan may therefore have to filter through many keys for the same lookup, but the cost is
+   * amortized: a single scan covers up to 1000 keys, and identities seen again in a later batch skip
+   * the scan entirely - they are deleted by `_id`.
+   *
+   * The V3 storage format uses an index more suitable for this.
+   */
+  protected leadingHistoryDeleteFilter(
+    lookup: bson.Binary,
+    keys: mongo.Document[],
+    before: InternalOpId
+  ): mongo.Document {
     return {
-      'key.g': doc.key.g as number,
-      lookup: doc.lookup,
-      _id: { $lte: doc._id },
-      key: doc.key
+      'key.g': this.replicationStreamId,
+      lookup,
+      key: { $in: keys },
+      _id: { $lt: before }
     };
   }
 }

package/src/storage/implementation/v1/MongoSyncBucketStorageV1.ts

@@ -3,6 +3,8 @@ import { mongo } from '@powersync/lib-service-mongodb';
 import { ServiceAssertionError } from '@powersync/lib-services-framework';
 import {
   CheckpointChanges,
+  CompactInitialReplicationOptions,
+  CompactInitialReplicationResults,
   deserializeParameterLookup,
   GetCheckpointChangesOptions,
   InternalOpId,
@@ -16,19 +18,30 @@ import {
 import { JSONBig } from '@powersync/service-jsonbig';
 import { ParameterLookupRows, ScopedParameterLookup, SqliteJsonRow } from '@powersync/service-sync-rules';
 import * as bson from 'bson';
-import { idPrefixFilter, mapOpEntry, readSingleBatch, setSessionSnapshotTime } from '../../../utils/util.js';
+import {
+  clearCollectionInIdBatches,
+  clearCollectionInIdRanges,
+  idPrefixFilter,
+  mapOpEntry,
+  readSingleBatch,
+  retryOnMongoMaxTimeMSExpired,
+  setSessionSnapshotTime
+} from '../../../utils/util.js';
 import { MongoBucketStorage } from '../../MongoBucketStorage.js';
 import {
-  MongoSyncBucketStorageCheckpoint,
-  MongoSyncBucketStorageContext
-} from '../common/MongoSyncBucketStorageContext.js';
+  MongoGetCheckpointChangesOptions,
+  MongoSyncBucketStorageCheckpoint
+} from '../common/MongoSyncBucketStorageCheckpoint.js';
 import { SourceKey } from '../models.js';
-import { MongoBucketBatchOptions } from '../MongoBucketBatch.js';
 import { MongoChecksums } from '../MongoChecksums.js';
-import { MongoCompactOptions, MongoCompactor } from '../MongoCompactor.js';
+import { MongoCompactOptions } from '../MongoCompactor.js';
 import { MongoParameterCompactor } from '../MongoParameterCompactor.js';
-import { MongoPersistedSyncRulesContentV1 } from '../MongoPersistedSyncRulesContent.js';
-import { MongoSyncBucketStorage, MongoSyncBucketStorageOptions } from '../MongoSyncBucketStorage.js';
+import { MongoPersistedReplicationStream } from '../MongoPersistedReplicationStream.js';
+import {
+  MongoCheckpointState,
+  MongoSyncBucketStorage,
+  MongoSyncBucketStorageOptions
+} from '../MongoSyncBucketStorage.js';
 import {
   BucketDataDocumentV1,
   BucketDataKeyV1,
@@ -42,67 +55,91 @@ import { MongoCompactorV1 } from './MongoCompactorV1.js';
 import { MongoParameterCompactorV1 } from './MongoParameterCompactorV1.js';
 import { VersionedPowerSyncMongoV1 } from './VersionedPowerSyncMongoV1.js';
 
+export interface MongoSyncBucketStorageContextV1 {
+  db: VersionedPowerSyncMongoV1;
+  replicationStreamId: number;
+  readPreference?: mongo.ReadPreference;
+}
+
 export class MongoSyncBucketStorageV1 extends MongoSyncBucketStorage {
-  // Declare types to be more specific
   declare readonly db: VersionedPowerSyncMongoV1;
   declare readonly checksums: MongoChecksumsV1;
 
   constructor(
     factory: MongoBucketStorage,
-    group_id: number,
-    sync_rules: MongoPersistedSyncRulesContentV1,
-    slot_name: string,
+    replicationStreamId: number,
+    replicationStream: MongoPersistedReplicationStream,
+    replicationStreamName: string,
     writeCheckpointMode: storage.WriteCheckpointMode | undefined,
     options: MongoSyncBucketStorageOptions
   ) {
-    super(factory, group_id, sync_rules, slot_name, writeCheckpointMode, options);
+    super(factory, replicationStreamId, replicationStream, replicationStreamName, writeCheckpointMode, options);
   }
 
   protected async initializeVersionStorage(): Promise<void> {}
 
-  protected createWriterImpl(batchOptions: MongoBucketBatchOptions): storage.BucketStorageBatch {
-    return new MongoBucketBatchV1(batchOptions);
-  }
-
-  protected async fetchCheckpointState(
-    session: mongo.ClientSession
-  ): Promise<{ checkpoint: bigint; lsn: string | null } | null> {
+  protected async fetchPersistedOpHead(): Promise<InternalOpId | null> {
     const doc = (await this.db.sync_rules.findOne(
-      { _id: this.group_id },
-      {
-        session,
-        projection: { _id: 1, state: 1, last_checkpoint: 1, last_checkpoint_lsn: 1, snapshot_done: 1 }
-      }
+      { _id: this.replicationStreamId },
+      { projection: { keepalive_op: 1, last_checkpoint: 1 } }
     )) as SyncRuleDocumentV1;
-    if (!doc?.snapshot_done || ![storage.SyncRuleState.ACTIVE, storage.SyncRuleState.ERRORED].includes(doc.state)) {
+    // keepalive_op covers ops not yet in a checkpoint (cleared once checkpointed),
+    // so the head is the max of the two.
+    const keepaliveOp = doc?.keepalive_op == null ? null : BigInt(doc.keepalive_op);
+    const lastCheckpoint = doc?.last_checkpoint ?? null;
+    if (keepaliveOp == null && lastCheckpoint == null) {
       return null;
     }
-    return {
-      checkpoint: doc.last_checkpoint ?? 0n,
-      lsn: doc.last_checkpoint_lsn ?? null
-    };
+    return (keepaliveOp ?? 0n) > (lastCheckpoint ?? 0n) ? keepaliveOp : lastCheckpoint;
   }
 
-  protected async getWriterSyncState() {
+  protected async createWriterImpl(options: storage.CreateWriterOptions): Promise<storage.BucketStorageBatch> {
     const doc = (await this.db.sync_rules.findOne(
       {
-        _id: this.group_id
+        _id: this.replicationStreamId
       },
       { projection: { last_checkpoint_lsn: 1, keepalive_op: 1, snapshot_lsn: 1 } }
     )) as SyncRuleDocumentV1;
-    const checkpointLsn = doc?.last_checkpoint_lsn ?? null;
+
+    return new MongoBucketBatchV1({
+      ...this.writerBatchOptions(options),
+      // Resume from the last consistent checkpoint, or the in-progress snapshot position if it is newer.
+      resumeFromLsn: maxLsn(doc?.last_checkpoint_lsn, doc?.snapshot_lsn),
+      keepaliveOp: doc?.keepalive_op ? BigInt(doc.keepalive_op) : null
+    });
+  }
+
+  protected async fetchCheckpointState(session: mongo.ClientSession): Promise<MongoCheckpointState | null> {
+    const doc = (await this.db.sync_rules.findOne(
+      { _id: this.replicationStreamId },
+      {
+        session,
+        projection: {
+          _id: 1,
+          state: 1,
+          last_checkpoint: 1,
+          last_checkpoint_lsn: 1,
+          snapshot_done: 1,
+          // Must be read in the same snapshot as the checkpoint.
+          'parameter_compaction.checkpoint_changes_invalid_before': 1
+        }
+      }
+    )) as SyncRuleDocumentV1;
+    if (!doc?.snapshot_done || ![storage.SyncRuleState.ACTIVE, storage.SyncRuleState.ERRORED].includes(doc.state)) {
+      return null;
+    }
     return {
-      lastCheckpointLsn: checkpointLsn,
-      resumeFromLsn: maxLsn(checkpointLsn, doc?.snapshot_lsn),
-      keepaliveOp: doc?.keepalive_op ? BigInt(doc.keepalive_op) : null,
-      syncConfigId: null
+      checkpoint: doc.last_checkpoint ?? 0n,
+      lsn: doc.last_checkpoint_lsn ?? null,
+      // Defaults to 0n for streams that have never been compacted.
+      parameterChangesInvalidBefore: doc.parameter_compaction?.checkpoint_changes_invalid_before ?? 0n
     };
   }
 
   protected async terminateSyncRuleState(): Promise<void> {
     await this.db.sync_rules.updateOne(
       {
-        _id: this.group_id
+        _id: this.replicationStreamId
       },
       {
         $set: {
@@ -114,18 +151,16 @@ export class MongoSyncBucketStorageV1 extends MongoSyncBucketStorage {
     );
   }
 
-  protected async getStatusImpl(): Promise<storage.SyncRuleStatus> {
+  protected async getStatusImpl(): Promise<storage.ReplicationStreamStatus> {
     const doc = (await this.db.sync_rules.findOne(
       {
-        _id: this.group_id
+        _id: this.replicationStreamId
       },
       {
         projection: {
           snapshot_done: 1,
           last_checkpoint_lsn: 1,
-          state: 1,
-          snapshot_lsn: 1,
-          keepalive_op: 1
+          snapshot_lsn: 1
         }
       }
     )) as SyncRuleDocumentV1;
@@ -134,18 +169,15 @@ export class MongoSyncBucketStorageV1 extends MongoSyncBucketStorage {
     }
 
     return {
-      snapshot_done: doc.snapshot_done,
-      snapshot_lsn: doc.snapshot_lsn ?? null,
-      active: doc.state == storage.SyncRuleState.ACTIVE,
-      checkpoint_lsn: doc.last_checkpoint_lsn,
-      keepalive_op: doc.keepalive_op == null ? null : BigInt(doc.keepalive_op)
+      snapshotDone: doc.snapshot_done && doc.last_checkpoint_lsn != null,
+      resumeLsn: maxLsn(doc.snapshot_lsn, doc.last_checkpoint_lsn)
     };
   }
 
   protected async clearSyncRuleState(): Promise<void> {
     await this.db.sync_rules.updateOne(
       {
-        _id: this.group_id
+        _id: this.replicationStreamId
       },
       {
         $set: {
@@ -156,7 +188,8 @@ export class MongoSyncBucketStorageV1 extends MongoSyncBucketStorage {
           no_checkpoint_before: null
         },
         $unset: {
-          snapshot_lsn: 1
+          snapshot_lsn: 1,
+          parameter_compaction: 1
         }
       },
       { maxTimeMS: lib_mongo.db.MONGO_CLEAR_OPERATION_TIMEOUT_MS }
@@ -164,29 +197,50 @@ export class MongoSyncBucketStorageV1 extends MongoSyncBucketStorage {
   }
 
   protected createMongoChecksums(options: MongoSyncBucketStorageOptions): MongoChecksums {
-    return new MongoChecksumsV1(this.db, this.group_id, {
+    return new MongoChecksumsV1(this.db, this.replicationStreamId, {
       ...options.checksumOptions,
-      storageConfig: options?.storageConfig,
-      mapping: this.sync_rules.mapping
+      checksumCacheTtlMs: options.checksumCacheTtlMs,
+      storageConfig: options?.storageConfig
     });
   }
 
-  createMongoCompactor(options: MongoCompactOptions): MongoCompactor {
+  createMongoCompactor(options: MongoCompactOptions): MongoCompactorV1 {
     return new MongoCompactorV1(this, this.db, options);
   }
 
+  async compactInitialReplication(
+    options: CompactInitialReplicationOptions
+  ): Promise<CompactInitialReplicationResults> {
+    this.logger.info(`Compacting after initial replication...`);
+    const start = Date.now();
+    const maxOpId = options.maxOpId ?? (await this.fetchPersistedOpHead()) ?? undefined;
+    const compactor = this.createMongoCompactor({
+      ...options,
+      maxOpId,
+      memoryLimitMB: 0,
+      logger: this.logger
+    });
+
+    const result = await compactor.populateChecksums({
+      minBucketChanges: options.minBucketChanges ?? 10
+    });
+    const duration = Date.now() - start;
+    this.logger.info(`Compacted after initial replication in ${(duration / 1000).toFixed(1)}s`);
+    return result;
+  }
+
   protected createMongoParameterCompactor(
     checkpoint: InternalOpId,
     options: storage.CompactOptions
   ): MongoParameterCompactor {
-    return new MongoParameterCompactorV1(this.db, this.group_id, checkpoint, options);
+    return new MongoParameterCompactorV1(this.db, this.replicationStreamId, checkpoint, options);
   }
 
-  protected override get versionContext(): MongoSyncBucketStorageContext<VersionedPowerSyncMongoV1> {
+  protected get versionContext(): MongoSyncBucketStorageContextV1 {
     return {
       db: this.db,
-      group_id: this.group_id,
-      mapping: this.mapping
+      replicationStreamId: this.replicationStreamId,
+      readPreference: this.readPreference
     };
   }
 
@@ -199,7 +253,7 @@ export class MongoSyncBucketStorageV1 extends MongoSyncBucketStorage {
   }
 
   protected getBucketDataBatchImpl(
-    checkpoint: utils.InternalOpId,
+    checkpoint: MongoSyncBucketStorageCheckpoint,
     dataBuckets: storage.BucketDataRequest[],
     options?: storage.BucketDataBatchOptions
   ): AsyncIterable<storage.SyncBucketDataChunk> {
@@ -207,72 +261,77 @@ export class MongoSyncBucketStorageV1 extends MongoSyncBucketStorage {
   }
 
   protected async clearBucketData(signal?: AbortSignal): Promise<void> {
-    await this.clearDeleteMany(
+    await clearCollectionInIdRanges(
+      this.logger,
       'bucket data',
-      () =>
-        this.db.bucket_data.deleteMany(
-          {
-            _id: idPrefixFilter<BucketDataKeyV1>({ g: this.group_id }, ['b', 'o'])
-          },
-          { maxTimeMS: lib_mongo.db.MONGO_CLEAR_OPERATION_TIMEOUT_MS }
-        ),
-      signal
+      this.db.bucket_data,
+      {
+        _id: idPrefixFilter<BucketDataKeyV1>({ g: this.replicationStreamId }, ['b', 'o'])
+      },
+      signal,
+      this.clearBatchThrottleRate
     );
   }
 
   protected async clearParameterIndexes(signal?: AbortSignal): Promise<void> {
-    await this.clearDeleteMany(
+    await clearCollectionInIdBatches(
+      this.logger,
       'parameter index',
-      () =>
-        this.db.parameterIndexV1.deleteMany(
-          {
-            'key.g': this.group_id
-          },
-          { maxTimeMS: lib_mongo.db.MONGO_CLEAR_OPERATION_TIMEOUT_MS }
-        ),
-      signal
+      this.db.parameterIndexV1,
+      {
+        'key.g': this.replicationStreamId
+      },
+      signal,
+      this.clearBatchThrottleRate
     );
   }
 
   protected async clearSourceRecords(signal?: AbortSignal): Promise<void> {
-    await this.clearDeleteMany(
+    await clearCollectionInIdRanges(
+      this.logger,
       'source records',
-      () =>
-        this.db.sourceRecordsV1.deleteMany(
-          {
-            _id: idPrefixFilter<SourceKey>({ g: this.group_id }, ['t', 'k'])
-          },
-          { maxTimeMS: lib_mongo.db.MONGO_CLEAR_OPERATION_TIMEOUT_MS }
-        ),
-      signal
+      this.db.sourceRecordsV1,
+      {
+        _id: idPrefixFilter<SourceKey>({ g: this.replicationStreamId }, ['t', 'k'])
+      },
+      signal,
+      this.clearBatchThrottleRate
     );
   }
 
   protected async clearBucketState(signal?: AbortSignal): Promise<void> {
-    await this.clearDeleteMany(
+    await clearCollectionInIdRanges(
+      this.logger,
       'bucket state',
-      () =>
-        this.db.bucketStateV1.deleteMany(
-          {
-            _id: idPrefixFilter<BucketStateDocument['_id']>({ g: this.group_id }, ['b'])
-          },
-          { maxTimeMS: lib_mongo.db.MONGO_CLEAR_OPERATION_TIMEOUT_MS }
-        ),
-      signal
+      this.db.bucketStateV1,
+      {
+        _id: idPrefixFilter<BucketStateDocument['_id']>({ g: this.replicationStreamId }, ['b'])
+      },
+      signal,
+      this.clearBatchThrottleRate
     );
   }
 
   protected async clearSourceTables(signal?: AbortSignal): Promise<void> {
-    await this.clearDeleteMany(
-      'source tables',
+    await retryOnMongoMaxTimeMSExpired(
       () =>
-        this.db.commonSourceTables(this.group_id).deleteMany(
+        this.db.sourceTablesV1(this.replicationStreamId).deleteMany(
           {
-            group_id: this.group_id
+            group_id: this.replicationStreamId
           },
           { maxTimeMS: lib_mongo.db.MONGO_CLEAR_OPERATION_TIMEOUT_MS }
         ),
-      signal
+      {
+        signal,
+        abortMessage: 'Aborted clearing data',
+        // This is a fairly long delay - only expected to hit this when the storage database is under high load.
+        retryDelayMs: lib_mongo.db.MONGO_CLEAR_OPERATION_TIMEOUT_MS,
+        onRetry: () => {
+          this.logger.info(
+            `Clearing batch of source tables timed out after ${lib_mongo.db.MONGO_CLEAR_OPERATION_TIMEOUT_MS}ms, retrying...`
+          );
+        }
+      }
     );
   }
 
@@ -283,14 +342,14 @@ export class MongoSyncBucketStorageV1 extends MongoSyncBucketStorage {
   }
 
   protected getParameterBucketChangesImpl(
-    options: GetCheckpointChangesOptions
+    options: MongoGetCheckpointChangesOptions
   ): Promise<Pick<CheckpointChanges, 'updatedParameterLookups' | 'invalidateParameterBuckets'>> {
     return getParameterBucketChangesV1(this.versionContext, options);
   }
 }
 
 export async function getParameterSetsV1(
-  ctx: MongoSyncBucketStorageContext<VersionedPowerSyncMongoV1>,
+  ctx: MongoSyncBucketStorageContextV1,
   checkpoint: MongoSyncBucketStorageCheckpoint,
   lookups: ScopedParameterLookup[],
   limit: number
@@ -306,7 +365,7 @@ export async function getParameterSetsV1(
         [
           {
             $match: {
-              'key.g': ctx.group_id,
+              'key.g': ctx.replicationStreamId,
               lookup: { $in: lookupFilter },
               _id: { $lte: checkpoint.checkpoint }
             }
@@ -364,31 +423,44 @@ export async function getParameterSetsV1(
 }
 
 export async function* getBucketDataBatchV1(
-  ctx: MongoSyncBucketStorageContext<VersionedPowerSyncMongoV1>,
-  checkpoint: utils.InternalOpId,
+  ctx: MongoSyncBucketStorageContextV1,
+  checkpoint: MongoSyncBucketStorageCheckpoint,
   dataBuckets: storage.BucketDataRequest[],
   options?: storage.BucketDataBatchOptions
 ): AsyncIterable<storage.SyncBucketDataChunk> {
   if (dataBuckets.length == 0) {
     return;
   }
+  const readPreference = options?.requestHint == 'bulk' ? ctx.readPreference : undefined;
+  const readConcern = ctx.readPreference == null ? undefined : 'majority';
+  const session =
+    readPreference == null || checkpoint.snapshotTime == null
+      ? undefined
+      : ctx.db.client.startSession({ causalConsistency: true });
+  await using _ = { [Symbol.asyncDispose]: async () => session?.endSession() };
+
+  if (session != null) {
+    session.advanceOperationTime(checkpoint.snapshotTime);
+    session.advanceClusterTime(checkpoint.clusterTime);
+  }
+
   let filters: mongo.Filter<BucketDataDocumentV1>[] = [];
   const bucketMap = new Map(dataBuckets.map((request) => [request.bucket, request.start]));
 
-  if (checkpoint == null) {
+  if (checkpoint.checkpoint == null) {
     throw new Error('checkpoint is null');
   }
-  const end = checkpoint;
+  const end = checkpoint.checkpoint;
   for (let { bucket: name, start } of dataBuckets) {
     filters.push({
       _id: {
         $gt: {
-          g: ctx.group_id,
+          g: ctx.replicationStreamId,
           b: name,
           o: start
         },
         $lte: {
-          g: ctx.group_id,
+          g: ctx.replicationStreamId,
           b: name,
           o: end as any
         }
@@ -399,12 +471,16 @@ export async function* getBucketDataBatchV1(
   const batchLimit = options?.limit ?? storage.DEFAULT_DOCUMENT_BATCH_LIMIT;
   const chunkSizeLimitBytes = options?.chunkLimitBytes ?? storage.DEFAULT_DOCUMENT_CHUNK_LIMIT_BYTES;
 
+  // raw: true returns Buffers, but the driver typing doesn't reflect that
+  // without an explicit cast to FindCursor<Buffer>.
   const cursor = ctx.db.bucket_data.find(
     {
       $or: filters
     },
     {
-      session: undefined,
+      session,
+      readPreference,
+      readConcern,
       sort: { _id: 1 },
       limit: batchLimit,
       batchSize: batchLimit + 1,
@@ -481,14 +557,14 @@ export async function* getBucketDataBatchV1(
 }
 
 export async function getDataBucketChangesV1(
-  ctx: MongoSyncBucketStorageContext<VersionedPowerSyncMongoV1>,
+  ctx: MongoSyncBucketStorageContextV1,
   options: GetCheckpointChangesOptions
 ): Promise<Pick<CheckpointChanges, 'updatedDataBuckets' | 'invalidateDataBuckets'>> {
   const limit = 1000;
   const bucketStateUpdates = await ctx.db.bucketStateV1
     .find(
       {
-        '_id.g': ctx.group_id,
+        '_id.g': ctx.replicationStreamId,
         last_op: { $gt: options.lastCheckpoint.checkpoint }
       },
       {
@@ -511,27 +587,48 @@ export async function getDataBucketChangesV1(
   };
 }
 
+/**
+ * Query the parameter entries changed between the two checkpoints, to determine which parameter
+ * lookups need to be re-evaluated.
+ *
+ * This runs at the next checkpoint's snapshot, so it still sees entries that parameter compaction
+ * deleted after that snapshot. Compaction that deleted entries before the snapshot is covered by
+ * the invalidation fence, checked before we get here.
+ */
 export async function getParameterBucketChangesV1(
-  ctx: MongoSyncBucketStorageContext<VersionedPowerSyncMongoV1>,
-  options: GetCheckpointChangesOptions
+  ctx: MongoSyncBucketStorageContextV1,
+  options: MongoGetCheckpointChangesOptions
 ): Promise<Pick<CheckpointChanges, 'updatedParameterLookups' | 'invalidateParameterBuckets'>> {
   const limit = 1000;
-  const parameterUpdates = await ctx.db.parameterIndexV1
-    .find(
-      {
-        _id: { $gt: options.lastCheckpoint.checkpoint, $lte: options.nextCheckpoint.checkpoint },
-        'key.g': ctx.group_id
-      },
-      {
-        projection: {
-          lookup: 1
+  const parameterUpdates = await ctx.db.client.withSession({ snapshot: true }, async (session) => {
+    setSessionSnapshotTime(session, options.nextCheckpoint.snapshotTime);
+    return await ctx.db.parameterIndexV1
+      .find(
+        {
+          _id: { $gt: options.lastCheckpoint.checkpoint, $lte: options.nextCheckpoint.checkpoint },
+          'key.g': ctx.replicationStreamId
         },
-        limit: limit + 1,
-        batchSize: limit + 2,
-        singleBatch: true
-      }
-    )
-    .toArray();
+        {
+          session,
+          readConcern: 'snapshot',
+          projection: {
+            lookup: 1
+          },
+          limit: limit + 1,
+          batchSize: limit + 2,
+          singleBatch: true
+        }
+      )
+      .toArray()
+      .catch((e) => {
+        // Includes the case where the checkpoint snapshot has expired. Degrading to
+        // invalidateParameterBuckets would be safe in itself - it reads nothing - but it gains
+        // nothing: the caller responds to that by re-evaluating the parameter queries at this
+        // same snapshot, which fails too. The checkpoint has to be refetched instead, which is
+        // what the existing sync retry behavior does.
+        throw lib_mongo.mapQueryError(e, 'while querying parameter changes');
+      });
+  });
   const invalidateParameterUpdates = parameterUpdates.length > limit;
 
   return {