@powersync/service-module-mongodb 0.18.1 → 0.19.0

package/test/DOCUMENTDB_TESTING.md

@@ -0,0 +1,115 @@
+# Running Tests Against DocumentDB
+
+These instructions cover running the `module-mongodb` test suite against an Azure DocumentDB (formerly Cosmos DB for MongoDB vCore) cluster.
+
+## Prerequisites
+
+- An Azure DocumentDB (Cosmos DB for MongoDB vCore) cluster with change stream support
+- Local PostgreSQL for PowerSync's internal storage (not the source database)
+- The connection URI for the DocumentDB cluster
+
+> **The open-source `documentdb-local` Docker image cannot be used for these tests.** The
+> open-source DocumentDB engine does not implement change streams (`$changeStream is not
+supported yet in native pipeline`), does not report the `documentdb_versions` `hello` field
+> the suite uses for detection, and presents as `msg: isdbgrid`. An Azure-managed DocumentDB
+> (vCore) cluster is required.
+
+## Environment Variables
+
+DocumentDB is detected automatically from the server: the test suite runs
+`detectDocumentDb()` once at startup (see `DatabaseType.ts`) and gates the
+DocumentDB-specific tests on the result. There is no separate enable flag — pointing
+`MONGO_TEST_DATA_URL` at a DocumentDB cluster is what activates the DocumentDB tests.
+
+| Variable                  | Required | Description                                                                                                                                                              |
+| ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `MONGO_TEST_DATA_URL`     | Yes      | DocumentDB connection URI. Must include a database name in the path (see below). Pointing this at a DocumentDB cluster enables the DocumentDB tests.                     |
+| `PG_STORAGE_TEST_URL`     | No       | PostgreSQL connection for PowerSync storage. Defaults to `postgres://postgres:postgres@localhost:5432/powersync_storage_test`.                                           |
+| `TEST_MONGO_STORAGE`      | No       | Set to `false` to skip MongoDB storage tests. Recommended when testing against DocumentDB to avoid using it as a storage backend.                                        |
+| `TEST_TIMEOUT_MULTIPLIER` | No       | Scale factor `testTimeout()` applies to a default timeout on DocumentDB when no explicit cloud override is given. Defaults to **6**. Increase for a slow/remote cluster. |
+
+### Connection URI format
+
+The `MONGO_TEST_DATA_URL` must include a database name in the path. DocumentDB URIs typically don't have one, so you need to add it before the query string:
+
+```
+# Original URI (no database):
+mongodb+srv://user:pass@cluster.mongocluster.cosmos.azure.com/
+
+# With database added:
+mongodb+srv://user:pass@cluster.mongocluster.cosmos.azure.com/powersync_test
+```
+
+If your password contains special characters (`=`, `@`, `+`, `/`), they must be URL-encoded in the URI (e.g., `=` becomes `%3D`). DocumentDB auto-generated passwords often contain `=` (base64).
+
+## Commands
+
+All commands run from the module directory: `modules/module-mongodb/`
+
+```bash
+# Run all DocumentDB tests (integration + unit helpers):
+MONGO_TEST_DATA_URL="mongodb+srv://user:pass@cluster.mongocluster.cosmos.azure.com/powersync_test" \
+TEST_MONGO_STORAGE=false \
+npx vitest run documentdb --reporter=verbose
+
+# Run only integration tests:
+MONGO_TEST_DATA_URL="<uri>" \
+TEST_MONGO_STORAGE=false \
+npx vitest run documentdb_mode --reporter=verbose
+
+# Run only unit helper tests (no DocumentDB cluster needed):
+npx vitest run documentdb_helpers --reporter=verbose
+
+# Run a specific test by name:
+MONGO_TEST_DATA_URL="<uri>" \
+TEST_MONGO_STORAGE=false \
+npx vitest run documentdb_mode -t "resume after restart" --reporter=verbose
+```
+
+If you have the URI in an environment variable (e.g., `$DOCUMENTDB_URI`), you can construct the test URL inline:
+
+```bash
+DOCUMENTDB_TEST_URL=$(echo "$DOCUMENTDB_URI" | sed 's|\?|powersync_test?|')
+MONGO_TEST_DATA_URL="$DOCUMENTDB_TEST_URL" \
+TEST_MONGO_STORAGE=false \
+npx vitest run documentdb --reporter=verbose
+```
+
+## GitHub Actions
+
+The `.github/workflows/documentdb-integration.yml` workflow runs these tests manually via `workflow_dispatch` only. Add a repository or organization secret named `AZURE_DOCUMENTDB_TEST_DATA_URL`, then dispatch the workflow. The workflow maps that secret to the test suite's `MONGO_TEST_DATA_URL` environment variable.
+
+The URI must include a database name in the path. The tests clear/drop this database as part of setup, so use a dedicated test database and cluster.
+
+The workflow starts a local MongoDB storage service, then runs the complete `modules/module-mongodb` `test` script against that storage backend. `MONGO_TEST_DATA_URL` is the remote DocumentDB source; `MONGO_TEST_URL` points at the local MongoDB storage test instance.
+
+```bash
+TEST_MONGO_STORAGE=true
+TEST_POSTGRES_STORAGE=false
+```
+
+## Test Files
+
+| File                         | Requires DocumentDB       | Description                                                                                                                                                                    |
+| ---------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `documentdb_mode.test.ts`    | Yes                       | Integration tests: replication, sentinel checkpoints, write checkpoints, keepalive, resume. Skipped automatically unless `MONGO_TEST_DATA_URL` points at a DocumentDB cluster. |
+| `documentdb_helpers.test.ts` | No (1 test needs MongoDB) | Unit tests: `getEventTimestamp`, sentinel parsing/matching, detection logic. Runs against any MongoDB or standalone.                                                           |
+
+## What the Integration Tests Cover
+
+Each integration test runs against 3 storage versions (v1, v2, v3) = 15 integration tests. Plus 15 unit tests in helpers = 30 total.
+
+| Test                    | What it validates                                                                               |
+| ----------------------- | ----------------------------------------------------------------------------------------------- |
+| basic replication       | Insert, update, delete through change stream with wallTime timestamps                           |
+| sentinel checkpoint     | Checkpoint created with `mode: 'sentinel'`, resolved by matching document content in the stream |
+| keepalive               | Stream idles past the keepalive interval without crashing on DocumentDB resume tokens           |
+| write checkpoint        | Full `createReplicationHead` → sentinel → polling flow for client write consistency             |
+| data events not dropped | Verifies `.lte()` dedup guard is skipped — events in the same wall-clock second are not lost    |
+| resume after restart    | Stop streaming, create new context, resume from stored token                                    |
+
+There is also a **characterization test**, `does not report collection drop and rename events`,
+that documents the current limitation: it writes DDL plus a post-DDL marker, waits for the marker
+(proving the stream caught up), then asserts no `drop` / `rename` events were delivered. It passes
+today and **fails if a future DocumentDB engine starts delivering DDL events** — a signal to add
+real drop/rename replication support.

package/test/src/DatabaseType.ts

@@ -0,0 +1,25 @@
+import { detectDocumentDb } from '@module/replication/replication-utils.js';
+import { logger } from '@powersync/lib-services-framework';
+import { connectMongoData } from './util.js';
+
+export enum DatabaseType {
+  DOCUMENTDB = 'DOCUMENTDB',
+  MONGODB = 'MONGODB'
+}
+
+let _databaseType: DatabaseType = DatabaseType.MONGODB;
+
+// Detected once at import time. Close the client afterwards so this detection
+// does not leak a connection: this module is imported by many test files, and
+// the client created here is otherwise never closed, accumulating open handles
+// in Vitest.
+const { client, db } = await connectMongoData();
+try {
+  _databaseType = (await detectDocumentDb(db)) ? DatabaseType.DOCUMENTDB : DatabaseType.MONGODB;
+} catch (ex) {
+  logger.warn(`Could not determine MongoDB database type`, ex);
+} finally {
+  await client.close().catch(() => {});
+}
+
+export const DATABASE_TYPE = _databaseType;

package/test/src/change_stream.test.ts

@@ -3,12 +3,14 @@ import { setTimeout } from 'node:timers/promises';
 import { describe, expect, test, vi } from 'vitest';
 
 import { mongo } from '@powersync/lib-service-mongodb';
-import { createWriteCheckpoint, storage } from '@powersync/service-core';
+import { createWriteCheckpoint, storage, WriteCheckpointBatcher } from '@powersync/service-core';
 import { test_utils } from '@powersync/service-core-tests';
 
 import { MongoRouteAPIAdapter } from '@module/api/MongoRouteAPIAdapter.js';
 import { PostImagesOption } from '@module/types/types.js';
 import { ChangeStreamTestContext } from './change_stream_utils.js';
+import { DATABASE_TYPE, DatabaseType } from './DatabaseType.js';
+import { testTimeout } from './test-timeouts.js';
 import { describeWithStorage, StorageVersionTestContext, TEST_CONNECTION_OPTIONS } from './util.js';
 
 const BASIC_SYNC_RULES = `
@@ -19,7 +21,7 @@ bucket_definitions:
 `;
 
 describe('change stream', () => {
-  describeWithStorage({ timeout: 20_000 }, defineChangeStreamTests);
+  describeWithStorage({ timeout: testTimeout(20_000, { cloudOverride: 40_000 }) }, defineChangeStreamTests);
 });
 
 function defineChangeStreamTests({ factory, storageVersion }: StorageVersionTestContext) {
@@ -28,7 +30,8 @@ function defineChangeStreamTests({ factory, storageVersion }: StorageVersionTest
   const openContext = (options?: Parameters<typeof ChangeStreamTestContext.open>[1]) => {
     return ChangeStreamTestContext.open(factory, { ...options, storageVersion });
   };
-  test('replicating basic values', async () => {
+  // DocumentDB does not support changeStreamPreAndPostImages, which this test requires via postImages: READ_ONLY.
+  test.skipIf(DATABASE_TYPE == DatabaseType.DOCUMENTDB)('replicating basic values', async () => {
     await using context = await openContext({
       mongoOptions: { postImages: PostImagesOption.READ_ONLY }
     });
@@ -74,7 +77,10 @@ bucket_definitions:
       - SELECT _id as id, description, num FROM "test_%"`);
 
     await db.createCollection('test_data', {
-      changeStreamPreAndPostImages: { enabled: false }
+      // DocumentDB does not support changeStreamPreAndPostImages, even when
+      // explicitly disabled. This test only needs a collection to exercise
+      // fatal error recovery, so omit the option in DocumentDB mode.
+      ...(DATABASE_TYPE == DatabaseType.MONGODB ? { changeStreamPreAndPostImages: { enabled: false } } : {})
     });
     const collection = db.collection('test_data');
 
@@ -152,7 +158,7 @@ bucket_definitions:
     await context.updateSyncRules(BASIC_SYNC_RULES);
 
     await db.createCollection('test_data', {
-      changeStreamPreAndPostImages: { enabled: false }
+      changeStreamPreAndPostImages: DATABASE_TYPE == DatabaseType.MONGODB ? { enabled: false } : undefined
     });
     testId = new mongo.ObjectId();
     collection = db.collection('test_data');
@@ -167,7 +173,9 @@ bucket_definitions:
     expect(test_utils.reduceBucket(data).slice(1)).toEqual([]);
   });
 
-  test('updateLookup - no fullDocument available', async () => {
+  // DocumentDB always materializes a write-time post-image for updateLookup, so the 'fullDocument unavailable'
+  // case this test exercises (update treated as a remove) cannot occur there.
+  test.skipIf(DATABASE_TYPE == DatabaseType.DOCUMENTDB)('updateLookup - no fullDocument available', async () => {
     await using context = await openContext({
       mongoOptions: { postImages: PostImagesOption.OFF }
     });
@@ -179,6 +187,9 @@ bucket_definitions:
       - SELECT _id as id, description, num FROM "test_data"`);
 
     await db.createCollection('test_data', {
+      // DocumentDB does not support changeStreamPreAndPostImages, even when
+      // explicitly disabled. This test only needs a collection to exercise
+      // fatal error recovery, so omit the option in DocumentDB mode.
       changeStreamPreAndPostImages: { enabled: false }
     });
     const collection = db.collection('test_data');
@@ -211,7 +222,8 @@ bucket_definitions:
     ]);
   });
 
-  test('postImages - autoConfigure', async () => {
+  // DocumentDB does not support changeStreamPreAndPostImages (post-images).
+  test.skipIf(DATABASE_TYPE == DatabaseType.DOCUMENTDB)('postImages - autoConfigure', async () => {
     // Similar to the above test, but with postImages enabled.
     // This resolves the consistency issue.
     await using context = await openContext({
@@ -259,7 +271,8 @@ bucket_definitions:
     ]);
   });
 
-  test('postImages - on', async () => {
+  // DocumentDB does not support changeStreamPreAndPostImages (post-images).
+  test.skipIf(DATABASE_TYPE == DatabaseType.DOCUMENTDB)('postImages - on', async () => {
     // Similar to postImages - autoConfigure, but does not auto-configure.
     // changeStreamPreAndPostImages must be manually configured.
     await using context = await openContext({
@@ -408,7 +421,9 @@ bucket_definitions:
     ]);
   });
 
-  test('replicating dropCollection', async () => {
+  // Collection drop events are not currently replicated on DocumentDB: they are not delivered through the
+  // cluster-level change stream the way standard MongoDB delivers them, so the drop is not applied as a remove.
+  test.skipIf(DATABASE_TYPE == DatabaseType.DOCUMENTDB)('replicating dropCollection', async () => {
     await using context = await openContext();
     const { db } = context;
     const syncRuleContent = `
@@ -440,7 +455,9 @@ bucket_definitions:
     ]);
   });
 
-  test('replicating renameCollection', async () => {
+  // Collection rename events are not currently replicated on DocumentDB: they are not delivered through the
+  // cluster-level change stream the way standard MongoDB delivers them.
+  test.skipIf(DATABASE_TYPE == DatabaseType.DOCUMENTDB)('replicating renameCollection', async () => {
     await using context = await openContext();
     const { db } = context;
     const syncRuleContent = `
@@ -471,7 +488,9 @@ bucket_definitions:
     ]);
   });
 
-  test.runIf(supportsConcurrentSnapshots)(
+  // Concurrent-snapshot regression test driven by collection drop/recreate DDL events, which DocumentDB does
+  // not deliver through the cluster-level change stream the way standard MongoDB does.
+  test.runIf(supportsConcurrentSnapshots && DATABASE_TYPE != DatabaseType.DOCUMENTDB)(
     'collection recreated while queued snapshot is waiting does not stall checkpoints',
     async () => {
       // This is a regression test for a specific timing issue in concurrent snapshot logic.
@@ -625,6 +644,10 @@ bucket_definitions:
       type: 'mongodb',
       ...TEST_CONNECTION_OPTIONS
     });
+    const writeCheckpointBatcher = new WriteCheckpointBatcher(
+      () => api,
+      () => context.factory
+    );
 
     context.startStreaming();
 
@@ -641,8 +664,7 @@ bucket_definitions:
         createWriteCheckpoint({
           userId: 'test_user',
           clientId: 'test_client' + i,
-          api,
-          storage: context.factory
+          batcher: writeCheckpointBatcher
         })
       )
     );
@@ -652,12 +674,14 @@ bucket_definitions:
 
     // We need at least 1 commit.
     expect(commitCount).toBeGreaterThan(0);
-    // The previous implementation greated 1 commit per checkpoint, which is bad for performance.
+    // The previous implementation created 1 commit per checkpoint, which is bad for performance.
     // We expect a small number here - typically 2-10, but allow for anything less than the total number of checkpoints.
     expect(commitCount).toBeLessThan(checkpointCount + 1);
   });
 
-  test('large record', async () => {
+  test
+    // DocumentDBDB does not support changeStreamSplitLargeEvent
+    .skipIf(DATABASE_TYPE == DatabaseType.DOCUMENTDB)('large record', async () => {
     // Test a large update.
 
     // Without $changeStreamSplitLargeEvent, we get this error:
@@ -729,75 +753,83 @@ bucket_definitions:
     expect(data).toMatchObject([]);
   });
 
-  test('postImages - new collection with postImages enabled', async () => {
-    await using context = await openContext({
-      mongoOptions: { postImages: PostImagesOption.AUTO_CONFIGURE }
-    });
-    const { db } = context;
-    await context.updateSyncRules(`
+  // DocumentDB does not support changeStreamPreAndPostImages (post-images).
+  test.skipIf(DATABASE_TYPE == DatabaseType.DOCUMENTDB)(
+    'postImages - new collection with postImages enabled',
+    async () => {
+      await using context = await openContext({
+        mongoOptions: { postImages: PostImagesOption.AUTO_CONFIGURE }
+      });
+      const { db } = context;
+      await context.updateSyncRules(`
 bucket_definitions:
   global:
     data:
       - SELECT _id as id, description FROM "test_%"`);
 
-    await context.replicateSnapshot();
+      await context.replicateSnapshot();
 
-    await db.createCollection('test_data', {
-      // enabled: true here - everything should work
-      changeStreamPreAndPostImages: { enabled: true }
-    });
-    const collection = db.collection('test_data');
-    const result = await collection.insertOne({ description: 'test1' });
-    const test_id = result.insertedId;
-    await collection.updateOne({ _id: test_id }, { $set: { description: 'test2' } });
+      await db.createCollection('test_data', {
+        // enabled: true here - everything should work
+        changeStreamPreAndPostImages: { enabled: true }
+      });
+      const collection = db.collection('test_data');
+      const result = await collection.insertOne({ description: 'test1' });
+      const test_id = result.insertedId;
+      await collection.updateOne({ _id: test_id }, { $set: { description: 'test2' } });
 
-    context.startStreaming();
+      context.startStreaming();
 
-    const data = await context.getBucketData('global[]');
-    if (data.length == 3) {
-      expect(data).toMatchObject([
-        // An extra op here, since this triggers a snapshot in addition to getting the event.
-        test_utils.putOp('test_data', { id: test_id!.toHexString(), description: 'test2' }),
-        test_utils.putOp('test_data', { id: test_id!.toHexString(), description: 'test1' }),
-        test_utils.putOp('test_data', { id: test_id!.toHexString(), description: 'test2' })
-      ]);
-    } else {
-      expect(data).toMatchObject([
-        test_utils.putOp('test_data', { id: test_id!.toHexString(), description: 'test1' }),
-        test_utils.putOp('test_data', { id: test_id!.toHexString(), description: 'test2' })
-      ]);
+      const data = await context.getBucketData('global[]');
+      if (data.length == 3) {
+        expect(data).toMatchObject([
+          // An extra op here, since this triggers a snapshot in addition to getting the event.
+          test_utils.putOp('test_data', { id: test_id!.toHexString(), description: 'test2' }),
+          test_utils.putOp('test_data', { id: test_id!.toHexString(), description: 'test1' }),
+          test_utils.putOp('test_data', { id: test_id!.toHexString(), description: 'test2' })
+        ]);
+      } else {
+        expect(data).toMatchObject([
+          test_utils.putOp('test_data', { id: test_id!.toHexString(), description: 'test1' }),
+          test_utils.putOp('test_data', { id: test_id!.toHexString(), description: 'test2' })
+        ]);
+      }
     }
-  });
+  );
 
-  test('postImages - new collection with postImages disabled', async () => {
-    await using context = await openContext({
-      mongoOptions: { postImages: PostImagesOption.AUTO_CONFIGURE }
-    });
-    const { db } = context;
-    await context.updateSyncRules(`
+  // DocumentDB does not support changeStreamPreAndPostImages (post-images).
+  test.skipIf(DATABASE_TYPE == DatabaseType.DOCUMENTDB)(
+    'postImages - new collection with postImages disabled',
+    async () => {
+      await using context = await openContext({
+        mongoOptions: { postImages: PostImagesOption.AUTO_CONFIGURE }
+      });
+      const { db } = context;
+      await context.updateSyncRules(`
 bucket_definitions:
   global:
     data:
       - SELECT _id as id, description FROM "test_data%"`);
 
-    await context.replicateSnapshot();
+      await context.replicateSnapshot();
 
-    await db.createCollection('test_data', {
-      // enabled: false here, but autoConfigure will enable it.
-      // Unfortunately, that is too late, and replication must be restarted.
-      changeStreamPreAndPostImages: { enabled: false }
-    });
-    const collection = db.collection('test_data');
-    const result = await collection.insertOne({ description: 'test1' });
-    const test_id = result.insertedId;
-    await collection.updateOne({ _id: test_id }, { $set: { description: 'test2' } });
+      await db.createCollection('test_data', {
+        // enabled: false here, but autoConfigure will enable it.
+        // Unfortunately, that is too late, and replication must be restarted.
+        changeStreamPreAndPostImages: { enabled: false }
+      });
+      const collection = db.collection('test_data');
+      const result = await collection.insertOne({ description: 'test1' });
+      const test_id = result.insertedId;
+      await collection.updateOne({ _id: test_id }, { $set: { description: 'test2' } });
 
-    context.startStreaming();
+      context.startStreaming();
 
-    await expect(() => context.getBucketData('global[]')).rejects.toMatchObject({
-      message: expect.stringContaining('stream was configured to require a post-image for all update events')
-    });
-  });
+      await expect(() => context.getBucketData('global[]')).rejects.toMatchObject({
+        message: expect.stringContaining('stream was configured to require a post-image for all update events')
+      });
+    }
+  );
 
   test('recover from error', async () => {
     await using context = await openContext();
@@ -809,7 +841,10 @@ bucket_definitions:
       - SELECT _id as id, description, num FROM "test_data"`);
 
     await db.createCollection('test_data', {
-      changeStreamPreAndPostImages: { enabled: false }
+      // DocumentDB does not support changeStreamPreAndPostImages, even when
+      // explicitly disabled. This test only needs a collection to exercise
+      // fatal error recovery, so omit the option in DocumentDB mode.
+      changeStreamPreAndPostImages: DATABASE_TYPE == DatabaseType.MONGODB ? { enabled: false } : undefined
     });
 
     const collection = db.collection('test_data');
@@ -834,7 +869,7 @@ bucket_definitions:
         const error = (await syncRules?.getSyncConfigStatus())?.last_fatal_error;
         return error == null;
       },
-      { timeout: 2_000 }
+      { timeout: testTimeout(2_000, { cloudOverride: 5_000 }) }
     );
   });
 }

package/test/src/change_stream_utils.ts

@@ -19,9 +19,15 @@ import {
 } from '@powersync/service-core';
 import { bucketRequest, METRICS_HELPER, test_utils } from '@powersync/service-core-tests';
 
+import { SentinelLSN } from '@module/common/SentinelLSN.js';
 import { ChangeStream, ChangeStreamOptions } from '@module/replication/ChangeStream.js';
 import { MongoManager } from '@module/replication/MongoManager.js';
-import { createCheckpoint, STANDALONE_CHECKPOINT_ID } from '@module/replication/MongoRelation.js';
+import {
+  createCheckpoint,
+  createSentinelCheckpointLsn,
+  STANDALONE_CHECKPOINT_ID
+} from '@module/replication/MongoRelation.js';
+import { detectDocumentDb } from '@module/replication/replication-utils.js';
 import { NormalizedMongoConnectionConfig } from '@module/types/types.js';
 
 import { clearTestDb, TEST_CONNECTION_OPTIONS } from './util.js';
@@ -46,6 +52,11 @@ export class ChangeStreamTestContext {
       storageVersion?: number;
       mongoOptions?: Partial<NormalizedMongoConnectionConfig>;
       streamOptions?: Partial<ChangeStreamOptions>;
+      /**
+       * Optional override for tests that need to force a mode. By default the
+       * test context detects DocumentDB from the hello response.
+       */
+      documentDbMode?: boolean;
     }
   ) {
     const f = await factory({ doNotClear: options?.doNotClear });
@@ -56,15 +67,17 @@ export class ChangeStreamTestContext {
     }
 
     const storageVersion = options?.storageVersion ?? LEGACY_STORAGE_VERSION;
+    const documentDbMode = options?.documentDbMode ?? (await detectDocumentDb(connectionManager.db));
 
-    return new ChangeStreamTestContext(f, connectionManager, options?.streamOptions, storageVersion);
+    return new ChangeStreamTestContext(f, connectionManager, options?.streamOptions, storageVersion, documentDbMode);
   }
 
   constructor(
     public factory: BucketStorageFactory,
     public connectionManager: MongoManager,
     private streamOptions: Partial<ChangeStreamOptions> = {},
-    private storageVersion: number = LEGACY_STORAGE_VERSION
+    private storageVersion: number = LEGACY_STORAGE_VERSION,
+    private documentDbMode: boolean = false
   ) {
     createCoreReplicationMetrics(METRICS_HELPER.metricsEngine);
     initializeCoreReplicationMetrics(METRICS_HELPER.metricsEngine);
@@ -120,6 +133,17 @@ export class ChangeStreamTestContext {
     return this.storage!;
   }
 
+  async loadActiveSyncRules() {
+    const syncConfig = await this.factory.getActiveSyncConfig();
+    if (syncConfig == null) {
+      throw new Error(`Active sync config not found`);
+    }
+
+    this.syncRulesContent = syncConfig.content;
+    this.storage = syncConfig.storage;
+    return this.storage!;
+  }
+
   private getSyncConfigContent(): storage.PersistedSyncConfigContent {
     if (this.syncRulesContent == null) {
       throw new Error('Sync config not configured - call updateSyncRules() first');
@@ -143,6 +167,7 @@ export class ChangeStreamTestContext {
       // a long time to abort the stream.
       maxAwaitTimeMS: this.streamOptions?.maxAwaitTimeMS ?? 200,
       snapshotChunkLength: this.streamOptions?.snapshotChunkLength,
+      keepaliveIntervalMs: this.streamOptions?.keepaliveIntervalMs,
       storageHooks: this.streamOptions?.storageHooks,
       snapshotHooks: this.streamOptions?.snapshotHooks,
       logger: this.streamOptions?.logger
@@ -170,7 +195,24 @@ export class ChangeStreamTestContext {
    * would result in inconsistent data.
    */
   async markSnapshotConsistent() {
-    const checkpoint = await createCheckpoint(this.client, this.db, STANDALONE_CHECKPOINT_ID);
+    let checkpoint: string;
+    if (this.documentDbMode) {
+      const sentinelCheckpoint = SentinelLSN.fromSerialized(await createSentinelCheckpointLsn(this.client, this.db));
+      const status = await this.storage!.getStatus();
+      const resumeFrom = status.resumeLsn;
+      const resumeToken = resumeFrom ? SentinelLSN.fromSerialized(resumeFrom).resumeToken : null;
+
+      // This helper artificially marks the snapshot as consistent without
+      // waiting for the stream to observe the sentinel. Keep the sentinel as the
+      // comparable position, but carry forward the existing snapshot resume
+      // token so later DocumentDB streaming still resumes from a real token.
+      checkpoint = new SentinelLSN({
+        sentinel: sentinelCheckpoint.sentinel,
+        resume_token: resumeToken
+      }).comparable;
+    } else {
+      checkpoint = await createCheckpoint(this.db, STANDALONE_CHECKPOINT_ID);
+    }
 
     await using writer = await this.storage!.createWriter(test_utils.BATCH_OPTIONS);
     await writer.keepalive(checkpoint);
@@ -203,12 +245,29 @@ export class ChangeStreamTestContext {
   }
 
   async getBucketData(bucket: string, start?: ProtocolOpId | InternalOpId | undefined, options?: { timeout?: number }) {
+    const checkpoint = await this.getCheckpoint(options);
+    return this.getBucketDataAtCheckpoint(bucket, checkpoint, start);
+  }
+
+  async getBucketDataAtLatestCheckpoint(bucket: string, start?: ProtocolOpId | InternalOpId | undefined) {
+    if (this.storage == null) {
+      throw new Error('updateSyncRules() first');
+    }
+
+    const checkpoint = await this.storage.getCheckpoint();
+    return this.getBucketDataAtCheckpoint(bucket, checkpoint, start);
+  }
+
+  async getBucketDataAtCheckpoint(
+    bucket: string,
+    checkpoint: ReplicationCheckpoint,
+    start?: ProtocolOpId | InternalOpId | undefined
+  ) {
     start ??= 0n;
     if (typeof start == 'string') {
       start = BigInt(start);
     }
     const syncConfigContent = this.getSyncConfigContent();
-    const checkpoint = await this.getCheckpoint(options);
     let map = [bucketRequest(syncConfigContent, bucket, start)];
     let data: OplogEntry[] = [];
     while (true) {
@@ -247,14 +306,25 @@ export async function getClientCheckpoint(
   client: mongo.MongoClient,
   db: mongo.Db,
   storageFactory: BucketStorageFactory,
-  options?: { timeout?: number }
-): Promise<InternalOpId> {
+  options?: { timeout?: number; documentDbMode?: boolean; storage?: SyncRulesBucketStorage }
+): Promise<ReplicationCheckpoint> {
   const start = Date.now();
-  const lsn = await createCheckpoint(client, db, STANDALONE_CHECKPOINT_ID);
+  const documentDbMode = options?.documentDbMode ?? (await detectDocumentDb(db));
+
+  const lsn = documentDbMode
+    ? await createSentinelCheckpointLsn(client, db)
+    : await createCheckpoint(db, STANDALONE_CHECKPOINT_ID);
   // This old API needs a persisted checkpoint id.
   // Since we don't use LSNs anymore, the only way to get that is to wait.
 
   const timeout = options?.timeout ?? 50_000;
+  // DocumentDB: the streaming loop skips standalone checkpoint events while a
+  // batch barrier is pending (see ChangeStream.ts), so a single sentinel bump
+  // can be missed on an idle stream with no later event to advance the
+  // checkpoint. Periodically re-bump the sentinel so a standalone event
+  // eventually commits past `lsn`, mirroring getSnapshotLsn's retry loop.
+  const NUDGE_INTERVAL_MS = 1000;
+  let lastNudge = Date.now();
   let lastCp: ReplicationCheckpoint | null = null;
 
   while (Date.now() - start < timeout) {
@@ -263,9 +333,15 @@ export async function getClientCheckpoint(
     if (cp != null) {
       lastCp = cp;
       if (cp.lsn && cp.lsn >= lsn) {
-        return cp.checkpoint;
+        return cp;
       }
     }
+
+    if (documentDbMode && Date.now() - lastNudge >= NUDGE_INTERVAL_MS) {
+      await createSentinelCheckpointLsn(client, db);
+      lastNudge = Date.now();
+    }
+
     await new Promise((resolve) => setTimeout(resolve, 30));
   }
 

package/test/src/checkpoint_retry.test.ts

@@ -4,9 +4,12 @@ import { mongo } from '@powersync/lib-service-mongodb';
 
 import { MongoLSN } from '@module/common/MongoLSN.js';
 import { createCheckpoint } from '@module/replication/MongoRelation.js';
+import { DATABASE_TYPE, DatabaseType } from './DatabaseType.js';
 import { clearTestDb, connectMongoData, requireFailCommand } from './util.js';
 
-describe('checkpoint retryable writes', () => {
+// This suite uses configureFailPoint to force retry timing. Azure DocumentDB
+// does not support configureFailPoint.
+describe.skipIf(DATABASE_TYPE == DatabaseType.DOCUMENTDB)('checkpoint retryable writes', () => {
   test('returns the persisted checkpoint clusterTime after a retryable write', { repeats: 1 }, async (ctx) => {
     // This test relies on very specific timing:
     //
@@ -75,7 +78,7 @@ describe('checkpoint retryable writes', () => {
         blockTimeMS: TIMEOUT
       }
     });
-    const returnedLsnPromise = createCheckpoint(client, db, checkpointId);
+    const returnedLsnPromise = createCheckpoint(db, checkpointId);
 
     for (let i = 0; i < INSERT_COUNT; i++) {
       await advanceClusterTime.insertOne({ at: new Date() });