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

package/src/storage/implementation/v1/MongoSyncBucketStorageV1.ts

@@ -3,6 +3,8 @@ import { mongo } from '@powersync/lib-service-mongodb';
 import { ServiceAssertionError } from '@powersync/lib-services-framework';
 import {
   CheckpointChanges,
+  CompactInitialReplicationOptions,
+  CompactInitialReplicationResults,
   deserializeParameterLookup,
   GetCheckpointChangesOptions,
   InternalOpId,
@@ -26,13 +28,20 @@ import {
   setSessionSnapshotTime
 } from '../../../utils/util.js';
 import { MongoBucketStorage } from '../../MongoBucketStorage.js';
-import { MongoSyncBucketStorageCheckpoint } from '../common/MongoSyncBucketStorageCheckpoint.js';
+import {
+  MongoGetCheckpointChangesOptions,
+  MongoSyncBucketStorageCheckpoint
+} from '../common/MongoSyncBucketStorageCheckpoint.js';
 import { SourceKey } from '../models.js';
 import { MongoChecksums } from '../MongoChecksums.js';
-import { MongoCompactOptions, MongoCompactor } from '../MongoCompactor.js';
+import { MongoCompactOptions } from '../MongoCompactor.js';
 import { MongoParameterCompactor } from '../MongoParameterCompactor.js';
 import { MongoPersistedReplicationStream } from '../MongoPersistedReplicationStream.js';
-import { MongoSyncBucketStorage, MongoSyncBucketStorageOptions } from '../MongoSyncBucketStorage.js';
+import {
+  MongoCheckpointState,
+  MongoSyncBucketStorage,
+  MongoSyncBucketStorageOptions
+} from '../MongoSyncBucketStorage.js';
 import {
   BucketDataDocumentV1,
   BucketDataKeyV1,
@@ -100,14 +109,20 @@ export class MongoSyncBucketStorageV1 extends MongoSyncBucketStorage {
     });
   }
 
-  protected async fetchCheckpointState(
-    session: mongo.ClientSession
-  ): Promise<{ checkpoint: bigint; lsn: string | null } | null> {
+  protected async fetchCheckpointState(session: mongo.ClientSession): Promise<MongoCheckpointState | null> {
     const doc = (await this.db.sync_rules.findOne(
       { _id: this.replicationStreamId },
       {
         session,
-        projection: { _id: 1, state: 1, last_checkpoint: 1, last_checkpoint_lsn: 1, snapshot_done: 1 }
+        projection: {
+          _id: 1,
+          state: 1,
+          last_checkpoint: 1,
+          last_checkpoint_lsn: 1,
+          snapshot_done: 1,
+          // Must be read in the same snapshot as the checkpoint.
+          'parameter_compaction.checkpoint_changes_invalid_before': 1
+        }
       }
     )) as SyncRuleDocumentV1;
     if (!doc?.snapshot_done || ![storage.SyncRuleState.ACTIVE, storage.SyncRuleState.ERRORED].includes(doc.state)) {
@@ -115,7 +130,9 @@ export class MongoSyncBucketStorageV1 extends MongoSyncBucketStorage {
     }
     return {
       checkpoint: doc.last_checkpoint ?? 0n,
-      lsn: doc.last_checkpoint_lsn ?? null
+      lsn: doc.last_checkpoint_lsn ?? null,
+      // Defaults to 0n for streams that have never been compacted.
+      parameterChangesInvalidBefore: doc.parameter_compaction?.checkpoint_changes_invalid_before ?? 0n
     };
   }
 
@@ -171,7 +188,8 @@ export class MongoSyncBucketStorageV1 extends MongoSyncBucketStorage {
           no_checkpoint_before: null
         },
         $unset: {
-          snapshot_lsn: 1
+          snapshot_lsn: 1,
+          parameter_compaction: 1
         }
       },
       { maxTimeMS: lib_mongo.db.MONGO_CLEAR_OPERATION_TIMEOUT_MS }
@@ -186,10 +204,31 @@ export class MongoSyncBucketStorageV1 extends MongoSyncBucketStorage {
     });
   }
 
-  createMongoCompactor(options: MongoCompactOptions): MongoCompactor {
+  createMongoCompactor(options: MongoCompactOptions): MongoCompactorV1 {
     return new MongoCompactorV1(this, this.db, options);
   }
 
+  async compactInitialReplication(
+    options: CompactInitialReplicationOptions
+  ): Promise<CompactInitialReplicationResults> {
+    this.logger.info(`Compacting after initial replication...`);
+    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(`Compacted after initial replication in ${(duration / 1000).toFixed(1)}s`);
+    return result;
+  }
+
   protected createMongoParameterCompactor(
     checkpoint: InternalOpId,
     options: storage.CompactOptions
@@ -303,7 +342,7 @@ export class MongoSyncBucketStorageV1 extends MongoSyncBucketStorage {
   }
 
   protected getParameterBucketChangesImpl(
-    options: GetCheckpointChangesOptions
+    options: MongoGetCheckpointChangesOptions
   ): Promise<Pick<CheckpointChanges, 'updatedParameterLookups' | 'invalidateParameterBuckets'>> {
     return getParameterBucketChangesV1(this.versionContext, options);
   }
@@ -548,27 +587,48 @@ export async function getDataBucketChangesV1(
   };
 }
 
+/**
+ * Query the parameter entries changed between the two checkpoints, to determine which parameter
+ * lookups need to be re-evaluated.
+ *
+ * This runs at the next checkpoint's snapshot, so it still sees entries that parameter compaction
+ * deleted after that snapshot. Compaction that deleted entries before the snapshot is covered by
+ * the invalidation fence, checked before we get here.
+ */
 export async function getParameterBucketChangesV1(
   ctx: MongoSyncBucketStorageContextV1,
-  options: GetCheckpointChangesOptions
+  options: MongoGetCheckpointChangesOptions
 ): Promise<Pick<CheckpointChanges, 'updatedParameterLookups' | 'invalidateParameterBuckets'>> {
   const limit = 1000;
-  const parameterUpdates = await ctx.db.parameterIndexV1
-    .find(
-      {
-        _id: { $gt: options.lastCheckpoint.checkpoint, $lte: options.nextCheckpoint.checkpoint },
-        'key.g': ctx.replicationStreamId
-      },
-      {
-        projection: {
-          lookup: 1
+  const parameterUpdates = await ctx.db.client.withSession({ snapshot: true }, async (session) => {
+    setSessionSnapshotTime(session, options.nextCheckpoint.snapshotTime);
+    return await ctx.db.parameterIndexV1
+      .find(
+        {
+          _id: { $gt: options.lastCheckpoint.checkpoint, $lte: options.nextCheckpoint.checkpoint },
+          'key.g': ctx.replicationStreamId
         },
-        limit: limit + 1,
-        batchSize: limit + 2,
-        singleBatch: true
-      }
-    )
-    .toArray();
+        {
+          session,
+          readConcern: 'snapshot',
+          projection: {
+            lookup: 1
+          },
+          limit: limit + 1,
+          batchSize: limit + 2,
+          singleBatch: true
+        }
+      )
+      .toArray()
+      .catch((e) => {
+        // Includes the case where the checkpoint snapshot has expired. Degrading to
+        // invalidateParameterBuckets would be safe in itself - it reads nothing - but it gains
+        // nothing: the caller responds to that by re-evaluating the parameter queries at this
+        // same snapshot, which fails too. The checkpoint has to be refetched instead, which is
+        // what the existing sync retry behavior does.
+        throw lib_mongo.mapQueryError(e, 'while querying parameter changes');
+      });
+  });
   const invalidateParameterUpdates = parameterUpdates.length > limit;
 
   return {

package/src/storage/implementation/v1/models.ts

@@ -48,6 +48,7 @@ export function serializeBucketDataV1(document: BucketDataDoc): BucketDataDocume
     op: document.op,
     source_table: document.source_table,
     source_key: document.source_key,
+    subkey: document.subkey,
     table: document.table,
     row_id: document.row_id,
     checksum: document.checksum,

package/src/storage/implementation/v3/CompactionLease.ts

@@ -0,0 +1,152 @@
+import { mongo } from '@powersync/lib-service-mongodb';
+import { InternalOpId } from '@powersync/service-core';
+import { CompactionLeaseLostError } from '../MongoCompactor.js';
+import { BucketStateDocumentV3 } from './models.js';
+
+const LEASE_RENEW_INTERVAL_MS = 60 * 1000;
+
+/**
+ * Filters for buckets that have no lease or an expired lease.
+ */
+export const AVAILABLE_LEASE_EXPR = {
+  // $$NOW is evaluated by MongoDB, avoiding lease expiry races due
+  // to clocks on separate compact workers.
+  $expr: {
+    $or: [{ $eq: [{ $type: '$compact_lease' }, 'missing'] }, { $lte: ['$compact_lease.expires_at', '$$NOW'] }]
+  }
+};
+
+/**
+ * Owns one V3 bucket-compaction lease, including its server-time renewal and
+ * the owner-fenced operations which release it.
+ *
+ * This is intended as a way to reduce redundant work if multiple jobs attempt to
+ * compact the same bucket concurrently, but it's not an absolute safety guarantee.
+ * The individual operations must still be designed to be safe with concurrent compacting.
+ */
+export class CompactionLease implements AsyncDisposable {
+  readonly startedAt: Date;
+  readonly lastOp: InternalOpId;
+
+  private timer: NodeJS.Timeout | undefined;
+  private renewalInFlight = false;
+  private renewalError: unknown;
+  private finalizing = false;
+  private finished = false;
+
+  private constructor(
+    private readonly collection: mongo.Collection<BucketStateDocumentV3>,
+    readonly state: BucketStateDocumentV3,
+    readonly id: mongo.ObjectId,
+    private readonly durationMs: number
+  ) {
+    this.startedAt = new Date(state.compact_lease!.expires_at.getTime() - durationMs);
+    this.lastOp = state.last_op;
+  }
+
+  static async claim(
+    collection: mongo.Collection<BucketStateDocumentV3>,
+    filter: mongo.Filter<BucketStateDocumentV3>,
+    sort: mongo.Sort | undefined,
+    durationMs: number
+  ): Promise<CompactionLease | null> {
+    const id = new mongo.ObjectId();
+    const state = await collection.findOneAndUpdate(
+      {
+        $and: [filter, AVAILABLE_LEASE_EXPR]
+      },
+      [
+        {
+          $set: {
+            compact_lease: {
+              id,
+              expires_at: { $dateAdd: { startDate: '$$NOW', unit: 'millisecond', amount: durationMs } }
+            }
+          }
+        }
+      ],
+      { sort, returnDocument: 'after' }
+    );
+    return state == null ? null : new CompactionLease(collection, state, id, durationMs);
+  }
+
+  startRenewal() {
+    const interval = Math.max(1, Math.min(LEASE_RENEW_INTERVAL_MS, Math.floor(this.durationMs / 2)));
+    this.timer = setInterval(() => {
+      if (this.renewalInFlight) {
+        return;
+      }
+      this.renewalInFlight = true;
+      void this.renew()
+        .catch((error) => {
+          this.renewalError = error;
+        })
+        .finally(() => {
+          this.renewalInFlight = false;
+        });
+    }, interval);
+    this.timer.unref();
+  }
+
+  async throwIfLost() {
+    if (this.renewalError != null) {
+      throw this.renewalError;
+    }
+  }
+
+  async reschedule(nextCompactCheck: mongo.Document) {
+    await this.finish([{ $set: { next_compact_check: nextCompactCheck } }, { $unset: 'compact_lease' }]);
+  }
+
+  async finalize(update: mongo.Document) {
+    await this.finish([{ $set: update }, { $unset: 'compact_lease' }]);
+  }
+
+  async [Symbol.asyncDispose]() {
+    if (this.timer != null) {
+      clearInterval(this.timer);
+      this.timer = undefined;
+    }
+    if (this.finished) {
+      return;
+    }
+    this.finalizing = true;
+    await this.collection.updateOne(this.filter, { $unset: { compact_lease: '' } });
+    this.finished = true;
+  }
+
+  private get filter(): mongo.Filter<BucketStateDocumentV3> {
+    return { _id: this.state._id, 'compact_lease.id': this.id };
+  }
+
+  private async renew() {
+    const result = await this.collection.updateOne(this.filter, [
+      {
+        $set: {
+          'compact_lease.expires_at': {
+            $dateAdd: { startDate: '$$NOW', unit: 'millisecond', amount: this.durationMs }
+          }
+        }
+      }
+    ]);
+    // A finalization in progress owns the authoritative fenced result.
+    if (result.matchedCount != 1 && !this.finalizing) {
+      throw new CompactionLeaseLostError(`Lost compaction lease for bucket ${this.state._id.b}`);
+    }
+    // A successful renewal confirms that a transient failure has passed. A
+    // lease-loss error remains sticky: it means another worker may own it.
+    if (!(this.renewalError instanceof CompactionLeaseLostError)) {
+      this.renewalError = undefined;
+    }
+  }
+
+  private async finish(update: mongo.Document[]) {
+    await this.throwIfLost();
+    this.finalizing = true;
+    const result = await this.collection.updateOne(this.filter, update);
+    if (result.matchedCount != 1) {
+      throw new CompactionLeaseLostError(`Lost compaction lease for bucket ${this.state._id.b}`);
+    }
+    this.finished = true;
+  }
+}

package/src/storage/implementation/v3/MongoBucketBatchV3.ts

@@ -1,21 +1,21 @@
 import * as lib_mongo from '@powersync/lib-service-mongodb';
-import { ReplicationAssertionError } from '@powersync/lib-services-framework';
-import { storage } from '@powersync/service-core';
+import { ReplicationAssertionError, ServiceAssertionError } from '@powersync/lib-services-framework';
+import { InternalOpId, storage } from '@powersync/service-core';
+import { EventDefinitionId } from '@powersync/service-sync-rules';
 import * as bson from 'bson';
 import { mongoTableId } from '../../../utils/util.js';
 import { canCheckpointState } from '../CheckpointState.js';
 import { MongoBucketBatch, MongoBucketBatchOptions } from '../MongoBucketBatch.js';
 import { MongoParsedSyncConfigSet } from '../MongoParsedSyncConfigSet.js';
-import { syncRuleStateUpdatePipeline } from '../SyncRuleStateUpdate.js';
+import { stopReplicationStreamPipeline } from '../SyncRuleStateUpdate.js';
 import { PersistedBatch } from '../common/PersistedBatch.js';
 import { SourceRecordStore } from '../common/SourceRecordStore.js';
 import { PersistedBatchV3 } from './PersistedBatchV3.js';
 import { SourceRecordStoreV3 } from './SourceRecordStoreV3.js';
 import { VersionedPowerSyncMongoV3 } from './VersionedPowerSyncMongoV3.js';
-import { ReplicationStreamDocumentV3, SourceTableDocumentV3 } from './models.js';
+import { CustomCheckpointRequestDocumentV3, ReplicationStreamDocumentV3, SourceTableDocumentV3 } from './models.js';
 import {
   createNewSourceTable,
-  designateEventCarrier,
   overlappingSourceTableFilter,
   planSourceTableReconciliation,
   sourceTableDesiredResolution,
@@ -27,6 +27,10 @@ export class MongoBucketBatchV3 extends MongoBucketBatch {
   declare readonly db: VersionedPowerSyncMongoV3;
 
   private readonly store: SourceRecordStore;
+  /** Avoid repeating idempotent createIndexes calls for every checkpoint flush. */
+  private readonly initializedCustomCheckpointEventIds = new Set<EventDefinitionId>();
+  // Used only to validate supplied checkpoint ids; it does not initialize collections.
+  private readonly knownEventIds: ReadonlySet<EventDefinitionId>;
   private readonly syncConfigIds: bson.ObjectId[];
   private needsActivationV3 = true;
   private lastWaitingLogThrottledV3 = 0;
@@ -38,6 +42,7 @@ export class MongoBucketBatchV3 extends MongoBucketBatch {
       throw new ReplicationAssertionError('Missing sync config id for v3 batch');
     }
     this.syncConfigIds = syncConfigIds;
+    this.knownEventIds = new Set(this.mapping.allEventDefinitionIds());
     this.store = new SourceRecordStoreV3(this.db, this.replicationStreamId, this.mapping);
   }
 
@@ -45,7 +50,9 @@ export class MongoBucketBatchV3 extends MongoBucketBatch {
     return new PersistedBatchV3(this.db, this.replicationStreamId, this.mapping, writtenSize, {
       logger: this.logger,
       objectStorage: this.options.objectStorage,
-      inlineThresholdBytes: this.options.inlineThresholdBytes
+      inlineThresholdBytes: this.options.inlineThresholdBytes,
+      signal: this.options.signal,
+      objectStorageUsageWriterId: this.objectStorageUsageWriterId
     });
   }
 
@@ -90,7 +97,8 @@ export class MongoBucketBatchV3 extends MongoBucketBatch {
         this.syncConfigIds.map((id) => id.toHexString()),
         table.ref,
         bucketDataSourceIds,
-        parameterLookupSourceIds
+        parameterLookupSourceIds,
+        [...table.eventDefinitionIds!]
       )
     );
   }
@@ -132,7 +140,7 @@ export class MongoBucketBatchV3 extends MongoBucketBatch {
         .sourceRecords(this.replicationStreamId, mongoTableId(table.id))
         .drop()
         .catch((error) => {
-          if (lib_mongo.isMongoServerError(error) && error.codeName === 'NamespaceNotFound') {
+          if (lib_mongo.isMongoNamespaceNotFoundError(error)) {
             return;
           }
           throw error;
@@ -146,6 +154,7 @@ export class MongoBucketBatchV3 extends MongoBucketBatch {
     const parsedOverride = options.parsedSyncConfig as MongoParsedSyncConfigSet | undefined;
     const syncConfig = parsedOverride?.hydratedSyncConfig ?? this.sync_rules;
     const mapping = parsedOverride?.mapping ?? this.mapping;
+    const eventById = (parsedOverride ?? this.options.parsedSyncConfig).eventById;
 
     const { connection_id, source } = options;
     const reconcile = options.reconcileSourceTables ?? storage.defaultSourceTableReconciler;
@@ -173,7 +182,7 @@ export class MongoBucketBatchV3 extends MongoBucketBatch {
         .toArray();
 
       const candidateTables = candidateDocs.map((doc) =>
-        sourceTableFromDocument(doc, source.connectionTag, syncConfig, mapping)
+        sourceTableFromDocument(doc, source.connectionTag, syncConfig, mapping, eventById)
       );
       const candidates = candidateTables.map((table) => table.clone());
       const resolution = await reconcile({ source, candidates });
@@ -191,7 +200,7 @@ export class MongoBucketBatchV3 extends MongoBucketBatch {
         storeCurrentData: source.sendsCompleteRows !== true,
         syncConfig,
         mapping,
-        desired: sourceTableDesiredResolution(syncConfig, source, mapping),
+        desired: sourceTableDesiredResolution(syncConfig, source, mapping, eventById),
         sourceCompatibleTables: resolution.compatibleTables,
         newTableSourceMetadata: resolution.newTableValues.sourceMetadata
       };
@@ -209,7 +218,8 @@ export class MongoBucketBatchV3 extends MongoBucketBatch {
           {
             $set: {
               bucket_data_source_ids: update.memberships.bucketDataSourceIds,
-              parameter_lookup_source_ids: update.memberships.parameterLookupSourceIds
+              parameter_lookup_source_ids: update.memberships.parameterLookupSourceIds,
+              event_definition_ids: update.memberships.eventDefinitionIds
             }
           },
           { session }
@@ -227,12 +237,11 @@ export class MongoBucketBatchV3 extends MongoBucketBatch {
         plan.tables.push(table);
       }
 
-      // If memberships are split across multiple source tables, only one may fire events.
-      designateEventCarrier(plan.tables, context.desired.triggersEvent);
-
       result = {
         tables: plan.tables,
-        dropTables: plan.dropDocs.map((doc) => sourceTableFromDocument(doc, context.connectionTag, syncConfig, mapping))
+        dropTables: plan.dropDocs.map((doc) =>
+          sourceTableFromDocument(doc, context.connectionTag, syncConfig, mapping, eventById)
+        )
       };
     });
 
@@ -247,12 +256,13 @@ export class MongoBucketBatchV3 extends MongoBucketBatch {
       return null;
     }
 
-    const refreshed = sourceTableFromDocument(doc, table.ref.connectionTag, this.sync_rules, this.mapping);
-    // The event-carrier designation is decided per resolveTables result and not persisted -
-    // preserve the caller's designation instead of recomputing it from the ref, so that
-    // refreshing a non-carrier table does not make it fire events.
-    refreshed.syncEvent = table.syncEvent;
-    return refreshed;
+    return sourceTableFromDocument(
+      doc,
+      table.ref.connectionTag,
+      this.sync_rules,
+      this.mapping,
+      this.options.parsedSyncConfig.eventById
+    );
   }
 
   async commit(lsn: string, options?: storage.BucketBatchCommitOptions): Promise<storage.CheckpointResult> {
@@ -519,7 +529,7 @@ export class MongoBucketBatchV3 extends MongoBucketBatch {
             _id: { $ne: this.replicationStreamId },
             state: { $in: [storage.SyncRuleState.ACTIVE, storage.SyncRuleState.ERRORED] }
           },
-          syncRuleStateUpdatePipeline(storage.SyncRuleState.STOP),
+          stopReplicationStreamPipeline(),
           { session }
         );
         activated = true;
@@ -683,4 +693,96 @@ export class MongoBucketBatchV3 extends MongoBucketBatch {
       return copy;
     });
   }
+
+  protected override async batchCreateCustomWriteCheckpoints(
+    session: lib_mongo.mongo.ClientSession,
+    opId: InternalOpId
+  ): Promise<void> {
+    if (this.write_checkpoint_batch.length == 0) {
+      return;
+    }
+
+    const checkpointsByEvent = Map.groupBy(this.write_checkpoint_batch, (checkpoint) =>
+      this.validateCustomCheckpointEventId(checkpoint.event_id)
+    );
+
+    for (const [eventId, checkpoints] of checkpointsByEvent) {
+      await this.batchCreateEventCustomWriteCheckpoints(session, opId, eventId, checkpoints);
+    }
+  }
+
+  protected override async prepareCustomWriteCheckpoints(): Promise<void> {
+    // Most events never produce custom checkpoints, so create collections lazily
+    // only for the event ids present in this batch. This hook runs before the
+    // replication transaction because MongoDB cannot create indexes within it.
+    const eventIds = new Set(
+      this.write_checkpoint_batch.map((checkpoint) => this.validateCustomCheckpointEventId(checkpoint.event_id))
+    );
+    for (const eventId of eventIds) {
+      if (this.initializedCustomCheckpointEventIds.has(eventId)) {
+        continue;
+      }
+      await this.db.initializeCustomCheckpointRequestsCollection({
+        replicationStreamId: this.replicationStreamId,
+        eventId
+      });
+      this.initializedCustomCheckpointEventIds.add(eventId);
+    }
+  }
+
+  private validateCustomCheckpointEventId(eventId: EventDefinitionId | undefined): EventDefinitionId {
+    if (eventId == null) {
+      throw new ServiceAssertionError('V3 custom checkpoints require an event definition id');
+    }
+
+    if (!this.knownEventIds.has(eventId)) {
+      throw new ServiceAssertionError(`Unknown custom checkpoint event definition ${eventId}`);
+    }
+    return eventId;
+  }
+
+  private async batchCreateEventCustomWriteCheckpoints(
+    session: lib_mongo.mongo.ClientSession,
+    opId: InternalOpId,
+    eventId: EventDefinitionId,
+    checkpoints: storage.CustomWriteCheckpointOptions[]
+  ): Promise<void> {
+    await this.db
+      .customCheckpointRequests({
+        eventId,
+        replicationStreamId: this.replicationStreamId
+      })
+      .bulkWrite(
+        checkpoints.map((checkpointOptions) => {
+          const set: Partial<CustomCheckpointRequestDocumentV3> = {
+            user_id: checkpointOptions.user_id,
+            checkpoint: checkpointOptions.checkpoint,
+            op_id: opId
+          };
+          if (checkpointOptions.checkpoint_requested_at != null) {
+            set.checkpoint_requested_at = checkpointOptions.checkpoint_requested_at;
+          }
+
+          return {
+            updateOne: {
+              filter: {
+                user_id: checkpointOptions.user_id
+              },
+              update: {
+                $set: set,
+                ...(checkpointOptions.checkpoint_requested_at == null
+                  ? {
+                      $unset: {
+                        checkpoint_requested_at: 1
+                      }
+                    }
+                  : {})
+              },
+              upsert: true
+            }
+          };
+        }),
+        { session }
+      );
+  }
 }