@powersync/service-module-mongodb-storage 0.20.0 → 0.22.0

package/src/storage/implementation/MongoStorageProvider.ts

@@ -1,7 +1,11 @@
 import * as lib_mongo from '@powersync/lib-service-mongodb';
 import { ErrorCode, logger, ServiceAssertionError, ServiceError } from '@powersync/lib-services-framework';
 import { POWERSYNC_VERSION, storage } from '@powersync/service-core';
-import { MongoStorageConfig, normalizeClearBatchThrottleRate } from '../../types/types.js';
+import {
+  MongoStorageConfig,
+  normalizeChunkCompactionConcurrency,
+  normalizeClearBatchThrottleRate
+} from '../../types/types.js';
 import { MongoBucketStorage } from '../MongoBucketStorage.js';
 import { MongoReportStorage } from '../MongoReportStorage.js';
 import { PowerSyncMongo } from './db.js';
@@ -24,6 +28,10 @@ export class MongoStorageProvider implements storage.StorageProvider {
     }
 
     const decodedConfig = MongoStorageConfig.decode(storage as any);
+    const chunkCompactionConcurrency = normalizeChunkCompactionConcurrency(
+      decodedConfig.chunk_compaction_concurrency,
+      decodedConfig.object_storage != null
+    );
 
     let objectStorage: ObjectStorage | undefined;
     if (decodedConfig.object_storage?.type === 's3') {
@@ -37,7 +45,8 @@ export class MongoStorageProvider implements storage.StorageProvider {
         forcePathStyle: decodedConfig.object_storage.force_path_style,
         accessKeyId: decodedConfig.object_storage.access_key_id,
         secretAccessKey: decodedConfig.object_storage.secret_access_key,
-        concurrencyLimit: decodedConfig.object_storage.concurrency_limit
+        concurrencyLimit: decodedConfig.object_storage.concurrency_limit,
+        defaultsMode: decodedConfig.object_storage.defaults_mode
       });
     }
 
@@ -46,6 +55,8 @@ export class MongoStorageProvider implements storage.StorageProvider {
       maxPoolSize: resolvedConfig.storage.max_pool_size ?? 8
     });
 
+    const database = new PowerSyncMongo(client, { database: resolvedConfig.storage.database });
+
     let shuttingDown = false;
 
     // Explicitly connect on startup.
@@ -55,7 +66,6 @@ export class MongoStorageProvider implements storage.StorageProvider {
     // Errors here will cause the process to exit.
     await client.connect();
 
-    const database = new PowerSyncMongo(client, { database: resolvedConfig.storage.database });
     const readPreference =
       decodedConfig.bulk_read_preference == null
         ? undefined
@@ -65,10 +75,12 @@ export class MongoStorageProvider implements storage.StorageProvider {
             maxStalenessSeconds: decodedConfig.bulk_read_preference == 'primary' ? undefined : 90
           });
     const syncStorageFactory = new MongoBucketStorage(database, {
+      chunkCompactionConcurrency,
       replicationStreamNamePrefix: resolvedConfig.slot_name_prefix,
       readPreference,
       clearBatchThrottleRate: normalizeClearBatchThrottleRate(decodedConfig.clear_batch_throttle_rate),
       checksumCacheTtlMs: resolvedConfig.api_parameters.bucket_count_cache_ttl_minutes * 60_000,
+      defaultStorageVersion: decodedConfig.default_storage_version,
       // Right now, only MongoDB source databases supports incremental reprocessing.
       // Remove this filter when we support it for other source databases.
       // This assumes a single source connection - revisit if we ever support multiple connections.

package/src/storage/implementation/MongoSyncBucketStorage.ts

@@ -2,6 +2,7 @@ import * as lib_mongo from '@powersync/lib-service-mongodb';
 import { mongo } from '@powersync/lib-service-mongodb';
 import {
   BaseObserver,
+  logger as defaultLogger,
   DO_NOT_LOG,
   Logger,
   ReplicationAbortedError,
@@ -11,14 +12,15 @@ import {
   BroadcastIterable,
   CHECKPOINT_INVALIDATE_ALL,
   CheckpointChanges,
+  CompactInitialReplicationOptions,
+  CompactInitialReplicationResults,
   GetCheckpointChangesOptions,
   InternalOpId,
   mergeAsyncIterables,
-  PopulateChecksumCacheOptions,
-  PopulateChecksumCacheResults,
   ReplicationCheckpoint,
   ReplicationStreamStorageIds,
   storage,
+  SyncRuleState,
   utils,
   WatchWriteCheckpointOptions
 } from '@powersync/service-core';
@@ -28,6 +30,10 @@ import { LRUCache } from 'lru-cache';
 import * as timers from 'timers/promises';
 import { DEFAULT_CLEAR_BATCH_THROTTLE_RATE } from '../../types/types.js';
 import { MongoBucketStorage } from '../MongoBucketStorage.js';
+import {
+  MongoGetCheckpointChangesOptions,
+  MongoSyncBucketStorageCheckpoint
+} from './common/MongoSyncBucketStorageCheckpoint.js';
 import { DEFAULT_INLINE_THRESHOLD_BYTES } from './common/PersistedBatch.js';
 import type { VersionedPowerSyncMongo } from './db.js';
 import { StorageConfig } from './models.js';
@@ -37,7 +43,7 @@ import { MongoCompactOptions, MongoCompactor } from './MongoCompactor.js';
 import { MongoParameterCompactor } from './MongoParameterCompactor.js';
 import { MongoParsedSyncConfigSet } from './MongoParsedSyncConfigSet.js';
 import { MongoPersistedReplicationStream } from './MongoPersistedReplicationStream.js';
-import { MongoWriteCheckpointAPI } from './MongoWriteCheckpointAPI.js';
+import { MongoCheckpointAPIOptions, MongoWriteCheckpointAPI } from './MongoWriteCheckpointAPI.js';
 import { ObjectStorage } from './v3/object-storage/ObjectStorage.js';
 
 export interface MongoSyncBucketStorageOptions {
@@ -50,6 +56,16 @@ export interface MongoSyncBucketStorageOptions {
   inlineThresholdBytes?: number;
 }
 
+/**
+ * The stream state read for a checkpoint. All fields must come from the same snapshot.
+ */
+export interface MongoCheckpointState {
+  checkpoint: InternalOpId;
+  lsn: string | null;
+  /** See {@link MongoSyncBucketStorageCheckpoint.parameterChangesInvalidBefore}. */
+  parameterChangesInvalidBefore: InternalOpId;
+}
+
 interface InternalCheckpointChanges extends CheckpointChanges {
   updatedWriteCheckpoints: Map<string, bigint>;
   invalidateWriteCheckpoints: boolean;
@@ -112,12 +128,27 @@ export abstract class MongoSyncBucketStorage
     this.clearBatchThrottleRate = options.clearBatchThrottleRate ?? DEFAULT_CLEAR_BATCH_THROTTLE_RATE;
     this.db = factory.db.versioned(this.storageConfig);
     this.checksums = this.createMongoChecksums(options);
-    this.writeCheckpointAPI = new MongoWriteCheckpointAPI({
+    this.writeCheckpointAPI = this.createWriteCheckpointAPI({
       db: this.db,
-      mode: writeCheckpointMode ?? storage.WriteCheckpointMode.MANAGED,
-      sync_rules_id: replicationStreamId
+      writeCheckpointMode: { mode: writeCheckpointMode ?? storage.WriteCheckpointMode.MANAGED },
+      replicationStreamId
     });
-    this.logger = replicationStream.logger;
+
+    // Include both replication stream name and sync config version labels in log prefix.
+    // Examples:
+    // No sync config with a label: [stream]
+    // All sync configs have a label: [stream][v5,v6]
+    // Mixed: [stream][?,v6]
+    const hasVersionLabel = replicationStream.syncConfigContent.some((config) => config.version_label != null);
+    const versionLabels = hasVersionLabel
+      ? replicationStream.syncConfigContent.map((config) => config.version_label ?? '?')
+      : [];
+    this.logger =
+      versionLabels.length == 0
+        ? replicationStream.logger
+        : defaultLogger.child({
+            prefix: `[${replicationStreamName}][${versionLabels.join(',')}] `
+          });
   }
 
   /**
@@ -128,11 +159,20 @@ export abstract class MongoSyncBucketStorage
   abstract createMongoCompactor(options: MongoCompactOptions): MongoCompactor;
 
   protected abstract createMongoChecksums(options: MongoSyncBucketStorageOptions): MongoChecksums;
+  protected createWriteCheckpointAPI(options: MongoCheckpointAPIOptions): MongoWriteCheckpointAPI {
+    return new MongoWriteCheckpointAPI(options);
+  }
+
   protected abstract createMongoParameterCompactor(
     checkpoint: InternalOpId,
     options: storage.CompactOptions
   ): MongoParameterCompactor;
 
+  /** MongoDB parameter compaction uses a persisted operation-id cursor. */
+  public supportsIncrementalParameterCompaction(): boolean {
+    return true;
+  }
+
   get writeCheckpointMode() {
     return this.writeCheckpointAPI.writeCheckpointMode;
   }
@@ -144,8 +184,8 @@ export abstract class MongoSyncBucketStorage
     return this.replicationStream.storageIds;
   }
 
-  setWriteCheckpointMode(mode: storage.WriteCheckpointMode): void {
-    this.writeCheckpointAPI.setWriteCheckpointMode(mode);
+  setWriteCheckpointMode(config: storage.WriteCheckpointModeConfig): void {
+    this.writeCheckpointAPI.setWriteCheckpointMode(config);
   }
 
   createManagedWriteCheckpoints(
@@ -178,9 +218,7 @@ export abstract class MongoSyncBucketStorage
     return (await this.getCheckpointInternal()) ?? new EmptyReplicationCheckpoint();
   }
 
-  protected abstract fetchCheckpointState(
-    session: mongo.ClientSession
-  ): Promise<{ checkpoint: bigint; lsn: string | null } | null>;
+  protected abstract fetchCheckpointState(session: mongo.ClientSession): Promise<MongoCheckpointState | null>;
 
   async getCheckpointInternal(): Promise<storage.ReplicationCheckpoint | null> {
     return await this.db.client.withSession({ snapshot: true }, async (session) => {
@@ -197,7 +235,14 @@ export abstract class MongoSyncBucketStorage
       if (clusterTime == null) {
         throw new ServiceAssertionError('Missing clusterTime in getCheckpoint()');
       }
-      return new MongoReplicationCheckpoint(this, state.checkpoint, state.lsn, snapshotTime, clusterTime);
+      return new MongoReplicationCheckpoint(
+        this,
+        state.checkpoint,
+        state.lsn,
+        snapshotTime,
+        clusterTime,
+        state.parameterChangesInvalidBefore
+      );
     });
   }
 
@@ -235,6 +280,7 @@ export abstract class MongoSyncBucketStorage
       markRecordUnavailable: options.markRecordUnavailable,
       hooks: options.hooks,
       tracer: options.tracer,
+      signal: options.signal,
       objectStorage: this.objectStorage,
       inlineThresholdBytes: this.inlineThresholdBytes
     };
@@ -329,6 +375,7 @@ export abstract class MongoSyncBucketStorage
   protected abstract clearBucketState(signal?: AbortSignal): Promise<void>;
 
   protected abstract clearSourceTables(signal?: AbortSignal): Promise<void>;
+  protected async clearCustomCheckpointRequests(_signal?: AbortSignal): Promise<void> {}
   protected abstract clearSyncRuleState(): Promise<void>;
 
   async clear(options?: storage.ClearStorageOptions): Promise<void> {
@@ -345,6 +392,7 @@ export abstract class MongoSyncBucketStorage
     await this.clearSourceRecords(signal);
     await this.clearBucketState(signal);
     await this.clearSourceTables(signal);
+    await this.clearCustomCheckpointRequests(signal);
 
     this.#storageInitialized = false;
   }
@@ -367,43 +415,30 @@ export abstract class MongoSyncBucketStorage
   async compact(options?: storage.CompactOptions) {
     let maxOpId = options?.maxOpId;
     if (maxOpId == null) {
+      // For PROCESSING streams, this will be undefined.
       const checkpoint = await this.getCheckpointInternal();
       maxOpId = checkpoint?.checkpoint ?? undefined;
     }
     await this.createMongoCompactor({ ...options, maxOpId, logger: this.logger }).compact();
 
-    if (maxOpId != null && options?.compactParameterData) {
-      await this.createMongoParameterCompactor(maxOpId, options).compact();
+    if (maxOpId != null && options?.compactParameterData && this.replicationStream.state == SyncRuleState.ACTIVE) {
+      // Use the stream-scoped logger, matching bucket compaction above.
+      await this.createMongoParameterCompactor(maxOpId, { ...options, logger: this.logger }).compact();
     }
   }
 
+  abstract compactInitialReplication(
+    options: CompactInitialReplicationOptions
+  ): Promise<CompactInitialReplicationResults>;
+
   /**
    * The highest op id persisted for this stream, whether or not covered by a checkpoint.
    *
-   * Used as the default `maxOpId` for {@link populatePersistentChecksumCache}, which runs after
+   * Used as the default `maxOpId` for {@link compactInitialReplication}, which runs after
    * initial replication but before the first checkpoint exists.
    */
   protected abstract fetchPersistedOpHead(): Promise<InternalOpId | null>;
 
-  async populatePersistentChecksumCache(options: PopulateChecksumCacheOptions): Promise<PopulateChecksumCacheResults> {
-    this.logger.info(`Populating persistent checksum cache...`);
-    const start = Date.now();
-    const maxOpId = options.maxOpId ?? (await this.fetchPersistedOpHead()) ?? undefined;
-    const compactor = this.createMongoCompactor({
-      ...options,
-      maxOpId,
-      memoryLimitMB: 0,
-      logger: this.logger
-    });
-
-    const result = await compactor.populateChecksums({
-      minBucketChanges: options.minBucketChanges ?? 10
-    });
-    const duration = Date.now() - start;
-    this.logger.info(`Populated persistent checksum cache in ${(duration / 1000).toFixed(1)}s`);
-    return result;
-  }
-
   private async *watchActiveCheckpoint(signal: AbortSignal): AsyncIterable<ReplicationCheckpoint> {
     if (signal.aborted) {
       return;
@@ -580,13 +615,31 @@ export abstract class MongoSyncBucketStorage
   }
 
   protected abstract getParameterBucketChangesImpl(
-    options: GetCheckpointChangesOptions
+    options: MongoGetCheckpointChangesOptions
   ): Promise<Pick<CheckpointChanges, 'updatedParameterLookups' | 'invalidateParameterBuckets'>>;
 
   private async getParameterBucketChanges(
     options: GetCheckpointChangesOptions
   ): Promise<Pick<CheckpointChanges, 'updatedParameterLookups' | 'invalidateParameterBuckets'>> {
-    return this.getParameterBucketChangesImpl(options);
+    const nextCheckpoint = requireMongoCheckpoint(options.nextCheckpoint);
+    if (options.lastCheckpoint.checkpoint < nextCheckpoint.parameterChangesInvalidBefore) {
+      // Parameter compaction may have deleted parameter entries in the range we'd have to query
+      // to find the individual changed lookups. Invalidate all parameter buckets instead.
+      //
+      // The fence is committed before the first delete of a compaction pass, and captured in the
+      // same snapshot as the checkpoint, so a checkpoint that could miss a deleted entry always
+      // observes the fence as well.
+      return {
+        invalidateParameterBuckets: true,
+        updatedParameterLookups: new Set<string>()
+      };
+    }
+    // The query below runs at the checkpoint snapshot, which still sees entries deleted by a
+    // compaction pass that started after the snapshot.
+    return this.getParameterBucketChangesImpl({
+      lastCheckpoint: options.lastCheckpoint,
+      nextCheckpoint
+    });
   }
 
   private checkpointChangesCache = new LRUCache<
@@ -611,7 +664,10 @@ export abstract class MongoSyncBucketStorage
   });
 
   async getCheckpointChanges(options: GetCheckpointChangesOptions): Promise<InternalCheckpointChanges> {
-    const key = `${options.lastCheckpoint.checkpoint}_${options.lastCheckpoint.lsn}__${options.nextCheckpoint.checkpoint}_${options.nextCheckpoint.lsn}`;
+    // The invalidation fence is part of the identity: the same checkpoint pair read before and
+    // after a compaction pass produces different results (specific lookups vs. invalidate-all).
+    const fence = requireMongoCheckpoint(options.nextCheckpoint).parameterChangesInvalidBefore;
+    const key = `${options.lastCheckpoint.checkpoint}_${options.lastCheckpoint.lsn}__${options.nextCheckpoint.checkpoint}_${options.nextCheckpoint.lsn}_${fence}`;
     const result = await this.checkpointChangesCache.fetch(key, { context: { options } });
     return result!;
   }
@@ -629,7 +685,19 @@ export abstract class MongoSyncBucketStorage
   }
 }
 
-class MongoReplicationCheckpoint implements ReplicationCheckpoint {
+/**
+ * We don't support any other constructions of ReplicationCheckpoint.
+ */
+function requireMongoCheckpoint(checkpoint: ReplicationCheckpoint): MongoReplicationCheckpoint {
+  if (!(checkpoint instanceof MongoReplicationCheckpoint)) {
+    throw new ServiceAssertionError(
+      `Checkpoint changes require a checkpoint from getCheckpointInternal(), got ${checkpoint.constructor.name}`
+    );
+  }
+  return checkpoint;
+}
+
+class MongoReplicationCheckpoint implements MongoSyncBucketStorageCheckpoint {
   #storage: MongoSyncBucketStorage;
 
   constructor(
@@ -637,7 +705,9 @@ class MongoReplicationCheckpoint implements ReplicationCheckpoint {
     public readonly checkpoint: InternalOpId,
     public readonly lsn: string | null,
     public snapshotTime: mongo.Timestamp,
-    public clusterTime: mongo.ClusterTime
+    public clusterTime: mongo.ClusterTime,
+    /** Captured in the same snapshot as the checkpoint. */
+    public readonly parameterChangesInvalidBefore: InternalOpId
   ) {
     this.#storage = storage;
   }
@@ -647,6 +717,10 @@ class MongoReplicationCheckpoint implements ReplicationCheckpoint {
   }
 }
 
+/**
+ * Used when no checkpoint has been persisted yet. This has no snapshot or invalidation fence, so
+ * it cannot be used for checkpoint change detection - see {@link requireMongoCheckpoint}.
+ */
 class EmptyReplicationCheckpoint implements ReplicationCheckpoint {
   readonly checkpoint: InternalOpId = 0n;
   readonly lsn: string | null = null;

package/src/storage/implementation/MongoSyncRulesLock.ts

@@ -5,6 +5,8 @@ import { ErrorCode, Logger, ServiceError } from '@powersync/lib-services-framewo
 import { storage } from '@powersync/service-core';
 import { VersionedPowerSyncMongo } from './db.js';
 
+const LOCK_DURATION_MS = 60 * 1000;
+
 /**
  * Manages a lock on a replication stream document, so that only one process
  * processes that replication stream at a time.
@@ -22,15 +24,20 @@ export class MongoSyncRulesLock implements storage.ReplicationLock {
   ): Promise<MongoSyncRulesLock> {
     const lockId = crypto.randomBytes(8).toString('hex');
     const doc = await db.sync_rules.findOneAndUpdate(
-      { _id: sync_rules.replicationStreamId, $or: [{ lock: null }, { 'lock.expires_at': { $lt: new Date() } }] },
       {
-        $set: {
-          lock: {
-            id: lockId,
-            expires_at: new Date(Date.now() + 60 * 1000)
+        _id: sync_rules.replicationStreamId,
+        $or: [{ lock: null }, { $expr: { $lt: ['$lock.expires_at', '$$NOW'] } }]
+      },
+      [
+        {
+          $set: {
+            lock: {
+              id: lockId,
+              expires_at: { $dateAdd: { startDate: '$$NOW', unit: 'millisecond', amount: LOCK_DURATION_MS } }
+            }
           }
         }
-      },
+      ],
       {
         projection: { lock: 1 },
         returnDocument: 'before',
@@ -96,9 +103,15 @@ export class MongoSyncRulesLock implements storage.ReplicationLock {
         _id: this.sync_rules_id,
         'lock.id': this.lock_id
       },
-      {
-        $set: { 'lock.expires_at': new Date(Date.now() + 60 * 1000) }
-      },
+      [
+        {
+          $set: {
+            'lock.expires_at': {
+              $dateAdd: { startDate: '$$NOW', unit: 'millisecond', amount: LOCK_DURATION_MS }
+            }
+          }
+        }
+      ],
       { returnDocument: 'after' }
     );
     if (result == null) {

package/src/storage/implementation/MongoWriteBatch.ts

@@ -0,0 +1,172 @@
+import { mongo } from '@powersync/lib-service-mongodb';
+
+/**
+ * Explicitly groups writes with no intervening reads or result dependencies.
+ * Callers retain responsibility for transaction and ordering boundaries.
+ *
+ * On MongoDB 8.0+, this uses the client-level bulkWrite API.
+ *
+ * On MongoDB earlier versions, this uses the the collection-level bulkWrite API, or individual operations.
+ * This is less efficient, but produces the same results.
+ */
+export class MongoWriteBatch {
+  private readonly operations: mongo.AnyClientBulkWriteModel<mongo.Document>[] = [];
+  private readonly deleteChecks: { index: number; check: (count: number) => void }[] = [];
+  private readonly fallback: (() => Promise<unknown>)[] = [];
+
+  private readonly ordered: boolean;
+
+  constructor(
+    private readonly client: mongo.MongoClient,
+    private readonly supportsClientBulkWrite: boolean,
+    private readonly session: mongo.ClientSession | undefined,
+    options: { ordered: boolean }
+  ) {
+    this.ordered = options.ordered;
+  }
+
+  /**
+   * Perform a collection-level bulkWrite.
+   *
+   * On MongoDB 8.0+, these operations join the client-level bulkWrite with the batch's ordering.
+   * The driver may split commands to respect server batch limits.
+   *
+   * On earlier MongoDB versions, this always uses an unordered collection-level bulkWrite.
+   * Operations within this collection bulk must therefore be independent of their order.
+   */
+  bulkWriteUnordered<T extends mongo.Document>(
+    collection: mongo.Collection<T>,
+    operations: mongo.AnyBulkWriteOperation<T>[]
+  ): void {
+    if (operations.length === 0) return;
+    if (!this.supportsClientBulkWrite) {
+      this.fallback.push(() => collection.bulkWrite(operations, { ordered: false, session: this.session }));
+      return;
+    }
+    for (const operation of operations) {
+      // Collection and client models contain the same operation fields, with a
+      // different envelope. Keep the schema checked at the collection boundary.
+      const [name, model] = Object.entries(operation)[0];
+      this.operations.push({ ...model, name, namespace: collection.namespace });
+    }
+  }
+
+  insertOne<T extends mongo.Document>(collection: mongo.Collection<T>, document: mongo.OptionalUnlessRequiredId<T>) {
+    if (!this.supportsClientBulkWrite) {
+      this.fallback.push(() => collection.insertOne(document, { session: this.session }));
+      return;
+    }
+    this.addModel<T>({ name: 'insertOne', namespace: collection.namespace, document: document as mongo.OptionalId<T> });
+  }
+
+  insertMany<T extends mongo.Document>(
+    collection: mongo.Collection<T>,
+    documents: mongo.OptionalUnlessRequiredId<T>[]
+  ) {
+    if (documents.length === 0) return;
+    if (!this.supportsClientBulkWrite) {
+      this.fallback.push(() => collection.insertMany(documents, { session: this.session }));
+      return;
+    }
+    for (const document of documents) {
+      this.addModel<T>({
+        name: 'insertOne',
+        namespace: collection.namespace,
+        document: document as mongo.OptionalId<T>
+      });
+    }
+  }
+
+  deleteMany<T extends mongo.Document>(
+    collection: mongo.Collection<T>,
+    filter: mongo.Filter<T>,
+    checkDeletedCount?: (count: number) => void
+  ) {
+    if (checkDeletedCount) {
+      // Client-bulk results are checked after all writes execute. A failed
+      // invariant must roll back the entire batch, not leave later writes visible.
+      if (!this.session?.inTransaction()) throw new Error('Checked deletes require a transaction');
+    }
+    if (!this.supportsClientBulkWrite) {
+      this.fallback.push(async () => {
+        const result = await collection.deleteMany(filter, { session: this.session });
+        checkDeletedCount?.(result.deletedCount);
+      });
+      return;
+    }
+    if (checkDeletedCount) {
+      this.deleteChecks.push({ index: this.operations.length, check: checkDeletedCount });
+    }
+    this.addModel<T>({ name: 'deleteMany', namespace: collection.namespace, filter });
+  }
+
+  updateOne<T extends mongo.Document>(
+    collection: mongo.Collection<T>,
+    filter: mongo.Filter<T>,
+    update: mongo.UpdateFilter<T> | mongo.Document[],
+    options: Pick<mongo.UpdateOptions, 'upsert' | 'arrayFilters'> = {}
+  ) {
+    if (!this.supportsClientBulkWrite) {
+      this.fallback.push(() => collection.updateOne(filter, update, { ...options, session: this.session }));
+      return;
+    }
+    this.addModel({ name: 'updateOne', namespace: collection.namespace, filter, update, ...options });
+  }
+
+  updateMany<T extends mongo.Document>(
+    collection: mongo.Collection<T>,
+    filter: mongo.Filter<T>,
+    update: mongo.UpdateFilter<T> | mongo.Document[],
+    options: Pick<mongo.UpdateOptions, 'upsert' | 'arrayFilters'> = {}
+  ) {
+    if (!this.supportsClientBulkWrite) {
+      this.fallback.push(() => collection.updateMany(filter, update, { ...options, session: this.session }));
+      return;
+    }
+    this.addModel({ name: 'updateMany', namespace: collection.namespace, filter, update, ...options });
+  }
+
+  private addModel<T extends mongo.Document>(operation: mongo.AnyClientBulkWriteModel<T>) {
+    // The collection-specific methods validate the schema before erasing it here.
+    this.operations.push(operation as unknown as mongo.AnyClientBulkWriteModel<mongo.Document>);
+  }
+
+  /**
+   * Execute the queued writes.
+   *
+   * On MongoDB 8.0+, this uses the client-level bulkWrite API, typically resulting in a single command.
+   * The command may be split if there are a large number of operations.
+   *
+   * On earlier MongoDB versions, this executes each queued operation individually.
+   *
+   * If no operations were queued, this is a no-op.
+   */
+  async execute(): Promise<void> {
+    if (!this.supportsClientBulkWrite) {
+      // Sessions cannot execute concurrent operations within a transaction.
+      for (const write of this.fallback) await write();
+      return;
+    }
+    if (this.operations.length === 0) return;
+
+    try {
+      const result = await this.client.bulkWrite(this.operations, {
+        session: this.session,
+        ordered: this.ordered,
+        verboseResults: this.deleteChecks.length > 0
+      });
+      for (const { index, check } of this.deleteChecks) {
+        const deleted = result.deleteResults?.get(index);
+        if (deleted == null) throw new Error('Missing client bulk delete result');
+        check(deleted.deletedCount);
+      }
+    } catch (error) {
+      // The driver wraps command failures without copying their error labels.
+      // Preserve withTransaction's retry handling for e.g. write conflicts.
+      if (error instanceof mongo.MongoClientBulkWriteError && error.cause instanceof mongo.MongoError) {
+        throw error.cause;
+      }
+      throw error;
+    }
+  }
+}