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

package/dist/replication/ChangeStream.js

@@ -7,8 +7,9 @@ import { PostImagesOption } from '../types/types.js';
 import { escapeRegExp } from '../utils.js';
 import { createCheckpointImplementation } from './checkpoints/create-checkpoint-implementation.js';
 import { getCacheIdentifier, getMongoRelation } from './MongoRelation.js';
+import { DEFAULT_MONGO_REPLICATION_QUERY_PROVIDER } from './MongoReplicationQueryProvider.js';
+import { openMongoReplicationStream } from './MongoReplicationStream.js';
 import { MongoSnapshotter } from './MongoSnapshotter.js';
-import { parseChangeDocument, rawChangeStream } from './RawChangeStream.js';
 import { CHECKPOINTS_COLLECTION, detectDocumentDb, timestampToDate } from './replication-utils.js';
 import { DirectSourceRowConverter } from './SourceRowConverter.js';
 /**
@@ -49,23 +50,43 @@ export class ChangeStream {
     changeStreamTimeout;
     storageHooks;
     sourceRowConverter;
+    queryProvider;
     keepaliveIntervalMs;
     isDocumentDb = false;
     _checkpointImplementation = 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.
+     */
+    lastPersistedResumeTimestamp = 0;
+    lastBatchCheckpoint = 0;
     constructor(options) {
         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,
         // so we use 90% of the socket timeout value.
@@ -79,7 +100,8 @@ export class ChangeStream {
             ...options,
             abortSignal: this.abortSignal,
             logger: snapshotLogger,
-            checkpointStreamId: this.checkpointStreamId
+            checkpointStreamId: this.checkpointStreamId,
+            queryProvider: this.queryProvider
         });
         options.abort_signal.addEventListener('abort', () => {
             this.abortController.abort(options.abort_signal.reason);
@@ -97,7 +119,9 @@ export class ChangeStream {
     get configurePostImages() {
         return this.connections.options.postImages == PostImagesOption.AUTO_CONFIGURE;
     }
-    /** The active checkpoint strategy. Only valid after ensureDetected(). */
+    /**
+     * The active checkpoint strategy. Only valid after ensureDetected().
+     */
     get checkpointImplementation() {
         if (this._checkpointImplementation == null) {
             throw new ReplicationAssertionError('Checkpoint implementation not initialized - call ensureDetected() first');
@@ -115,8 +139,9 @@ 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.');
+            this.logger.warn('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,
@@ -377,89 +402,40 @@ export class ChangeStream {
         catch (e) {
             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);
             }
             throw e;
         }
     }
-    rawChangeStreamBatches(options) {
-        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;
-        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 = {
-            fullDocument: fullDocument
-        };
-        if (!this.isDocumentDb) {
-            // DocumentDB does not support showExpandedEvents.
-            streamOptions.showExpandedEvents = true;
-        }
-        const pipeline = [
-            {
-                $changeStream: streamOptions
-            },
-            {
-                $match: filters.$match
+    openChangeStream(options) {
+        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;
-        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
         });
     }
     rawToSqliteRow(row) {
         return this.sourceRowConverter.rawToSqliteRow(row);
     }
+    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);
@@ -473,276 +449,245 @@ 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) => {
             const { resumeFromLsn } = batch;
             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;
+            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 = await this.checkpointImplementation.createBatchCheckpoint();
-            let splitDocument = null;
-            let flexDbNameWorkaroundLogged = false;
-            let lastEmptyResume = performance.now();
+            let waitForCheckpointLsn = await this.createBatchCheckpoint();
+            let lastKeepalive = performance.now();
             let lastTxnKey = 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) {
+            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 we have no changes, we can just persist the keepalive.
-                    // This is throttled to once per interval.
-                    if (performance.now() - lastEmptyResume < this.keepaliveIntervalMs) {
-                        continue;
+                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;
+                        }
                     }
+                    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;
-                        if (splitDocument == null) {
-                            splitDocument = originalChangeDocument;
-                        }
-                        else {
-                            splitDocument = Object.assign(splitDocument, originalChangeDocument);
+                    // 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 = 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;
                         }
-                        if (splitEvent.fragment == splitEvent.of) {
-                            // Got all fragments
-                            changeDocument = splitDocument;
-                            splitDocument = null;
+                        else if (waitForCheckpointLsn != null) {
+                            // Skip this checkpoint - wait for the batch checkpoint.
+                            continue;
                         }
                         else {
-                            // Wait for more fragments
-                            continue;
+                            // 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 (waitForCheckpointLsn != null &&
+                        this.checkpointImplementation.event.resolvesBarrier(waitForCheckpointLsn, changeDocument)) {
+                        waitForCheckpointLsn = null;
                     }
-                    if (!filters.multipleDatabases &&
-                        'ns' in changeDocument &&
-                        changeDocument.ns.db != this.defaultDb.databaseName &&
-                        changeDocument.ns.db.endsWith(`_${this.defaultDb.databaseName}`)) {
-                        // 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}.`);
-                        }
+                    const { checkpointBlocked, checkpointCreated } = await batch.commit(lsn, {
+                        oldestUncommittedChange: this.replicationLag.oldestUncommittedChange
+                    });
+                    if (!checkpointBlocked || checkpointCreated) {
+                        this.replicationLag.markCommitted();
                     }
-                    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 (waitForCheckpointLsn != null &&
-                            this.checkpointImplementation.event.resolvesBarrier(waitForCheckpointLsn, changeDocument)) {
-                            waitForCheckpointLsn = null;
-                        }
-                        const { checkpointBlocked, checkpointCreated } = await batch.commit(lsn, {
-                            oldestUncommittedChange: this.replicationLag.oldestUncommittedChange
-                        });
-                        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();
                     }
-                    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.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 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.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);
+                        for (const table of tablesToReplicate) {
+                            await this.writeChange(batch, table, changeDocument);
                         }
-                        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
-                        });
+                }
+                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);
                 }
-                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);
+                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
+                    });
                 }
-                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
-                });
-                outerSpan = tracer.span('batch');
             }
         });
         throw new ReplicationAbortedError(`Replication stream aborted`, this.abortSignal.reason);
@@ -750,6 +695,29 @@ export class ChangeStream {
     getReplicationLagMillis() {
         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();
+        }
+    }
     lastTouchedAt = performance.now();
     touch() {
         if (performance.now() - this.lastTouchedAt > 1_000) {