@powersync/service-module-mongodb 0.0.0-dev-20260803144812 → 0.0.0-dev-20260929095716

package/src/replication/ChangeStream.ts

@@ -27,13 +27,14 @@ import { CheckpointImplementation } from './checkpoints/CheckpointImplementation
 import { createCheckpointImplementation } from './checkpoints/create-checkpoint-implementation.js';
 import { MongoManager } from './MongoManager.js';
 import { getCacheIdentifier, getMongoRelation } from './MongoRelation.js';
-import { MongoSnapshotter, MongoSnapshotterHooks } from './MongoSnapshotter.js';
 import {
-  ChangeStreamBatch,
-  parseChangeDocument,
-  ProjectedChangeStreamDocument,
-  rawChangeStream
-} from './RawChangeStream.js';
+  DEFAULT_MONGO_REPLICATION_QUERY_PROVIDER,
+  MongoReplicationQueryProvider,
+  MongoReplicationQueryProviderFactory
+} from './MongoReplicationQueryProvider.js';
+import { MongoReplicationStreamItem, openMongoReplicationStream } from './MongoReplicationStream.js';
+import { MongoSnapshotter, MongoSnapshotterHooks } from './MongoSnapshotter.js';
+import { ChangeStreamBatch, ProjectedChangeStreamDocument } from './RawChangeStream.js';
 import { CHECKPOINTS_COLLECTION, detectDocumentDb, timestampToDate } from './replication-utils.js';
 import { DirectSourceRowConverter, SourceRowConverter } from './SourceRowConverter.js';
 export interface ChangeStreamOptions {
@@ -61,6 +62,10 @@ export interface ChangeStreamOptions {
 
   storageHooks?: storage.StorageHooks;
   snapshotHooks?: MongoSnapshotterHooks;
+  /**
+   * Create one adapter per replication attempt, shared with its snapshotter and source probes.
+   */
+  createReplicationQueryProvider?: MongoReplicationQueryProviderFactory;
 
   logger?: Logger;
 }
@@ -118,26 +123,45 @@ export class ChangeStream {
   private storageHooks: storage.StorageHooks | undefined;
 
   private readonly sourceRowConverter: SourceRowConverter;
+  private readonly queryProvider: MongoReplicationQueryProvider;
 
   private keepaliveIntervalMs: number;
 
   private isDocumentDb = false;
   private _checkpointImplementation: CheckpointImplementation | null = null;
+  /**
+   * Last persisted resume timestamp as Date.now(). This represents the equivalent timestamp from the
+   * source database, rather than the time when we persisted it.
+   */
+  private lastPersistedResumeTimestamp = 0;
+  private lastBatchCheckpoint = 0;
 
   constructor(options: ChangeStreamOptions) {
     this.storage = options.storage;
     this.metrics = options.metrics;
     this.group_id = options.storage.replicationStreamId;
     this.connections = options.connections;
-    this.maxAwaitTimeMS = options.maxAwaitTimeMS ?? 10_000;
     this.snapshotChunkLength = options.snapshotChunkLength ?? 6_000;
     this.keepaliveIntervalMs = options.keepaliveIntervalMs ?? 60_000;
+    if (options.maxAwaitTimeMS) {
+      this.maxAwaitTimeMS = options.maxAwaitTimeMS;
+    } else {
+      // Default to 10s, unless keepaliveIntervalMs is shorter. In that case, use keepaliveIntervalMs,
+      // but add a bit of a margin, so that our keepalive logic is triggered on each empty change stream batch.
+      this.maxAwaitTimeMS = Math.min(10_000, this.keepaliveIntervalMs + 100);
+    }
     this.storageHooks = options.storageHooks;
     this.client = this.connections.client;
     this.defaultDb = this.connections.db;
     this.sync_rules = options.storage.getParsedSyncRules({
       defaultSchema: this.defaultDb.databaseName
     });
+    this.queryProvider =
+      options.createReplicationQueryProvider?.({
+        syncConfig: this.sync_rules,
+        connectionTag: this.connections.connectionTag,
+        defaultSchema: this.defaultDb.databaseName
+      }) ?? DEFAULT_MONGO_REPLICATION_QUERY_PROVIDER;
     this.sourceRowConverter = new DirectSourceRowConverter(this.sync_rules.compatibility);
 
     // The change stream aggregation command should timeout before the socket times out,
@@ -154,7 +178,8 @@ export class ChangeStream {
       ...options,
       abortSignal: this.abortSignal,
       logger: snapshotLogger,
-      checkpointStreamId: this.checkpointStreamId
+      checkpointStreamId: this.checkpointStreamId,
+      queryProvider: this.queryProvider
     });
 
     options.abort_signal.addEventListener(
@@ -181,7 +206,9 @@ export class ChangeStream {
     return this.connections.options.postImages == PostImagesOption.AUTO_CONFIGURE;
   }
 
-  /** The active checkpoint strategy. Only valid after ensureDetected(). */
+  /**
+   * The active checkpoint strategy. Only valid after ensureDetected().
+   */
   private get checkpointImplementation(): CheckpointImplementation {
     if (this._checkpointImplementation == null) {
       throw new ReplicationAssertionError('Checkpoint implementation not initialized - call ensureDetected() first');
@@ -201,9 +228,10 @@ export class ChangeStream {
     this.isDocumentDb = await detectDocumentDb(this.defaultDb);
     if (this.isDocumentDb) {
       this.logger.warn(
-        'Azure DocumentDB support is experimental. APIs and behavior may change, and long-term stability is not yet guaranteed.'
+        'Azure DocumentDB support is in alpha. APIs and behavior may change, and long-term stability is not yet guaranteed.'
       );
     }
+    await this.queryProvider.validateSource?.({ connectionManager: this.connections, isDocumentDb: this.isDocumentDb });
     this._checkpointImplementation = createCheckpointImplementation(this.isDocumentDb, {
       client: this.client,
       db: this.defaultDb,
@@ -500,7 +528,7 @@ export class ChangeStream {
       if (
         e instanceof mongo.MongoServerError &&
         e.codeName == 'NoMatchingDocument' &&
-        e.errmsg?.includes('post-image was not found')
+        (e.errmsg?.includes('post-image was not found') || e.errmsg?.includes('pre-image was not found'))
       ) {
         throw new ChangeStreamInvalidatedError(e.errmsg, e);
       }
@@ -508,89 +536,32 @@ export class ChangeStream {
     }
   }
 
-  private rawChangeStreamBatches(options: {
+  private openChangeStream(options: {
     lsn: string | null;
     maxAwaitTimeMS?: number;
     batchSize?: number;
     filters: { $match: any; multipleDatabases: boolean };
     signal?: AbortSignal;
     tracer?: PerformanceTracer<'changestream'>;
-  }): AsyncIterableIterator<ChangeStreamBatch> {
-    const position = options.lsn ? this.checkpointImplementation.parseResumePosition(options.lsn) : null;
-    const startAfter = position?.startAfter ?? undefined;
-    const resumeAfter = position?.resumeAfter ?? undefined;
-
-    const filters = options.filters;
-
-    let fullDocument: 'required' | 'updateLookup';
-
-    if (this.isDocumentDb) {
-      // DocumentDB does not support changeStreamPreAndPostImages, so 'required' won't work.
-      fullDocument = 'updateLookup';
-    } else if (this.usePostImages) {
-      // 'read_only' or 'auto_configure'
-      // Configuration happens during snapshot, or when we see new
-      // collections.
-      fullDocument = 'required';
-    } else {
-      fullDocument = 'updateLookup';
-    }
-    const streamOptions: mongo.ChangeStreamOptions & mongo.Document = {
-      fullDocument: fullDocument
-    };
-    if (!this.isDocumentDb) {
-      // DocumentDB does not support showExpandedEvents.
-      streamOptions.showExpandedEvents = true;
-    }
-    const pipeline: mongo.Document[] = [
-      {
-        $changeStream: streamOptions
-      },
-      {
-        $match: filters.$match
+    onBatch?: (batch: ChangeStreamBatch) => Disposable | void;
+  }): AsyncIterableIterator<MongoReplicationStreamItem> {
+    return openMongoReplicationStream({
+      db: this.defaultDb,
+      queryProvider: this.queryProvider,
+      namespaceFilter: options.filters,
+      isDocumentDb: this.isDocumentDb,
+      usePostImages: this.usePostImages,
+      position: options.lsn ? this.checkpointImplementation.parseResumePosition(options.lsn) : null,
+      skipInitialTimestamp: true,
+      onBatch: options.onBatch,
+      options: {
+        batchSize: options.batchSize ?? this.snapshotChunkLength,
+        maxAwaitTimeMS: options.maxAwaitTimeMS ?? this.maxAwaitTimeMS,
+        maxTimeMS: this.changeStreamTimeout,
+        signal: options.signal,
+        logger: this.logger,
+        tracer: options.tracer
       }
-    ];
-    if (!this.isDocumentDb) {
-      // DocumentDB does not support $changeStreamSplitLargeEvent.
-      pipeline.push({ $changeStreamSplitLargeEvent: {} });
-    }
-
-    /**
-     * Only one of these options can be supplied at a time.
-     */
-    if (resumeAfter) {
-      streamOptions.resumeAfter = resumeAfter;
-    } else if (startAfter != null) {
-      // Legacy: We don't persist lsns without resumeTokens anymore, but we do still handle the
-      // case if we have an old one.
-      // This is also relevant for getSnapshotLSN().
-      // The sentinel implementation never produces a startAfter, and a fresh DocumentDB stream
-      // opens from "now" with neither option set.
-      streamOptions.startAtOperationTime = startAfter;
-    }
-
-    let watchDb: mongo.Db;
-    if (this.isDocumentDb || filters.multipleDatabases) {
-      // DocumentDB only supports cluster-level change streams.
-      watchDb = this.client.db('admin');
-      streamOptions.allChangesForCluster = true;
-    } else {
-      watchDb = this.defaultDb;
-    }
-
-    const maxAwaitTimeMS = options.maxAwaitTimeMS ?? this.maxAwaitTimeMS;
-
-    return rawChangeStream(watchDb, pipeline, {
-      batchSize: options.batchSize ?? this.snapshotChunkLength,
-      maxAwaitTimeMS,
-      // maxAwaitTimeMS can be 0 for probe-style streams that do not want an idle wait.
-      // In that case there is no client-side wait to emulate for DocumentDB.
-      clientSideMaxAwaitTimeMS: this.isDocumentDb && maxAwaitTimeMS > 0,
-      maxTimeMS: this.changeStreamTimeout,
-
-      signal: options.signal,
-      logger: this.logger,
-      tracer: options.tracer
     });
   }
 
@@ -598,6 +569,12 @@ export class ChangeStream {
     return this.sourceRowConverter.rawToSqliteRow(row);
   }
 
+  private async createBatchCheckpoint() {
+    const checkpoint = await this.checkpointImplementation.createBatchCheckpoint();
+    this.lastBatchCheckpoint = Date.now();
+    return checkpoint;
+  }
+
   async streamChangesInternal() {
     await this.ensureDetected();
     const transactionsReplicatedMetric = this.metrics.getCounter(ReplicationMetric.TRANSACTIONS_REPLICATED);
@@ -615,6 +592,7 @@ export class ChangeStream {
         // We get a complete postimage for every change, so we don't need to store the current data.
         storeCurrentData: false,
         hooks: this.storageHooks,
+        signal: this.abortSignal,
         tracer
       },
       async (batch) => {
@@ -622,313 +600,260 @@ export class ChangeStream {
         if (resumeFromLsn == null) {
           throw new ReplicationAssertionError(`No LSN found to resume from`);
         }
-        // Seed the implementation's coordinate state from the stored LSN, and parse
-        // the legacy startAfter timestamp (timestamp implementation only) for the
-        // resume-boundary dedupe guard below.
+        // Seed the checkpoint strategy's coordinate from the durable source position.
         this.checkpointImplementation.seedPosition(resumeFromLsn);
-        const { startAfter } = this.checkpointImplementation.parseResumePosition(resumeFromLsn);
         let outerSpan = tracer.span('batch');
 
         this.checkpointImplementation.logResume(resumeFromLsn);
 
         const filters = this.getSourceNamespaceFilters();
         // This is closed when the for loop below returns/breaks/throws
-        const batchStream = this.rawChangeStreamBatches({
+        let processingSpan: ReturnType<typeof tracer.span> | undefined;
+        let receivedBytes = 0;
+        let changesSinceProgress = 0;
+        const stream = this.openChangeStream({
           lsn: resumeFromLsn,
           filters,
           signal: this.abortSignal,
-          tracer
+          tracer,
+          onBatch: (batch) => {
+            // Count actual transport, even if the adapter drops every envelope or reassembles fragments.
+            bytesReplicatedMetric.add(batch.byteSize);
+            chunksReplicatedMetric.add(1);
+            receivedBytes += batch.byteSize;
+            processingSpan = tracer.span('processing');
+            return processingSpan;
+          }
         });
 
         // Always start with a checkpoint.
         // This helps us to clear errors when restarting, even if there is
         // no data to replicate.
-        let waitForCheckpointLsn: string | null = await this.checkpointImplementation.createBatchCheckpoint();
-
-        let splitDocument: ProjectedChangeStreamDocument | null = null;
-
-        let flexDbNameWorkaroundLogged = false;
+        let waitForCheckpointLsn: string | null = await this.createBatchCheckpoint();
 
-        let lastEmptyResume = performance.now();
+        let lastKeepalive = performance.now();
         let lastTxnKey: string | null = null;
 
-        for await (let eventBatch of batchStream) {
-          const { events, resumeToken } = eventBatch;
-          using batchSpan = tracer.span('processing');
-
-          bytesReplicatedMetric.add(eventBatch.byteSize);
-          chunksReplicatedMetric.add(1);
-          if (this.abortSignal.aborted) {
-            break;
-          }
+        for await (const item of stream) {
+          if (this.abortSignal.aborted) break;
           this.touch();
-          if (events.length == 0) {
-            // No changes in this batch, but we still want to keep the connection alive.
-            // We do this by persisting a keepalive checkpoint.
-            // If we don't update it on empty events, we do keep consistency, but resuming the stream
-            // with old tokens may cause connection timeouts.
-            if (waitForCheckpointLsn == null && performance.now() - lastEmptyResume > this.keepaliveIntervalMs) {
-              // The implementation persists a keepalive (timestamp) or bumps the
-              // sentinel so a later event commits (sentinel). Logging is handled
-              // inside the implementation.
-              await this.checkpointImplementation.keepalive(batch, resumeToken);
-              this.touch();
-              lastEmptyResume = performance.now();
-              this.replicationLag.markStarted();
+          if (item.type == 'progress') {
+            const { resumeToken, filteredCount } = item;
+            if (changesSinceProgress == 0) {
+              // No retained changes since the previous progress item: this is either idle or filtered-only traffic.
+              // Case 1: No pending barrier and the keepalive interval has elapsed. Advance checkpoints as below,
+              // then flush and save the resume token.
+              // Case 2: Idle traffic with a recent keepalive. Skip this resume update, whether or not a barrier
+              // is pending, to preserve the idle throttle.
+              // Case 3: All other combinations. Flush and save the resume token without requesting a checkpoint.
+              // A pending barrier will provide the checkpoint boundary once replication reaches it. Filtered
+              // progress still saves its token even during the keepalive interval, so excluded work is resumable.
+              const hadRecentKeepalive = performance.now() - lastKeepalive < this.keepaliveIntervalMs;
+              if (waitForCheckpointLsn == null && !hadRecentKeepalive) {
+                if (filteredCount > 0) {
+                  // Case 1a: A transaction can span batches: this batch may contain only filtered changes,
+                  // while retained changes from the same transaction are still unread. They share a timestamp,
+                  // so publishing a checkpoint here could acknowledge the transaction before its data is saved.
+                  // Request a source barrier; reaching it ensures those retained changes have been processed.
+                  // The progress token can still be saved below for recovery without publishing a checkpoint.
+                  using _ = tracer.span('source_checkpoint');
+                  waitForCheckpointLsn = await this.createBatchCheckpoint();
+                } else {
+                  // Case 1b: Idle traffic. The timestamp implementation persists a keepalive directly;
+                  // the sentinel implementation writes a source marker whose event will commit later.
+                  await this.checkpointImplementation.keepalive(batch, resumeToken);
+                  this.replicationLag.markStarted();
+                }
+                this.touch();
+                lastKeepalive = performance.now();
+              } else if (filteredCount == 0 && hadRecentKeepalive) {
+                // Case 2: Only idle progress skips resume persistence. Cases 1 and 3 fall through below.
+                continue;
+              }
             }
 
-            // If we have no changes, we can just persist the keepalive.
-            // This is throttled to once per interval.
-            if (performance.now() - lastEmptyResume < this.keepaliveIntervalMs) {
-              continue;
-            }
+            const { lsn, timestamp } = this.checkpointImplementation.lsnFromResumeToken(resumeToken);
+            // Row writes must be durable before their source token. This advances recovery without
+            // publishing a checkpoint ahead of an outstanding barrier, transaction or snapshot.
+            await batch.flush({ oldestUncommittedChange: this.replicationLag.oldestUncommittedChange });
+            await batch.setResumeLsn(lsn);
+            // MongoDB's token timestamp may lag by about 10 seconds. DocumentDB tokens have no timestamp.
+            this.lastPersistedResumeTimestamp = timestamp?.getTime() ?? Date.now();
+            processingSpan?.end();
+            const durationsMicroseconds = outerSpan.end();
+            this.logger.info(`Processed ${changesSinceProgress} changes and ${filteredCount} filtered events`, {
+              count: changesSinceProgress,
+              filteredCount,
+              bytes: receivedBytes,
+              duration: processingSpan?.durationMillis,
+              t: durationsMicroseconds
+            });
+            changesSinceProgress = 0;
+            receivedBytes = 0;
+            outerSpan = tracer.span('batch');
+            continue;
           }
 
-          this.touch();
-
-          for (let eventIndex = 0; eventIndex < events.length; eventIndex++) {
-            const rawChangeDocument = events[eventIndex];
-            const originalChangeDocument = parseChangeDocument(rawChangeDocument);
-            if (this.abortSignal.aborted) {
-              break;
+          // The shared reader has already reassembled complete events and normalized their namespaces.
+          const changeDocument = item.event;
+          changesSinceProgress++;
+          const ns = 'ns' in changeDocument && 'coll' in changeDocument.ns ? changeDocument.ns : undefined;
+
+          if (ns?.coll == CHECKPOINTS_COLLECTION) {
+            /**
+             * Dropping the database does not provide an `invalidate` event.
+             * We typically would receive `drop` events for the collection which we
+             * would process below.
+             *
+             * However we don't commit the LSN after collections are dropped.
+             * This prevents the `startAfter` or `resumeToken` from advancing past the drop events.
+             * The stream also closes after the drop events.
+             * This causes an infinite loop of processing the collection drop events.
+             *
+             * This check here invalidates the change stream if our `_powersync_checkpoints` collection
+             * is dropped. This allows for detecting when the DB is dropped.
+             */
+            if (changeDocument.operationType == 'drop') {
+              throw new ChangeStreamInvalidatedError(
+                'Internal collections have been dropped',
+                new Error('_powersync_checkpoints collection was dropped')
+              );
             }
 
-            if (startAfter != null && originalChangeDocument.clusterTime?.lte(startAfter)) {
+            if (
+              !(
+                changeDocument.operationType == 'insert' ||
+                changeDocument.operationType == 'update' ||
+                changeDocument.operationType == 'replace'
+              )
+            ) {
               continue;
             }
 
-            let changeDocument = originalChangeDocument;
-            if (originalChangeDocument?.splitEvent != null) {
-              // Handle split events from $changeStreamSplitLargeEvent.
-              // This is only relevant for very large update operations.
-              const splitEvent = originalChangeDocument?.splitEvent;
+            // We handle two types of checkpoint events:
+            // 1. "Standalone" checkpoints, typically write checkpoints. We want to process these
+            //    immediately, regardless of where they were created.
+            // 2. "Batch" checkpoints for the current stream. This is used as a form of dynamic rate
+            //    limiting of commits, so we specifically want to exclude checkpoints from other streams.
+            //
+            // It may be useful to also throttle commits due to standalone checkpoints in the future.
+            // However, these typically have a much lower rate than batch checkpoints, so we don't do that for now.
 
-              if (splitDocument == null) {
-                splitDocument = originalChangeDocument;
-              } else {
-                splitDocument = Object.assign(splitDocument, originalChangeDocument);
-              }
+            const kind = this.checkpointImplementation.event.observe(changeDocument);
 
-              if (splitEvent.fragment == splitEvent.of) {
-                // Got all fragments
-                changeDocument = splitDocument;
-                splitDocument = null;
-              } else {
-                // Wait for more fragments
+            if (kind == 'foreign') {
+              // Another stream's barrier - ignore.
+              continue;
+            } else if (kind == 'standalone') {
+              // Standalone / write checkpoint received.
+              // When we are caught up, commit immediately to keep write checkpoint latency low.
+              // Once there is already a batch checkpoint pending, or the driver has buffered more
+              // change stream events, collapse standalone checkpoints into the normal batch
+              // checkpoint flow to avoid commit churn under sustained load.
+              const hasBufferedChanges = item.hasBufferedChanges;
+              if (hasBufferedChanges && waitForCheckpointLsn == null) {
+                // Buffered changes - create a new batch checkpoint to rate limit commits
+                using _ = tracer.span('source_checkpoint');
+                waitForCheckpointLsn = await this.createBatchCheckpoint();
+                continue;
+              } else if (waitForCheckpointLsn != null) {
+                // Skip this checkpoint - wait for the batch checkpoint.
                 continue;
+              } else {
+                // No buffered changes, and no batch checkpoint pending - commit immediately.
               }
-            } else if (splitDocument != null) {
-              // We were waiting for fragments, but got a different event
-              throw new ReplicationAssertionError(`Incomplete splitEvent: ${JSON.stringify(splitDocument.splitEvent)}`);
             }
+            // kind == 'own-barrier' falls through to commit.
+
+            const lsn = this.checkpointImplementation.event.lsn(changeDocument);
 
             if (
-              !filters.multipleDatabases &&
-              'ns' in changeDocument &&
-              changeDocument.ns.db != this.defaultDb.databaseName &&
-              changeDocument.ns.db.endsWith(`_${this.defaultDb.databaseName}`)
+              waitForCheckpointLsn != null &&
+              this.checkpointImplementation.event.resolvesBarrier(waitForCheckpointLsn, changeDocument)
             ) {
-              // When all of the following conditions are met:
-              // 1. We're replicating from an Atlas Flex instance.
-              // 2. There were changestream events recorded while the PowerSync service is paused.
-              // 3. We're only replicating from a single database.
-              // Then we've observed an ns with for example {db: '67b83e86cd20730f1e766dde_ps'},
-              // instead of the expected {db: 'ps'}.
-              // We correct this.
-              changeDocument.ns.db = this.defaultDb.databaseName;
-
-              if (!flexDbNameWorkaroundLogged) {
-                flexDbNameWorkaroundLogged = true;
-                this.logger.warn(
-                  `Incorrect DB name in change stream: ${changeDocument.ns.db}. Changed to ${this.defaultDb.databaseName}.`
-                );
-              }
+              waitForCheckpointLsn = null;
             }
+            const { checkpointBlocked, checkpointCreated } = await batch.commit(lsn, {
+              oldestUncommittedChange: this.replicationLag.oldestUncommittedChange
+            });
 
-            const ns = 'ns' in changeDocument && 'coll' in changeDocument.ns ? changeDocument.ns : undefined;
-
-            if (ns?.coll == CHECKPOINTS_COLLECTION) {
-              /**
-               * Dropping the database does not provide an `invalidate` event.
-               * We typically would receive `drop` events for the collection which we
-               * would process below.
-               *
-               * However we don't commit the LSN after collections are dropped.
-               * This prevents the `startAfter` or `resumeToken` from advancing past the drop events.
-               * The stream also closes after the drop events.
-               * This causes an infinite loop of processing the collection drop events.
-               *
-               * This check here invalidates the change stream if our `_powersync_checkpoints` collection
-               * is dropped. This allows for detecting when the DB is dropped.
-               */
-              if (changeDocument.operationType == 'drop') {
-                throw new ChangeStreamInvalidatedError(
-                  'Internal collections have been dropped',
-                  new Error('_powersync_checkpoints collection was dropped')
-                );
-              }
-
-              if (
-                !(
-                  changeDocument.operationType == 'insert' ||
-                  changeDocument.operationType == 'update' ||
-                  changeDocument.operationType == 'replace'
-                )
-              ) {
-                continue;
-              }
-
-              // We handle two types of checkpoint events:
-              // 1. "Standalone" checkpoints, typically write checkpoints. We want to process these
-              //    immediately, regardless of where they were created.
-              // 2. "Batch" checkpoints for the current stream. This is used as a form of dynamic rate
-              //    limiting of commits, so we specifically want to exclude checkpoints from other streams.
-              //
-              // It may be useful to also throttle commits due to standalone checkpoints in the future.
-              // However, these typically have a much lower rate than batch checkpoints, so we don't do that for now.
-
-              const kind = this.checkpointImplementation.event.observe(changeDocument);
-
-              if (kind == 'foreign') {
-                // Another stream's barrier - ignore.
-                continue;
-              } else if (kind == 'standalone') {
-                // Standalone / write checkpoint received.
-                // When we are caught up, commit immediately to keep write checkpoint latency low.
-                // Once there is already a batch checkpoint pending, or the driver has buffered more
-                // change stream events, collapse standalone checkpoints into the normal batch
-                // checkpoint flow to avoid commit churn under sustained load.
-                const hasBufferedChanges = eventIndex < events.length - 1;
-                if (hasBufferedChanges && waitForCheckpointLsn == null) {
-                  // Buffered changes - create a new batch checkpoint to rate limit commits
-                  using _ = tracer.span('source_checkpoint');
-                  waitForCheckpointLsn = await this.checkpointImplementation.createBatchCheckpoint();
-                  continue;
-                } else if (waitForCheckpointLsn != null) {
-                  // Skip this checkpoint - wait for the batch checkpoint.
-                  continue;
-                } else {
-                  // No buffered changes, and no batch checkpoint pending - commit immediately.
-                }
-              }
-              // kind == 'own-barrier' falls through to commit.
-
-              const lsn = this.checkpointImplementation.event.lsn(changeDocument);
+            if (!checkpointBlocked || checkpointCreated) {
+              this.replicationLag.markCommitted();
+            }
+          } else if (
+            changeDocument.operationType == 'insert' ||
+            changeDocument.operationType == 'update' ||
+            changeDocument.operationType == 'replace' ||
+            changeDocument.operationType == 'delete'
+          ) {
+            if (waitForCheckpointLsn == null) {
+              using _ = tracer.span('source_checkpoint');
+              waitForCheckpointLsn = await this.createBatchCheckpoint();
+            }
 
-              if (
-                waitForCheckpointLsn != null &&
-                this.checkpointImplementation.event.resolvesBarrier(waitForCheckpointLsn, changeDocument)
-              ) {
-                waitForCheckpointLsn = null;
+            const rel = getMongoRelation(changeDocument.ns, this.connections.connectionTag);
+            const tables = await this.getRelations(batch, rel, {
+              // In most cases, we should not need to snapshot this. But if this is the first time we see the collection
+              // for whatever reason, then we do need to snapshot it.
+              // This may result in some duplicate operations when a collection is created for the first time after
+              // sync config was deployed.
+              snapshot: true
+            });
+            const tablesToReplicate = tables.filter((table) => table.syncAny);
+            if (tablesToReplicate.length > 0) {
+              this.replicationLag.trackUncommittedChange(
+                // Standard MongoDB uses clusterTime, unchanged. DocumentDB has no
+                // clusterTime, so fall back to wallTime there for the lag metric.
+                changeDocument.clusterTime != null
+                  ? timestampToDate(changeDocument.clusterTime)
+                  : ((changeDocument as any).wallTime ?? null)
+              );
+
+              const transactionKeyValue = transactionKey(changeDocument);
+
+              if (transactionKeyValue == null || lastTxnKey != transactionKeyValue) {
+                // Very crude metric for counting transactions replicated.
+                // We ignore operations other than basic CRUD, and ignore changes to _powersync_checkpoints.
+                // Individual writes may not have a txnNumber, in which case we count them as separate transactions.
+                lastTxnKey = transactionKeyValue;
+                transactionsReplicatedMetric.add(1);
               }
-              const { checkpointBlocked, checkpointCreated } = await batch.commit(lsn, {
-                oldestUncommittedChange: this.replicationLag.oldestUncommittedChange
-              });
 
-              if (!checkpointBlocked || checkpointCreated) {
-                this.replicationLag.markCommitted();
+              for (const table of tablesToReplicate) {
+                await this.writeChange(batch, table, changeDocument);
               }
-            } else if (
-              changeDocument.operationType == 'insert' ||
-              changeDocument.operationType == 'update' ||
-              changeDocument.operationType == 'replace' ||
-              changeDocument.operationType == 'delete'
-            ) {
-              if (waitForCheckpointLsn == null) {
-                using _ = tracer.span('source_checkpoint');
-                waitForCheckpointLsn = await this.checkpointImplementation.createBatchCheckpoint();
-              }
-
-              const rel = getMongoRelation(changeDocument.ns, this.connections.connectionTag);
-              const tables = await this.getRelations(batch, rel, {
-                // In most cases, we should not need to snapshot this. But if this is the first time we see the collection
-                // for whatever reason, then we do need to snapshot it.
-                // This may result in some duplicate operations when a collection is created for the first time after
-                // sync config was deployed.
-                snapshot: true
-              });
-              const tablesToReplicate = tables.filter((table) => table.syncAny);
-              if (tablesToReplicate.length > 0) {
-                this.replicationLag.trackUncommittedChange(
-                  // Standard MongoDB uses clusterTime, unchanged. DocumentDB has no
-                  // clusterTime, so fall back to wallTime there for the lag metric.
-                  changeDocument.clusterTime != null
-                    ? timestampToDate(changeDocument.clusterTime)
-                    : ((changeDocument as any).wallTime ?? null)
-                );
-
-                const transactionKeyValue = transactionKey(changeDocument);
-
-                if (transactionKeyValue == null || lastTxnKey != transactionKeyValue) {
-                  // Very crude metric for counting transactions replicated.
-                  // We ignore operations other than basic CRUD, and ignore changes to _powersync_checkpoints.
-                  // Individual writes may not have a txnNumber, in which case we count them as separate transactions.
-                  lastTxnKey = transactionKeyValue;
-                  transactionsReplicatedMetric.add(1);
-                }
-
-                for (const table of tablesToReplicate) {
-                  await this.writeChange(batch, table, changeDocument);
-                }
-              }
-            } else if (changeDocument.operationType == 'drop') {
-              const rel = getMongoRelation(changeDocument.ns, this.connections.connectionTag);
-              const tables = await this.getRelations(batch, rel, {
-                // We're "dropping" this collection, so never snapshot it.
-                snapshot: false
-              });
-              const tablesToDrop = tables.filter((table) => table.syncAny);
-              if (tablesToDrop.length > 0) {
-                await batch.drop(tablesToDrop);
-              }
-              this.relationCache.delete(rel);
-            } else if (changeDocument.operationType == 'rename') {
-              const relFrom = getMongoRelation(changeDocument.ns, this.connections.connectionTag);
-              const relTo = getMongoRelation(changeDocument.to, this.connections.connectionTag);
-              const tablesFrom = await this.getRelations(batch, relFrom, {
-                // We're "dropping" this collection, so never snapshot it.
-                snapshot: false
-              });
-              const tablesToDrop = tablesFrom.filter((table) => table.syncAny);
-              if (tablesToDrop.length > 0) {
-                await batch.drop(tablesToDrop);
-              }
-              this.relationCache.delete(relFrom);
-              // Here we do need to snapshot the new table
-              const collection = await this.getCollectionInfo(relTo.schema, relTo.name);
-              await this.handleRelation(batch, relTo, {
-                // This is a new (renamed) collection, so always snapshot it.
-                snapshot: true,
-                collectionInfo: collection
-              });
             }
-          }
-
-          if (splitDocument == null) {
-            // We flush and mark progress on every batch of data we receive.
-            // Batches are generally large (64MB or 6000 events, whichever comes first),
-            // so this is a good natural point to flush and mark progress.
-            // We avoid this when splitDocument is set, since we cannot resume in the middle of a split event.
-            const lsn = this.checkpointImplementation.lsnFromResumeToken(resumeToken);
-            await batch.flush({ oldestUncommittedChange: this.replicationLag.oldestUncommittedChange });
-            // TODO: We should consider making this standard behavior of flush().
-            await batch.setResumeLsn(lsn);
-          }
-
-          batchSpan.end();
-          const durationsMicroseconds = outerSpan.end();
-          const duration = batchSpan.durationMillis;
-
-          this.logger.info(
-            `Processed batch of ${events.length} changes / ${eventBatch.byteSize} bytes in ${duration}ms`,
-            {
-              count: events.length,
-              bytes: eventBatch.byteSize,
-              duration,
-              t: durationsMicroseconds
+          } else if (changeDocument.operationType == 'drop') {
+            const rel = getMongoRelation(changeDocument.ns, this.connections.connectionTag);
+            const tables = await this.getRelations(batch, rel, {
+              // We're "dropping" this collection, so never snapshot it.
+              snapshot: false
+            });
+            const tablesToDrop = tables.filter((table) => table.syncAny);
+            if (tablesToDrop.length > 0) {
+              await batch.drop(tablesToDrop);
+            }
+            this.relationCache.delete(rel);
+          } else if (changeDocument.operationType == 'rename') {
+            const relFrom = getMongoRelation(changeDocument.ns, this.connections.connectionTag);
+            const relTo = getMongoRelation(changeDocument.to, this.connections.connectionTag);
+            const tablesFrom = await this.getRelations(batch, relFrom, {
+              // We're "dropping" this collection, so never snapshot it.
+              snapshot: false
+            });
+            const tablesToDrop = tablesFrom.filter((table) => table.syncAny);
+            if (tablesToDrop.length > 0) {
+              await batch.drop(tablesToDrop);
             }
-          );
-          outerSpan = tracer.span('batch');
+            this.relationCache.delete(relFrom);
+            // Here we do need to snapshot the new table
+            const collection = await this.getCollectionInfo(relTo.schema, relTo.name);
+            await this.handleRelation(batch, relTo, {
+              // This is a new (renamed) collection, so always snapshot it.
+              snapshot: true,
+              collectionInfo: collection
+            });
+          }
         }
       }
     );
@@ -940,6 +865,34 @@ export class ChangeStream {
     return this.replicationLag.getLagMillis();
   }
 
+  async keepAlive() {
+    // This is called on an interval of keepaliveIntervalMs.
+
+    // This writes to _powersync_checkpoints.
+    // Main use case: When there are massive bulk writes to another database or collection, the change stream may
+    // start timing out due to reading through too much data in one batch. This breaks up those bulk writes,
+    // allowing the change stream to make progress.
+
+    // When there is low replication traffic, regular calls to setResumeLsn() with recent resume tokens make this unnecessary.
+    // We track that using lastPersistedResumeTimestamp.
+    // We add a bit of a margin here, since setResumeLsn is not called on an exact interval.
+    const staleResumeLsn = Date.now() - this.lastPersistedResumeTimestamp > this.keepaliveIntervalMs * 1.1;
+
+    // When there is replication lag, that resumeToken can get too outdated. In that case, we periodically create a
+    // new back checkpoint. This interval is controlled by the frequency of the keepAlive() call,
+    // while also skipping if there was another call to createBatchCheckpoint().
+    // We use a factor of 0.9 here, to make sure this is called on every keepAlive() interval, unless there
+    // was another call to createBatchCheckpoint().
+    const staleBatchCheckpoint = Date.now() - this.lastBatchCheckpoint > this.keepaliveIntervalMs * 0.9;
+
+    // We don't use oldestUncommittedChange here, since that may be unset in some edge cases where we do need
+    // to persist new checkpoints.
+    if (staleResumeLsn && staleBatchCheckpoint) {
+      await this.ensureDetected();
+      await this.createBatchCheckpoint();
+    }
+  }
+
   private lastTouchedAt = performance.now();
 
   private touch() {