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

package/test/src/replication_stream.test.ts

@@ -0,0 +1,311 @@
+import { ChangeStreamInvalidatedError } from '@module/replication/ChangeStream.js';
+import { DEFAULT_MONGO_REPLICATION_QUERY_PROVIDER } from '@module/replication/MongoReplicationQueryProvider.js';
+import { openMongoReplicationStream, readMongoReplicationStream } from '@module/replication/MongoReplicationStream.js';
+import { ChangeStreamBatch, mapChangeStreamError } from '@module/replication/RawChangeStream.js';
+import { mongo } from '@powersync/lib-service-mongodb';
+import { DatabaseConnectionError } from '@powersync/lib-services-framework';
+import { describe, expect, test, vi } from 'vitest';
+import { env } from './env.js';
+
+/**
+ * Exercise cursor construction and stream decoding without contacting MongoDB. Cursor tests intercept
+ * the driver's command method; reader tests supply BSON batches with explicit events and resume tokens.
+ */
+describe('MongoDB replication stream reader', () => {
+  test.each(['pre', 'post'])('invalidates replication when a required %s-image is missing', (image) => {
+    const error = new mongo.MongoServerError({
+      code: 47,
+      codeName: 'NoMatchingDocument',
+      errmsg: `Change stream was configured to require a ${image}-image, but the ${image}-image was not found for event: example`
+    });
+
+    // Invalidated streams trigger a fresh snapshot instead of retrying an unrecoverable position.
+    expect(() => mapChangeStreamError(error)).toThrow(ChangeStreamInvalidatedError);
+  });
+
+  test('does not invalidate replication for unrelated NoMatchingDocument errors', () => {
+    const error = new mongo.MongoServerError({
+      code: 47,
+      codeName: 'NoMatchingDocument',
+      errmsg: 'No matching document found'
+    });
+
+    expect(() => mapChangeStreamError(error)).toThrow(DatabaseConnectionError);
+  });
+
+  test.each([
+    { isDocumentDb: false, multipleDatabases: false, usePostImages: false },
+    { isDocumentDb: false, multipleDatabases: false, usePostImages: true },
+    { isDocumentDb: false, multipleDatabases: true, usePostImages: true },
+    { isDocumentDb: true, multipleDatabases: false, usePostImages: true }
+  ])('preserves the base cursor options for %j', async ({ isDocumentDb, multipleDatabases, usePostImages }) => {
+    const client = new mongo.MongoClient(env.MONGO_TEST_DATA_URL);
+    await using clientDisposer = { [Symbol.asyncDispose]: () => client.close() };
+    const db = client.db('app');
+    const resumeAfter = { _data: 'exact-position' };
+    // Observe the real cursor-opening path, stopping before any network operation. An exact token must
+    // take precedence even if the stored position also contains its transaction's shared timestamp.
+    const command = vi.spyOn(mongo.Db.prototype, 'command').mockRejectedValue(new Error('observed command'));
+    try {
+      await expect(
+        collect(
+          openMongoReplicationStream({
+            db,
+            queryProvider: DEFAULT_MONGO_REPLICATION_QUERY_PROVIDER,
+            namespaceFilter: { $match: { 'ns.coll': 'documents' }, multipleDatabases },
+            isDocumentDb,
+            usePostImages,
+            position: { resumeAfter, startAfter: new mongo.Timestamp({ t: 10, i: 1 }) },
+            skipInitialTimestamp: true,
+            options: { batchSize: 50, maxAwaitTimeMS: 200, maxTimeMS: 1000 }
+          })
+        )
+      ).rejects.toThrow('observed command');
+      expect(command).toHaveBeenCalledOnce();
+      expect((command.mock.contexts[0] as mongo.Db).databaseName).toBe(
+        isDocumentDb || multipleDatabases ? 'admin' : 'app'
+      );
+      expect(command.mock.calls[0][0]).toEqual({
+        aggregate: 1,
+        pipeline: [
+          {
+            $changeStream: {
+              fullDocument: !isDocumentDb && usePostImages ? 'required' : 'updateLookup',
+              ...(!isDocumentDb ? { showExpandedEvents: true } : {}),
+              ...(isDocumentDb || multipleDatabases ? { allChangesForCluster: true } : {}),
+              resumeAfter
+            }
+          },
+          { $match: { 'ns.coll': 'documents' } },
+          ...(!isDocumentDb ? [{ $changeStreamSplitLargeEvent: {} }] : [])
+        ],
+        cursor: { batchSize: 1 },
+        maxTimeMS: 1000
+      });
+    } finally {
+      command.mockRestore();
+    }
+  });
+
+  test('opens adapter stages after namespace selection, with pre-images and the shared resume settings', async () => {
+    // A provider requests pre-images and adds a stage. The shared opener must still supply the source
+    // position and post-image settings, and run the provider stage before large events are split.
+    const client = new mongo.MongoClient(env.MONGO_TEST_DATA_URL);
+    await using clientDisposer = { [Symbol.asyncDispose]: () => client.close() };
+    const command = vi.spyOn(mongo.Db.prototype, 'command').mockRejectedValue(new Error('observed command'));
+    const timestamp = new mongo.Timestamp({ t: 10, i: 1 });
+    try {
+      await expect(
+        collect(
+          openMongoReplicationStream({
+            db: client.db('app'),
+            queryProvider: {
+              ...DEFAULT_MONGO_REPLICATION_QUERY_PROVIDER,
+              openChangeStream: ({ open }) =>
+                open({
+                  pipelineStages: [{ $set: { marker: 'keep' } }],
+                  imageOptions: { fullDocumentBeforeChange: 'whenAvailable' }
+                })
+            },
+            namespaceFilter: { $match: { 'ns.coll': 'documents' }, multipleDatabases: false },
+            isDocumentDb: false,
+            usePostImages: true,
+            position: { startAfter: timestamp },
+            options: { batchSize: 50, maxAwaitTimeMS: 200, maxTimeMS: 1000 }
+          })
+        )
+      ).rejects.toThrow('observed command');
+      expect(command.mock.calls[0][0].pipeline).toEqual([
+        {
+          $changeStream: {
+            fullDocumentBeforeChange: 'whenAvailable',
+            fullDocument: 'required',
+            showExpandedEvents: true,
+            startAtOperationTime: timestamp
+          }
+        },
+        { $match: { 'ns.coll': 'documents' } },
+        { $set: { marker: 'keep' } },
+        { $changeStreamSplitLargeEvent: {} }
+      ]);
+    } finally {
+      command.mockRestore();
+    }
+  });
+
+  test('keeps raw rows, buffered checkpoint information and idle progress', async () => {
+    // Two changes arrive together, followed by an empty response. Preserve raw BSON document bodies
+    // and indicate whether another change is buffered, while exposing a resume boundary for each batch.
+    const onBatch = vi.fn();
+    const batches = [batch([event('first'), event('second')], 'data'), batch([], 'idle')];
+    const items = await collect(
+      readMongoReplicationStream({
+        batches: from(batches),
+        defaultSchema: 'app',
+        multipleDatabases: false,
+        onBatch
+      })
+    );
+    expect(items.map((item) => item.type)).toEqual(['change', 'change', 'progress', 'progress']);
+    expect(items[0]).toMatchObject({ type: 'change', hasBufferedChanges: true });
+    expect(items[1]).toMatchObject({ type: 'change', hasBufferedChanges: false });
+    if (items[0].type != 'change' || !('fullDocument' in items[0].event)) throw new Error('Expected a row');
+    expect(Buffer.isBuffer(items[0].event.fullDocument)).toBe(true);
+    expect(mongo.BSON.deserialize(items[0].event.fullDocument!)).toEqual({ _id: 'first', body: 'raw row' });
+    expect(items.slice(2)).toEqual([
+      { type: 'progress', resumeToken: { _data: 'data' }, filteredCount: 0 },
+      { type: 'progress', resumeToken: { _data: 'idle' }, filteredCount: 0 }
+    ]);
+    expect(onBatch.mock.calls.map(([value]) => value)).toEqual(batches);
+  });
+
+  test('withholds progress across split batches, including an idle response between fragments', async () => {
+    // A large event spans two nonempty batches with an idle response between them. Saving either
+    // intermediate token would lose the in-memory first fragment if replication restarted there.
+    const original = event('large');
+    const first = { ...original, fullDocument: undefined, splitEvent: { fragment: 1, of: 2 } };
+    const last = {
+      _id: { _data: 'fragment-2' },
+      fullDocument: original.fullDocument,
+      splitEvent: { fragment: 2, of: 2 }
+    };
+    const onBatch = vi.fn();
+    const items = await collect(
+      readMongoReplicationStream({
+        batches: from([
+          batch([event('before'), first], 'unsafe'),
+          batch([], 'still-unsafe'),
+          batch([last, event('after')], 'safe')
+        ]),
+        defaultSchema: 'app',
+        multipleDatabases: false,
+        onBatch
+      })
+    );
+    // A consumer must never save either partial token, even though all three transport batches are counted.
+    expect(items.map((item) => item.type)).toEqual(['change', 'change', 'change', 'progress']);
+    expect(items[1]).toMatchObject({
+      type: 'change',
+      event: { documentKey: { _id: 'large' }, _id: { _data: 'fragment-2' } }
+    });
+    expect(items[3]).toEqual({ type: 'progress', resumeToken: { _data: 'safe' }, filteredCount: 0 });
+    expect(onBatch).toHaveBeenCalledTimes(3);
+  });
+
+  test.each([
+    // The first fragment is missing.
+    [{ ...event('broken'), splitEvent: { fragment: 2, of: 2 } }],
+    // A fragment in the middle is missing.
+    [
+      { ...event('broken'), splitEvent: { fragment: 1, of: 3 } },
+      { _id: { _data: 'bad' }, splitEvent: { fragment: 3, of: 3 } }
+    ],
+    // An ordinary event interrupts reassembly.
+    [{ ...event('broken'), splitEvent: { fragment: 1, of: 2 } }, event('unrelated')],
+    // The source iterator ends before the final fragment arrives.
+    [{ ...event('broken'), splitEvent: { fragment: 1, of: 2 } }]
+  ])('fails closed on incomplete or out-of-order fragments %#', async (...events) => {
+    // Invalid fragment sequences must reject consumption and close the upstream iterator so a caller
+    // cannot mistake a partial document for a complete change or continue from its batch token.
+    const closed = vi.fn();
+    const stream = readMongoReplicationStream({
+      batches: from([batch(events, 'unsafe')], closed),
+      defaultSchema: 'app',
+      multipleDatabases: false
+    });
+    await expect(collect(stream)).rejects.toThrow('splitEvent');
+    expect(closed).toHaveBeenCalledOnce();
+  });
+
+  test.each(['return', 'abort'] as const)(
+    'closes the upstream iterator on %s without acknowledging unread work',
+    async (end) => {
+      // Stop after the first change while another remains in the same batch. Both consumer return
+      // and signal cancellation must run upstream cleanup before the batch's progress is yielded.
+      const closed = vi.fn();
+      const controller = new AbortController();
+      const stream = readMongoReplicationStream({
+        batches: from([batch([event('first'), event('unread')], 'unsafe')], closed),
+        defaultSchema: 'app',
+        multipleDatabases: false,
+        signal: controller.signal
+      });
+      expect((await stream.next()).value).toMatchObject({ type: 'change' });
+      if (end == 'return') await stream.return(undefined);
+      else {
+        controller.abort(new Error('cancelled'));
+        await expect(stream.next()).rejects.toThrow('cancelled');
+      }
+      expect(closed).toHaveBeenCalledOnce();
+    }
+  );
+
+  test('normalizes Atlas Flex namespaces and deduplicates legacy positions before adapter evaluation', async () => {
+    // Legacy positions contain only a timestamp, so an event at that timestamp is already covered.
+    // The remaining event uses an Atlas Flex database prefix that must be removed before delivery.
+    const timestamp = new mongo.Timestamp({ t: 10, i: 1 });
+    const items = await collect(
+      readMongoReplicationStream({
+        batches: from([
+          batch(
+            [
+              { ...event('old'), clusterTime: timestamp },
+              { ...event('new'), ns: { db: 'prefix_app', coll: 'documents' } }
+            ],
+            'safe'
+          )
+        ]),
+        defaultSchema: 'app',
+        multipleDatabases: false,
+        startAfter: timestamp
+      })
+    );
+    expect(items).toHaveLength(2);
+    expect(items[0]).toMatchObject({
+      type: 'change',
+      event: { ns: { db: 'app', coll: 'documents' }, documentKey: { _id: 'new' } }
+    });
+  });
+});
+
+/**
+ * Minimal insert event for the app.documents fixture namespace; callers override fields for each scenario.
+ */
+function event(id: string): mongo.Document {
+  return {
+    _id: { _data: id },
+    operationType: 'insert',
+    ns: { db: 'app', coll: 'documents' },
+    documentKey: { _id: id },
+    fullDocument: { _id: id, body: 'raw row' }
+  };
+}
+
+/**
+ * Encode events as raw BSON, matching the reader's transport input. Tokens are opaque test labels;
+ * the fixed byte count supports batch accounting assertions without depending on BSON payload size.
+ */
+function batch(events: mongo.Document[], token: string): ChangeStreamBatch {
+  return {
+    events: events.map((event) => Buffer.from(mongo.BSON.serialize(event))),
+    resumeToken: { _data: token },
+    byteSize: 1234
+  };
+}
+
+/**
+ * Supply deterministic source batches and expose iterator cleanup to cancellation and failure tests.
+ */
+async function* from<T>(values: T[], closed?: () => void) {
+  try {
+    yield* values;
+  } finally {
+    closed?.();
+  }
+}
+
+async function collect<T>(stream: AsyncIterable<T>): Promise<T[]> {
+  const items: T[] = [];
+  for await (const item of stream) items.push(item);
+  return items;
+}

package/test/src/resume.test.ts

@@ -1,8 +1,9 @@
 import { ChangeStreamInvalidatedError } from '@module/replication/ChangeStream.js';
 import { MongoManager } from '@module/replication/MongoManager.js';
 import { normalizeConnectionConfig } from '@module/types/types.js';
+import { METRICS_HELPER } from '@powersync/service-core-tests';
 import { describe, expect, test } from 'vitest';
-import { ChangeStreamTestContext } from './change_stream_utils.js';
+import { ChangeStreamTestContext, openChangeStreamTestContext } from './change_stream_test_setup.js';
 import { env } from './env.js';
 import { describeWithStorage, StorageVersionTestContext } from './util.js';
 
@@ -11,8 +12,8 @@ describe('mongodb resuming replication', () => {
 });
 
 function defineResumeTest({ factory: factoryGenerator, storageVersion }: StorageVersionTestContext) {
-  const openContext = (options?: Parameters<typeof ChangeStreamTestContext.open>[1]) => {
-    return ChangeStreamTestContext.open(factoryGenerator, { ...options, storageVersion });
+  const openContext = (options?: Parameters<typeof openChangeStreamTestContext>[1]) => {
+    return openChangeStreamTestContext(factoryGenerator, { ...options, storageVersion });
   };
 
   test.skip('resuming with a different source database', async () => {
@@ -66,7 +67,12 @@ function defineResumeTest({ factory: factoryGenerator, storageVersion }: Storage
     const factory = await factoryGenerator({ doNotClear: true });
 
     // Create a new context without updating the sync config
-    await using context2 = new ChangeStreamTestContext(factory, connectionManager, {}, storageVersion);
+    await using context2 = new ChangeStreamTestContext({
+      factory,
+      connectionManager,
+      storageVersion,
+      metrics: METRICS_HELPER.metricsEngine
+    });
     const active = await factory.getActiveSyncConfig();
     context2.storage = active!.storage;
 

package/test/src/resuming_snapshots.test.ts

@@ -3,7 +3,7 @@ import { METRICS_HELPER } from '@powersync/service-core-tests';
 import { ReplicationMetric } from '@powersync/service-types';
 import * as timers from 'node:timers/promises';
 import { describe, expect, test } from 'vitest';
-import { ChangeStreamTestContext } from './change_stream_utils.js';
+import { openChangeStreamTestContext } from './change_stream_test_setup.js';
 import { env } from './env.js';
 import { describeWithStorage } from './util.js';
 
@@ -35,7 +35,7 @@ async function testResumingReplication(factory: TestStorageFactory, storageVersi
   let startRowCount: number;
 
   {
-    await using context = await ChangeStreamTestContext.open(factory, {
+    await using context = await openChangeStreamTestContext(factory, {
       storageVersion,
       streamOptions: { snapshotChunkLength: 1000 }
     });
@@ -88,7 +88,7 @@ async function testResumingReplication(factory: TestStorageFactory, storageVersi
 
   {
     // Bypass the usual "clear db on factory open" step.
-    await using context2 = await ChangeStreamTestContext.open(factory, {
+    await using context2 = await openChangeStreamTestContext(factory, {
       doNotClear: true,
       storageVersion,
       streamOptions: { snapshotChunkLength: 1000 }

package/test/src/schema.test.ts

@@ -0,0 +1,223 @@
+import { mongo } from '@powersync/lib-service-mongodb';
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+
+import { inferCollectionSchema } from '@module/api/infer-collection-schema.js';
+import { MongoRouteAPIAdapter } from '@module/api/MongoRouteAPIAdapter.js';
+import { DATABASE_TYPE, DatabaseType } from './DatabaseType.js';
+import { testTimeout } from './test-timeouts.js';
+import { connectMongoData, requireFailCommand, TEST_CONNECTION_OPTIONS } from './util.js';
+
+const isDocumentDb = DATABASE_TYPE == DatabaseType.DOCUMENTDB;
+
+describe('collection schema inference', { timeout: testTimeout(20_000) }, () => {
+  let client: mongo.MongoClient;
+  let db: mongo.Db;
+
+  beforeEach(async () => {
+    ({ client } = await connectMongoData({ monitorCommands: true }));
+    db = client.db(`${TEST_CONNECTION_OPTIONS.database}_schema`);
+    await db.dropDatabase();
+  });
+
+  afterEach(async () => {
+    await db.dropDatabase();
+    await client.close();
+  });
+
+  test('merges types across documents and only infers top-level fields', async () => {
+    const collection = db.collection('mixed');
+    await collection.insertMany([
+      {
+        _id: 1 as any,
+        value: null,
+        whole: new mongo.Double(42),
+        huge: new mongo.Double(1e100),
+        fractional: new mongo.Double(-1.25),
+        nan: NaN,
+        positiveInfinity: Infinity,
+        negativeInfinity: -Infinity,
+        long: mongo.Long.fromString('9007199254740993'),
+        array: [{ nested: 'value' }],
+        object: { nested: true }
+      },
+      { _id: 2 as any, value: 'text', whole: new mongo.Int32(-42), array: [] },
+      { _id: 3 as any, value: 42, whole: new mongo.Double(-0) },
+      { _id: 4 as any, value: 1.25 },
+      { _id: 5 as any, value: new mongo.Double(42) }
+    ]);
+
+    expect(await inferCollectionSchema(collection, isDocumentDb)).toMatchObject([
+      { name: '_id', sqlite_type: 4, internal_type: 'Integer' },
+      { name: 'array', sqlite_type: 2, internal_type: 'Array' },
+      { name: 'fractional', sqlite_type: 8, internal_type: 'Double' },
+      { name: 'huge', sqlite_type: 4, internal_type: 'Integer' },
+      { name: 'long', sqlite_type: 4, internal_type: 'Long' },
+      { name: 'nan', sqlite_type: 8, internal_type: 'Double' },
+      { name: 'negativeInfinity', sqlite_type: 8, internal_type: 'Double' },
+      { name: 'object', sqlite_type: 2, internal_type: 'Object' },
+      { name: 'positiveInfinity', sqlite_type: 8, internal_type: 'Double' },
+      { name: 'value', sqlite_type: 14, internal_type: 'Double | Integer | Null | String' },
+      { name: 'whole', sqlite_type: 4, internal_type: 'Integer' }
+    ]);
+  });
+
+  test('distinguishes UUIDs from binary values by subtype and length', async () => {
+    const collection = db.collection('binary');
+    await collection.insertMany([
+      {
+        _id: 1 as any,
+        uuid: new mongo.UUID('00000000-0000-0000-0000-000000000000'),
+        binary: new mongo.Binary(Buffer.alloc(16)),
+        mixed: new mongo.UUID()
+      },
+      {
+        _id: 2 as any,
+        uuid: new mongo.UUID('ffffffff-ffff-ffff-ffff-ffffffffffff'),
+        binary: new mongo.Binary(Buffer.alloc(16, 255)),
+        mixed: new mongo.Binary(Buffer.alloc(16), mongo.Binary.SUBTYPE_UUID_OLD)
+      },
+      {
+        _id: 3 as any,
+        uuid: new mongo.UUID(),
+        binary: new mongo.Binary(Buffer.alloc(16), mongo.Binary.SUBTYPE_MD5)
+      },
+      { _id: 4 as any, binary: new mongo.Binary(Buffer.alloc(15, 255), mongo.Binary.SUBTYPE_USER_DEFINED) },
+      { _id: 5 as any, binary: new mongo.Binary(Buffer.alloc(17)) },
+      { _id: 6 as any, binary: new mongo.Binary(Buffer.alloc(0)) }
+    ]);
+
+    expect(await inferCollectionSchema(collection, isDocumentDb)).toMatchObject([
+      { name: '_id', sqlite_type: 4, internal_type: 'Integer' },
+      { name: 'binary', sqlite_type: 1, internal_type: 'Binary' },
+      { name: 'mixed', sqlite_type: 3, internal_type: 'Binary | UUID' },
+      { name: 'uuid', sqlite_type: 2, internal_type: 'UUID' }
+    ]);
+  });
+
+  test('handles empty collections and documents with only an id', async () => {
+    const collection = await db.createCollection('empty');
+    expect(await inferCollectionSchema(collection, isDocumentDb)).toEqual([]);
+
+    await collection.insertOne({});
+    expect(await inferCollectionSchema(collection, isDocumentDb)).toEqual([
+      { name: '_id', sqlite_type: 2, type: 'ObjectId', internal_type: 'ObjectId', pg_type: 'ObjectId' }
+    ]);
+  });
+
+  test.skipIf(DATABASE_TYPE == DatabaseType.DOCUMENTDB)(
+    'preserves field names with a non-simple collation',
+    async () => {
+      const collection = await db.createCollection('collation', { collation: { locale: 'en', strength: 1 } });
+      await collection.insertOne({ Name: 'text', name: 1, 'with.dot': true, $field: [] });
+
+      const columns = await inferCollectionSchema(collection, isDocumentDb);
+      expect(columns).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({ name: 'Name', sqlite_type: 2 }),
+          expect.objectContaining({ name: 'name', sqlite_type: 4 }),
+          expect.objectContaining({ name: 'with.dot', sqlite_type: 4 }),
+          expect.objectContaining({ name: '$field', internal_type: 'Array' })
+        ])
+      );
+      expect(columns).toHaveLength(5);
+    }
+  );
+
+  test('returns only small schema metadata for multi-megabyte documents', async () => {
+    const collection = db.collection('large');
+    const largeString = 'x'.repeat(2 * 1024 * 1024);
+    for (let i = 0; i < 4; i++) {
+      await collection.insertOne({ text: largeString, binary: Buffer.alloc(2 * 1024 * 1024), array: [largeString] });
+    }
+
+    const responseSizes: number[] = [];
+    const executionLimits: number[] = [];
+    client.on('commandStarted', (event: mongo.CommandStartedEvent) => {
+      if (event.commandName == 'aggregate') {
+        executionLimits.push(event.command.maxTimeMS);
+      }
+    });
+    client.on('commandSucceeded', (event: mongo.CommandSucceededEvent) => {
+      if (event.commandName == 'aggregate' || event.commandName == 'getMore') {
+        responseSizes.push(mongo.BSON.calculateObjectSize(event.reply as mongo.Document));
+      }
+    });
+
+    expect(await inferCollectionSchema(collection, isDocumentDb)).toMatchObject([
+      { name: '_id', sqlite_type: 2, internal_type: 'ObjectId' },
+      { name: 'array', sqlite_type: 2, internal_type: 'Array' },
+      { name: 'binary', sqlite_type: 1, internal_type: 'Binary' },
+      { name: 'text', sqlite_type: 2, internal_type: 'String' }
+    ]);
+    expect(responseSizes.length).toBeGreaterThan(0);
+    expect(Math.max(...responseSizes)).toBeLessThan(4096);
+    expect(executionLimits).toEqual([30_000]);
+  });
+
+  // A collection we cannot sample should cost us that collection's fields, not the whole schema.
+  // Exercises the real server/driver error path without waiting for the limits to be reached.
+  describe.skipIf(DATABASE_TYPE == DatabaseType.DOCUMENTDB)('when a collection cannot be sampled', () => {
+    // 146 is ExceededMemoryLimit, 292 is QueryExceededMemoryLimitNoDiskUseAllowed, which is what
+    // a small collection of multi-megabyte documents produces when $sample has to sort them.
+    // The namespace filter below needs a server recent enough to honor it (CI runs 6.0+);
+    // older servers ignore it and fail an arbitrary collection's aggregation.
+    test.for([146, 292])('reports it without columns on error %i', async (errorCode, ctx) => {
+      await db.collection('readable').insertOne({ value: 'text' });
+      await db.collection('unreadable').insertOne({ value: 'text' });
+      await using adapter = new MongoRouteAPIAdapter({
+        type: 'mongodb',
+        ...TEST_CONNECTION_OPTIONS,
+        database: db.databaseName
+      });
+      await using failCommand = await requireFailCommand(client, ctx);
+      await failCommand.configure({
+        mode: { times: 1 },
+        data: {
+          failCommands: ['aggregate'],
+          namespace: `${db.databaseName}.unreadable`,
+          errorCode
+        }
+      });
+
+      const schema = await adapter.getConnectionSchema();
+      const tables = schema.find((s) => s.name == db.databaseName)?.tables;
+
+      expect(tables).toEqual(
+        expect.arrayContaining([
+          { name: 'unreadable', columns: [] },
+          expect.objectContaining({
+            name: 'readable',
+            columns: expect.arrayContaining([expect.objectContaining({ name: 'value' })])
+          })
+        ])
+      );
+    });
+
+    // 2 is BadValue, standing in for any unexpected error. 50 is MaxTimeMSExpired: timeouts
+    // usually mean the source is overloaded rather than one problem collection, so they keep
+    // failing the request instead of silently degrading every collection.
+    // Neither is retryable, so the driver surfaces them without re-running the aggregation.
+    test.for([2, 50])('still fails the request on error %i', async (errorCode, ctx) => {
+      await db.collection('broken').insertOne({ value: 'text' });
+      await using adapter = new MongoRouteAPIAdapter({
+        type: 'mongodb',
+        ...TEST_CONNECTION_OPTIONS,
+        database: db.databaseName
+      });
+      await using failCommand = await requireFailCommand(client, ctx);
+      await failCommand.configure({
+        mode: { times: 1 },
+        data: {
+          failCommands: ['aggregate'],
+          namespace: `${db.databaseName}.broken`,
+          errorCode
+        }
+      });
+
+      await expect(adapter.getConnectionSchema()).rejects.toMatchObject({
+        name: 'MongoServerError',
+        code: errorCode
+      });
+    });
+  });
+});

package/test/src/slow_tests.test.ts

@@ -2,7 +2,7 @@ import { setTimeout } from 'node:timers/promises';
 import { describe, expect, test } from 'vitest';
 
 import { mongo } from '@powersync/lib-service-mongodb';
-import { ChangeStreamTestContext, setSnapshotHistorySeconds } from './change_stream_utils.js';
+import { openChangeStreamTestContext, setSnapshotHistorySeconds } from './change_stream_test_setup.js';
 import { DATABASE_TYPE, DatabaseType } from './DatabaseType.js';
 import { env } from './env.js';
 import { describeWithStorage, StorageVersionTestContext } from './util.js';
@@ -12,8 +12,8 @@ describe.runIf(env.CI || env.SLOW_TESTS)('change stream slow tests', { timeout:
 });
 
 function defineSlowTests({ factory, storageVersion }: StorageVersionTestContext) {
-  const openContext = (options?: Parameters<typeof ChangeStreamTestContext.open>[1]) => {
-    return ChangeStreamTestContext.open(factory, { ...options, storageVersion });
+  const openContext = (options?: Parameters<typeof openChangeStreamTestContext>[1]) => {
+    return openChangeStreamTestContext(factory, { ...options, storageVersion });
   };
 
   // This test uses getParameter/setParameter for minSnapshotHistoryWindowInSeconds,