@powersync/service-module-postgres-storage 0.0.0-dev-20260602073133 → 0.0.0-dev-20260909133214

package/src/storage/checkpoints/PostgresWriteCheckpointAPI.ts

@@ -21,8 +21,8 @@ export class PostgresWriteCheckpointAPI implements storage.WriteCheckpointAPI {
     return this._mode;
   }
 
-  setWriteCheckpointMode(mode: storage.WriteCheckpointMode): void {
-    this._mode = mode;
+  setWriteCheckpointMode(config: storage.WriteCheckpointModeConfig): void {
+    this._mode = config.mode;
   }
 
   async batchCreateCustomWriteCheckpoints(
@@ -32,32 +32,172 @@ export class PostgresWriteCheckpointAPI implements storage.WriteCheckpointAPI {
     return batchCreateCustomWriteCheckpoints(this.db, checkpoints);
   }
 
-  async createManagedWriteCheckpoint(checkpoint: storage.ManagedWriteCheckpointOptions): Promise<bigint> {
+  async createManagedWriteCheckpoints(
+    checkpoints: storage.ManagedWriteCheckpointOptions[]
+  ): Promise<storage.CreateManagedWriteCheckpointsResult> {
     if (this.writeCheckpointMode !== storage.WriteCheckpointMode.MANAGED) {
       throw new framework.errors.ValidationError(
         `Attempting to create a managed Write Checkpoint when the current Write Checkpoint mode is set to "${this.writeCheckpointMode}"`
       );
     }
 
-    const row = await this.db.sql`
-      INSERT INTO
-        write_checkpoints (user_id, lsns, write_checkpoint)
-      VALUES
-        (
-          ${{ type: 'varchar', value: checkpoint.user_id }},
-          ${{ type: 'jsonb', value: checkpoint.heads }},
-          ${{ type: 'int8', value: 1 }}
-        )
-      ON CONFLICT (user_id) DO UPDATE
-      SET
-        write_checkpoint = write_checkpoints.write_checkpoint + 1,
-        lsns = EXCLUDED.lsns
-      RETURNING
-        *;
-    `
-      .decoded(models.WriteCheckpoint)
-      .first();
-    return row!.write_checkpoint;
+    const uniqueCheckpoints = storage.uniqueManagedWriteCheckpoints(checkpoints);
+    if (uniqueCheckpoints.length == 0) {
+      return { writeCheckpoints: new Map(), shouldAdvance: false };
+    }
+
+    const writeCheckpoints = new Map<string, bigint>();
+    const generatedCheckpoints = uniqueCheckpoints.filter((checkpoint) => checkpoint.checkpoint_request_id == null);
+    const suppliedCheckpoints = uniqueCheckpoints.filter((checkpoint) => checkpoint.checkpoint_request_id != null);
+
+    if (generatedCheckpoints.length > 0) {
+      const mappedCheckpoints = generatedCheckpoints.map((checkpoint) => ({
+        user_id: checkpoint.user_id,
+        lsns: checkpoint.heads
+      }));
+
+      const generatedRows = await this.db.sql`
+        WITH
+          json_data AS (
+            SELECT
+            CHECKPOINT ->> 'user_id' AS user_id,
+            CHECKPOINT -> 'lsns' AS lsns
+            FROM
+              jsonb_array_elements(${{ type: 'jsonb', value: mappedCheckpoints }}) AS
+            CHECKPOINT
+          )
+        INSERT INTO
+          write_checkpoints (
+            user_id,
+            lsns,
+            write_checkpoint,
+            checkpoint_requested_at
+          )
+        SELECT
+          user_id,
+          lsns,
+          1,
+          NULL
+        FROM
+          json_data
+        ON CONFLICT (user_id) DO UPDATE
+        SET
+          write_checkpoint = write_checkpoints.write_checkpoint + 1,
+          lsns = EXCLUDED.lsns,
+          checkpoint_requested_at = NULL
+        RETURNING
+          *;
+      `
+        .decoded(models.WriteCheckpoint)
+        .rows();
+
+      for (const row of generatedRows) {
+        writeCheckpoints.set(row.user_id, row.write_checkpoint);
+      }
+    }
+
+    if (suppliedCheckpoints.length > 0) {
+      // Supplied request ids are monotonic. Greater values update the checkpoint
+      // id and heads, while equal retries only refresh the retention timestamp.
+      // Stale requests return the stored id without changing the row.
+      const mappedCheckpoints = suppliedCheckpoints.map((checkpoint) => ({
+        user_id: checkpoint.user_id,
+        lsns: checkpoint.heads,
+        checkpoint_request_id: String(checkpoint.checkpoint_request_id)
+      }));
+
+      const suppliedRows = await this.db.sql`
+        WITH
+          json_data AS (
+            SELECT
+            CHECKPOINT ->> 'user_id' AS user_id,
+            CHECKPOINT -> 'lsns' AS lsns,
+            (
+              CHECKPOINT ->> 'checkpoint_request_id'
+            )::int8 AS checkpoint_request_id
+            FROM
+              jsonb_array_elements(${{ type: 'jsonb', value: mappedCheckpoints }}) AS
+            CHECKPOINT
+          )
+        INSERT INTO
+          write_checkpoints (
+            user_id,
+            lsns,
+            write_checkpoint,
+            checkpoint_requested_at
+          )
+        SELECT
+          user_id,
+          lsns,
+          checkpoint_request_id,
+          NOW()
+        FROM
+          json_data
+        ON CONFLICT (user_id) DO UPDATE
+        SET
+          write_checkpoint = CASE
+            WHEN EXCLUDED.write_checkpoint > write_checkpoints.write_checkpoint THEN EXCLUDED.write_checkpoint
+            ELSE write_checkpoints.write_checkpoint
+          END,
+          lsns = CASE
+            WHEN EXCLUDED.write_checkpoint > write_checkpoints.write_checkpoint THEN EXCLUDED.lsns
+            ELSE write_checkpoints.lsns
+          END,
+          checkpoint_requested_at = NOW()
+        WHERE
+          EXCLUDED.write_checkpoint >= write_checkpoints.write_checkpoint
+        RETURNING
+          *;
+      `
+        .decoded(models.WriteCheckpoint)
+        .rows();
+
+      for (const row of suppliedRows) {
+        writeCheckpoints.set(row.user_id, row.write_checkpoint);
+      }
+
+      // RETURNING only excludes stale requests rejected by the monotonic
+      // conflict condition. Those requests still need the stored id.
+      const returnedSuppliedUserIds = new Set(suppliedRows.map((row) => row.user_id));
+      const unchangedUserIds = suppliedCheckpoints
+        .map((checkpoint) => checkpoint.user_id)
+        .filter((userId) => !returnedSuppliedUserIds.has(userId));
+
+      if (unchangedUserIds.length > 0) {
+        const mappedUserIds = unchangedUserIds.map((user_id) => ({ user_id }));
+        const unchangedRows = await this.db.sql`
+          WITH
+            json_data AS (
+              SELECT
+              CHECKPOINT ->> 'user_id' AS user_id
+              FROM
+                jsonb_array_elements(${{ type: 'jsonb', value: mappedUserIds }}) AS
+              CHECKPOINT
+            )
+          SELECT
+            write_checkpoints.*
+          FROM
+            write_checkpoints
+            JOIN json_data ON write_checkpoints.user_id = json_data.user_id;
+        `
+          .decoded(models.WriteCheckpoint)
+          .rows();
+
+        for (const row of unchangedRows) {
+          writeCheckpoints.set(row.user_id, row.write_checkpoint);
+        }
+      }
+    }
+
+    // Postgres storage does not track a per-row processed indicator: a write
+    // checkpoint is considered processed at read time by comparing its lsns
+    // against the replicated head (see lastManagedWriteCheckpoint). We therefore
+    // force the source marker whenever any checkpoint was matched, which also
+    // covers stale or duplicate requests whose stored checkpoint may still be
+    // pending. Forcing a marker for an already-processed checkpoint is wasteful
+    // but harmless.
+    const shouldAdvance = generatedCheckpoints.length > 0 || suppliedCheckpoints.length > 0;
+    return { writeCheckpoints, shouldAdvance };
   }
 
   async lastWriteCheckpoint(filters: storage.LastWriteCheckpointFilters): Promise<bigint | null> {
@@ -133,7 +273,8 @@ export async function batchCreateCustomWriteCheckpoints(
       // Cannot encode bigint directly using JSON.stringify.
       // The ::int8 in the query below will take care of casting back to a number
       checkpoint: String(cp.checkpoint),
-      sync_rules_id: cp.sync_rules_id
+      sync_rules_id: cp.sync_rules_id,
+      checkpoint_requested_at: cp.checkpoint_requested_at?.toISOString() ?? null
     };
   });
 
@@ -145,7 +286,12 @@ export async function batchCreateCustomWriteCheckpoints(
         CHECKPOINT
       )
     INSERT INTO
-      custom_write_checkpoints (user_id, write_checkpoint, sync_rules_id)
+      custom_write_checkpoints (
+        user_id,
+        write_checkpoint,
+        sync_rules_id,
+        checkpoint_requested_at
+      )
     SELECT
     CHECKPOINT ->> 'user_id'::varchar,
     (
@@ -153,11 +299,15 @@ export async function batchCreateCustomWriteCheckpoints(
     )::int8,
     (
       CHECKPOINT ->> 'sync_rules_id'
-    )::int4
+    )::int4,
+    (
+      CHECKPOINT ->> 'checkpoint_requested_at'
+    )::timestamptz
     FROM
       json_data
     ON CONFLICT (user_id, sync_rules_id) DO UPDATE
     SET
-      write_checkpoint = EXCLUDED.write_checkpoint;
+      write_checkpoint = EXCLUDED.write_checkpoint,
+      checkpoint_requested_at = EXCLUDED.checkpoint_requested_at;
   `.execute();
 }

package/src/storage/current-data-store.ts

@@ -301,19 +301,74 @@ export class PostgresCurrentDataStore {
     `.execute();
   }
 
-  async deleteGroupRows(db: Queryable, options: { groupId: number }) {
+  /**
+   * Delete up to `limit` rows for the group, returning the number of candidate
+   * rows found by the scan (see PostgresSyncRulesStorage#deleteGroupBatch for
+   * why the scan is counted rather than the delete).
+   */
+  async deleteGroupRowsBatch(db: Queryable, options: { groupId: number; limit: number }): Promise<bigint> {
     if (this.softDeleteEnabled) {
-      await db.sql`
-        DELETE FROM v3_current_data
-        WHERE
-          group_id = ${{ type: 'int4', value: options.groupId }}
-      `.execute();
+      const result = await db.sql`
+        WITH
+          batch AS (
+            SELECT
+              ctid
+            FROM
+              v3_current_data
+            WHERE
+              group_id = ${{ type: 'int4', value: options.groupId }}
+            LIMIT
+              ${{ type: 'int4', value: options.limit }}
+          ),
+          deleted AS (
+            DELETE FROM v3_current_data
+            WHERE
+              ctid IN (
+                SELECT
+                  ctid
+                FROM
+                  batch
+              )
+            RETURNING
+              1
+          )
+        SELECT
+          COUNT(*) AS count
+        FROM
+          batch
+      `.first<{ count: bigint }>();
+      return result?.count ?? 0n;
     } else {
-      await db.sql`
-        DELETE FROM current_data
-        WHERE
-          group_id = ${{ type: 'int4', value: options.groupId }}
-      `.execute();
+      const result = await db.sql`
+        WITH
+          batch AS (
+            SELECT
+              ctid
+            FROM
+              current_data
+            WHERE
+              group_id = ${{ type: 'int4', value: options.groupId }}
+            LIMIT
+              ${{ type: 'int4', value: options.limit }}
+          ),
+          deleted AS (
+            DELETE FROM current_data
+            WHERE
+              ctid IN (
+                SELECT
+                  ctid
+                FROM
+                  batch
+              )
+            RETURNING
+              1
+          )
+        SELECT
+          COUNT(*) AS count
+        FROM
+          batch
+      `.first<{ count: bigint }>();
+      return result?.count ?? 0n;
     }
   }
 

package/src/storage/storage-index.ts

@@ -1,4 +1,5 @@
 export * from './PostgresBucketStorageFactory.js';
 export * from './PostgresCompactor.js';
+export * from './PostgresReportStorage.js';
 export * from './PostgresStorageProvider.js';
 export * from './PostgresSyncRulesStorage.js';

package/src/storage/sync-rules/PostgresPersistedSyncConfigContent.ts

@@ -0,0 +1,105 @@
+import * as lib_postgres from '@powersync/lib-service-postgres';
+import { ErrorCode, ServiceError } from '@powersync/lib-services-framework';
+import { storage } from '@powersync/service-core';
+import { models } from '../../types/types.js';
+
+export class PostgresPersistedSyncConfigContent extends storage.PersistedSyncConfigContent {
+  constructor(
+    private db: lib_postgres.DatabaseClient,
+    row: models.SyncRulesDecoded
+  ) {
+    super({
+      replicationStreamId: Number(row.id),
+      sync_rules_content: row.content,
+      compiled_plan: row.sync_plan,
+      replicationStreamName: row.slot_name,
+      storageVersion: row.storage_version ?? storage.LEGACY_STORAGE_VERSION,
+      syncConfigState: row.state as storage.SyncRuleState,
+      version_label: row.version_label ?? undefined
+    });
+  }
+
+  async getSyncConfigStatus(): Promise<storage.PersistedSyncConfigStatus | null> {
+    const row = await this.db.sql`
+      SELECT
+        *
+      FROM
+        sync_rules
+      WHERE
+        id = ${{ value: this.replicationStreamId, type: 'int4' }}
+    `
+      .decoded(models.SyncRules)
+      .first();
+
+    return row == null ? null : syncConfigStatusFromRow(row);
+  }
+}
+
+function syncConfigStatusFromRow(row: models.SyncRulesDecoded): storage.PersistedSyncConfigStatus {
+  return {
+    id: String(row.id),
+    replicationStreamId: Number(row.id),
+    state: row.state as storage.SyncRuleState,
+    snapshot_done: row.snapshot_done,
+    last_checkpoint_lsn: row.last_checkpoint_lsn,
+    last_fatal_error: row.last_fatal_error,
+    last_keepalive_ts: row.last_keepalive_ts ? new Date(row.last_keepalive_ts) : null,
+    last_checkpoint_ts: row.last_checkpoint_ts ? new Date(row.last_checkpoint_ts) : null
+  };
+}
+
+export class PostgresPersistedReplicationStream extends storage.PersistedReplicationStream {
+  current_lock: storage.ReplicationLock | null = null;
+  readonly syncConfigContent: readonly PostgresPersistedSyncConfigContent[];
+
+  constructor(
+    private db: lib_postgres.DatabaseClient,
+    private readonly row: models.SyncRulesDecoded
+  ) {
+    super({
+      replicationStreamId: Number(row.id),
+      replicationStreamName: row.slot_name,
+      state: row.state as storage.SyncRuleState,
+      storageVersion: row.storage_version ?? storage.LEGACY_STORAGE_VERSION
+    });
+    if (this.storageVersion >= storage.STORAGE_VERSION_4) {
+      throw new ServiceError(
+        ErrorCode.PSYNC_S1005,
+        `Unsupported storage version ${this.storageVersion} for PostgreSQL storage`
+      );
+    }
+    this.syncConfigContent = [new PostgresPersistedSyncConfigContent(this.db, this.row)];
+  }
+
+  parsed(options: storage.ParseSyncConfigOptions): storage.ParsedSyncConfigSet {
+    return this.syncConfigContent[0].parsed(options);
+  }
+
+  async lock(): Promise<storage.ReplicationLock> {
+    const manager = new lib_postgres.PostgresLockManager({
+      db: this.db,
+      name: `sync_rules_${this.replicationStreamId}_${this.replicationStreamName}`
+    });
+    const lockHandle = await manager.acquire();
+    if (!lockHandle) {
+      throw new ServiceError(ErrorCode.PSYNC_S1003, `Replication stream is locked by another process, standing by.`);
+    }
+
+    const interval = setInterval(async () => {
+      try {
+        await lockHandle.refresh();
+      } catch (e) {
+        this.logger.error('Failed to refresh lock', e);
+        clearInterval(interval);
+      }
+    }, 30_130);
+
+    return (this.current_lock = {
+      sync_rules_id: this.replicationStreamId,
+      release: async () => {
+        clearInterval(interval);
+        return lockHandle.release();
+      }
+    });
+  }
+}

package/src/types/models/ActiveCheckpoint.ts

@@ -1,3 +1,4 @@
+import { orNull } from '@powersync/service-types';
 import * as t from 'ts-codec';
 import { bigint, pgwire_number } from '../codecs.js';
 
@@ -7,8 +8,8 @@ import { bigint, pgwire_number } from '../codecs.js';
  */
 export const ActiveCheckpoint = t.object({
   id: pgwire_number,
-  last_checkpoint: t.Null.or(bigint),
-  last_checkpoint_lsn: t.Null.or(t.string)
+  last_checkpoint: orNull(bigint),
+  last_checkpoint_lsn: orNull(t.string)
 });
 
 export type ActiveCheckpoint = t.Encoded<typeof ActiveCheckpoint>;

package/src/types/models/BucketData.ts

@@ -1,3 +1,4 @@
+import { orNull } from '@powersync/service-types';
 import * as t from 'ts-codec';
 import { bigint, hexBuffer, pgwire_number } from '../codecs.js';
 
@@ -13,13 +14,13 @@ export const BucketData = t.object({
   bucket_name: t.string,
   op_id: bigint,
   op: t.Enum(OpType),
-  source_table: t.Null.or(t.string),
-  source_key: t.Null.or(hexBuffer),
-  table_name: t.string.or(t.Null),
-  row_id: t.string.or(t.Null),
+  source_table: orNull(t.string),
+  source_key: orNull(hexBuffer),
+  table_name: orNull(t.string),
+  row_id: orNull(t.string),
   checksum: bigint,
-  data: t.Null.or(t.string),
-  target_op: t.Null.or(bigint)
+  data: orNull(t.string),
+  target_op: orNull(bigint)
 });
 
 export type BucketData = t.Encoded<typeof BucketData>;

package/src/types/models/CurrentData.ts

@@ -1,3 +1,4 @@
+import { orNull } from '@powersync/service-types';
 import * as t from 'ts-codec';
 import { bigint, hexBuffer, jsonb, pgwire_number } from '../codecs.js';
 
@@ -26,7 +27,7 @@ export const V3CurrentData = t.object({
   lookups: t.array(hexBuffer),
   source_key: hexBuffer,
   source_table: t.string,
-  pending_delete: t.Null.or(bigint)
+  pending_delete: orNull(bigint)
 });
 
 export type V1CurrentData = t.Encoded<typeof V1CurrentData>;

package/src/types/models/SdkReporting.ts

@@ -1,3 +1,4 @@
+import { orNull } from '@powersync/service-types';
 import * as t from 'ts-codec';
 import { bigint, jsonb } from '../codecs.js';
 
@@ -11,12 +12,11 @@ export type Sdks = t.Encoded<typeof Sdks>;
 
 export const SdkReporting = t.object({
   users: bigint,
-  sdks: t
-    .object({
+  sdks: orNull(
+    t.object({
       data: jsonb<Sdks[]>(t.array(Sdks))
     })
-    .optional()
-    .or(t.Null)
+  ).optional()
 });
 
 export type SdkReporting = t.Encoded<typeof SdkReporting>;

package/src/types/models/SourceTable.ts

@@ -1,3 +1,5 @@
+import { JsonValue } from '@powersync/service-core';
+import { orNull } from '@powersync/service-types';
 import * as t from 'ts-codec';
 import { bigint, hexBuffer, jsonb, jsonb_raw, pgwire_number } from '../codecs.js';
 
@@ -14,21 +16,25 @@ export const ColumnDescriptor = t.object({
   /**
    *  Some data sources have a type id that can be used to identify the type of the column
    */
-  typeId: t.number.optional()
+  type_oid: t.number.optional()
 });
 
 export const SourceTable = t.object({
   id: t.string,
   group_id: pgwire_number,
   connection_id: bigint,
-  relation_id: t.Null.or(jsonb_raw<StoredRelationId>()),
+  relation_id: orNull(jsonb_raw<StoredRelationId>()),
   schema_name: t.string,
   table_name: t.string,
-  replica_id_columns: t.Null.or(jsonb(t.array(ColumnDescriptor))),
+  replica_id_columns: orNull(jsonb(t.array(ColumnDescriptor))),
   snapshot_done: t.boolean,
-  snapshot_total_estimated_count: t.Null.or(bigint),
-  snapshot_replicated_count: t.Null.or(bigint),
-  snapshot_last_key: t.Null.or(hexBuffer)
+  snapshot_total_estimated_count: orNull(bigint),
+  snapshot_replicated_count: orNull(bigint),
+  snapshot_last_key: orNull(hexBuffer),
+  /**
+   * Source-specific metadata. Null for legacy records.
+   */
+  source_metadata: orNull(jsonb_raw<JsonValue>())
 });
 
 export type SourceTable = t.Encoded<typeof SourceTable>;

package/src/types/models/SyncRules.ts

@@ -1,5 +1,5 @@
 import { framework, storage } from '@powersync/service-core';
-import { ReplicationError } from '@powersync/service-types';
+import { orNull, ReplicationError } from '@powersync/service-types';
 import * as t from 'ts-codec';
 import { bigint, pgwire_number } from '../codecs.js';
 import { jsonContainerObject } from './json.js';
@@ -16,42 +16,43 @@ export const SyncRules = t.object({
   /**
    * May be set if snapshot_done = false, if the replication stream requires it.
    */
-  snapshot_lsn: t.Null.or(t.string),
+  snapshot_lsn: orNull(t.string),
   /**
    * The last consistent checkpoint.
    *
    * There may be higher OpIds used in the database if we're in the middle of replicating a large transaction.
    */
-  last_checkpoint: t.Null.or(bigint),
+  last_checkpoint: orNull(bigint),
   /**
    * The LSN associated with the last consistent checkpoint.
    */
-  last_checkpoint_lsn: t.Null.or(t.string),
+  last_checkpoint_lsn: orNull(t.string),
   /**
    * If set, no new checkpoints may be created < this value.
    */
-  no_checkpoint_before: t.Null.or(t.string),
+  no_checkpoint_before: orNull(t.string),
   slot_name: t.string,
   /**
    * Last time we persisted a checkpoint.
    *
    * This may be old if no data is incoming.
    */
-  last_checkpoint_ts: t.Null.or(framework.codecs.date),
+  last_checkpoint_ts: orNull(framework.codecs.date),
   /**
    * Last time we persisted a checkpoint or keepalive.
    *
    * This should stay fairly current while replicating.
    */
-  last_keepalive_ts: t.Null.or(framework.codecs.date),
+  last_keepalive_ts: orNull(framework.codecs.date),
   /**
    * If an error is stopping replication, it will be stored here.
    */
-  last_fatal_error: t.Null.or(t.string),
-  keepalive_op: t.Null.or(bigint),
-  storage_version: t.Null.or(pgwire_number).optional(),
+  last_fatal_error: orNull(t.string),
+  keepalive_op: orNull(bigint),
+  storage_version: orNull(pgwire_number).optional(),
+  version_label: orNull(t.string).optional(),
   content: t.string,
-  sync_plan: t.Null.or(
+  sync_plan: orNull(
     jsonContainerObject(
       t.object({
         plan: t.any,

package/src/types/models/WriteCheckpoint.ts

@@ -1,10 +1,13 @@
+import { framework } from '@powersync/service-core';
+import { orNull } from '@powersync/service-types';
 import * as t from 'ts-codec';
 import { bigint, jsonb } from '../codecs.js';
 
 export const WriteCheckpoint = t.object({
   user_id: t.string,
   lsns: jsonb(t.record(t.string)),
-  write_checkpoint: bigint
+  write_checkpoint: bigint,
+  checkpoint_requested_at: orNull(framework.codecs.date)
 });
 
 export type WriteCheckpoint = t.Encoded<typeof WriteCheckpoint>;
@@ -13,7 +16,8 @@ export type WriteCheckpointDecoded = t.Decoded<typeof WriteCheckpoint>;
 export const CustomWriteCheckpoint = t.object({
   user_id: t.string,
   write_checkpoint: bigint,
-  sync_rules_id: bigint
+  sync_rules_id: bigint,
+  checkpoint_requested_at: orNull(framework.codecs.date)
 });
 
 export type CustomWriteCheckpoint = t.Encoded<typeof CustomWriteCheckpoint>;

package/src/utils/checkpoints.ts

@@ -0,0 +1,31 @@
+import * as lib_postgres from '@powersync/lib-service-postgres';
+import { storage } from '@powersync/service-core';
+import { models } from '../types/types.js';
+
+/**
+ * Gets the latest active checkpoint document.
+ * This is mainly exported for mocking in tests.
+ */
+export async function getActiveCheckpointDocument({
+  db
+}: {
+  db: lib_postgres.DatabaseClient;
+}): Promise<models.ActiveCheckpointDecoded | null> {
+  return db.sql`
+    SELECT
+      id,
+      last_checkpoint,
+      last_checkpoint_lsn
+    FROM
+      sync_rules
+    WHERE
+      state = ${{ value: storage.SyncRuleState.ACTIVE, type: 'varchar' }}
+      OR state = ${{ value: storage.SyncRuleState.ERRORED, type: 'varchar' }}
+    ORDER BY
+      id DESC
+    LIMIT
+      1
+  `
+    .decoded(models.ActiveCheckpoint)
+    .first();
+}