@powersync/service-module-postgres-storage 0.0.0-dev-20260803144812 → 0.0.0-dev-20260929095716

package/src/storage/PostgresBucketStorageFactory.ts

@@ -15,6 +15,7 @@ export type PostgresBucketStorageOptions = {
   config: NormalizedPostgresStorageConfig;
   replicationStreamNamePrefix: string;
   checksumCacheTtlMs?: number;
+  defaultStorageVersion?: number;
 };
 
 export class PostgresBucketStorageFactory extends storage.BucketStorageFactory {
@@ -24,8 +25,11 @@ export class PostgresBucketStorageFactory extends storage.BucketStorageFactory {
 
   private activeStorageCache: storage.SyncRulesBucketStorage | undefined;
 
-  constructor(protected options: PostgresBucketStorageOptions) {
-    super();
+  constructor(
+    protected options: PostgresBucketStorageOptions,
+    syncConfigParser: storage.SyncConfigParser
+  ) {
+    super({ syncConfigParser });
     this.db = new lib_postgres.DatabaseClient({
       config: options.config,
       schema: STORAGE_SCHEMA_NAME,
@@ -40,7 +44,11 @@ export class PostgresBucketStorageFactory extends storage.BucketStorageFactory {
   }
 
   async [Symbol.asyncDispose]() {
-    await this.db[Symbol.asyncDispose]();
+    try {
+      await super[Symbol.asyncDispose]();
+    } finally {
+      await this.db[Symbol.asyncDispose]();
+    }
   }
 
   async prepareStatements(connection: pg_wire.PgConnection) {
@@ -78,7 +86,8 @@ export class PostgresBucketStorageFactory extends storage.BucketStorageFactory {
       return {
         operations_size_bytes: 0,
         parameters_size_bytes: 0,
-        replication_size_bytes: 0
+        replication_size_bytes: 0,
+        object_storage_size_bytes: 0
       };
     }
 
@@ -104,7 +113,8 @@ export class PostgresBucketStorageFactory extends storage.BucketStorageFactory {
     return {
       operations_size_bytes: Number(sizes!.operations_size_bytes),
       parameters_size_bytes: Number(sizes!.parameter_size_bytes),
-      replication_size_bytes: Number(sizes!.v1_current_size_bytes) + Number(sizes!.v3_current_size_bytes)
+      replication_size_bytes: Number(sizes!.v1_current_size_bytes) + Number(sizes!.v3_current_size_bytes),
+      object_storage_size_bytes: 0
     };
   }
 
@@ -156,12 +166,15 @@ export class PostgresBucketStorageFactory extends storage.BucketStorageFactory {
 
   async updateSyncRules(options: storage.UpdateSyncRulesOptions): Promise<PostgresPersistedReplicationStream> {
     const storageVersion =
-      options.storageVersion ?? options.config.parsed.config.storageVersion ?? storage.CURRENT_STORAGE_VERSION;
+      options.storageVersion ??
+      options.config.parsed.config.storageVersion ??
+      this.options.defaultStorageVersion ??
+      storage.CURRENT_STORAGE_VERSION;
     const storageConfig = storage.STORAGE_VERSION_CONFIG[storageVersion];
-    if (storageConfig == null) {
+    if (storageConfig == null || storageVersion >= storage.STORAGE_VERSION_4) {
       throw new framework.ServiceError(
         framework.ErrorCode.PSYNC_S1005,
-        `Unsupported storage version ${storageVersion}`
+        `Unsupported storage version ${storageVersion} for PostgreSQL storage`
       );
     }
     await this.initializeStorageVersion(storageConfig);
@@ -174,6 +187,7 @@ export class PostgresBucketStorageFactory extends storage.BucketStorageFactory {
           state = ${{ type: 'varchar', value: storage.SyncRuleState.PROCESSING }}
       `.execute();
 
+      // Uses the legacy sequence name "sync_rules_id_sequence" for backwards-compatibility. See AGENTS.md.
       const newSyncRulesRow = await db.sql`
         WITH
           next_id AS (
@@ -187,7 +201,8 @@ export class PostgresBucketStorageFactory extends storage.BucketStorageFactory {
             sync_plan,
             state,
             slot_name,
-            storage_version
+            storage_version,
+            version_label
           )
         VALUES
           (
@@ -211,7 +226,8 @@ export class PostgresBucketStorageFactory extends storage.BucketStorageFactory {
               '_',
               ${{ type: 'varchar', value: crypto.randomBytes(2).toString('hex') }}
             ),
-            ${{ type: 'int4', value: storageVersion }}
+            ${{ type: 'int4', value: storageVersion }},
+            ${{ type: 'varchar', value: options.version_label ?? null }}
           )
         RETURNING
           *
@@ -219,7 +235,7 @@ export class PostgresBucketStorageFactory extends storage.BucketStorageFactory {
         .decoded(models.SyncRules)
         .first();
 
-      return new PostgresPersistedReplicationStream(this.db, newSyncRulesRow!);
+      return new PostgresPersistedReplicationStream(this.db, newSyncRulesRow!, this.syncConfigParser);
     });
   }
 
@@ -353,7 +369,7 @@ export class PostgresBucketStorageFactory extends storage.BucketStorageFactory {
       .decoded(models.SyncRules)
       .rows();
 
-    return rows.map((row) => new PostgresPersistedReplicationStream(this.db, row));
+    return rows.map((row) => new PostgresPersistedReplicationStream(this.db, row, this.syncConfigParser));
   }
 
   async getStoppedReplicationStreams(): Promise<storage.PersistedReplicationStream[]> {
@@ -368,14 +384,14 @@ export class PostgresBucketStorageFactory extends storage.BucketStorageFactory {
       .decoded(models.SyncRules)
       .rows();
 
-    return rows.map((row) => new PostgresPersistedReplicationStream(this.db, row));
+    return rows.map((row) => new PostgresPersistedReplicationStream(this.db, row, this.syncConfigParser));
   }
 
   private resolvedSyncConfigFromRow(
     row: models.SyncRulesDecoded,
     options: { cacheActiveStorage?: boolean } = {}
   ): storage.ResolvedSyncConfig {
-    const stream = new PostgresPersistedReplicationStream(this.db, row);
+    const stream = new PostgresPersistedReplicationStream(this.db, row, this.syncConfigParser);
     const content = stream.syncConfigContent[0];
     const thisFactory = this;
 

package/src/storage/PostgresStorageProvider.ts

@@ -25,11 +25,15 @@ export class PostgresStorageProvider implements storage.StorageProvider {
 
     const decodedConfig = PostgresStorageConfig.decode(storage);
     const normalizedConfig = normalizePostgresStorageConfig(decodedConfig);
-    const storageFactory = new PostgresBucketStorageFactory({
-      config: normalizedConfig,
-      replicationStreamNamePrefix: options.resolvedConfig.slot_name_prefix,
-      checksumCacheTtlMs: options.resolvedConfig.api_parameters.bucket_count_cache_ttl_minutes * 60_000
-    });
+    const storageFactory = new PostgresBucketStorageFactory(
+      {
+        config: normalizedConfig,
+        replicationStreamNamePrefix: options.resolvedConfig.slot_name_prefix,
+        checksumCacheTtlMs: options.resolvedConfig.api_parameters.bucket_count_cache_ttl_minutes * 60_000,
+        defaultStorageVersion: decodedConfig.default_storage_version
+      },
+      options.syncConfigParser
+    );
 
     const reportStorageFactory = new PostgresReportStorage({
       config: normalizedConfig

package/src/storage/PostgresSyncRulesStorage.ts

@@ -4,6 +4,8 @@ import {
   BucketChecksum,
   CHECKPOINT_INVALIDATE_ALL,
   CheckpointChanges,
+  CompactInitialReplicationOptions,
+  CompactInitialReplicationResults,
   GetCheckpointChangesOptions,
   InternalOpId,
   internalToExternalOpId,
@@ -11,11 +13,10 @@ import {
   maxLsn,
   ParameterSetLimitExceededError,
   PartialChecksum,
-  PopulateChecksumCacheOptions,
-  PopulateChecksumCacheResults,
   ReplicationCheckpoint,
   storage,
   StorageVersionConfig,
+  SyncRuleState,
   utils,
   WatchWriteCheckpointOptions
 } from '@powersync/service-core';
@@ -94,7 +95,7 @@ export class PostgresSyncRulesStorage
     this.factory = options.factory;
     this.storageConfig = options.replicationStream.getStorageConfig();
     this.currentDataStore = new PostgresCurrentDataStore(this.storageConfig);
-    this.logger = options.replicationStream.logger;
+    this.logger = this.sync_rules.logger;
 
     this.writeCheckpointAPI = new PostgresWriteCheckpointAPI({
       db: this.db,
@@ -145,7 +146,19 @@ export class PostgresSyncRulesStorage
     `.execute();
   }
 
+  supportsIncrementalParameterCompaction(): boolean {
+    return false;
+  }
+
   async compact(options?: storage.CompactOptions): Promise<void> {
+    if (options?.incrementalOnly) {
+      // Not supported yet
+      this.logger.info('Incremental compacting is not supported on Postgres storage yet.');
+      return;
+    } else if (this.replicationStream.state != SyncRuleState.ACTIVE) {
+      this.logger.info(`Skipping compacting of replication stream in ${this.replicationStream.state} state.`);
+      return;
+    }
     let maxOpId = options?.maxOpId;
     if (maxOpId == null) {
       const checkpoint = await this.getCheckpoint();
@@ -160,7 +173,9 @@ export class PostgresSyncRulesStorage
     }).compact();
   }
 
-  async populatePersistentChecksumCache(_options: PopulateChecksumCacheOptions): Promise<PopulateChecksumCacheResults> {
+  async compactInitialReplication(
+    _options: CompactInitialReplicationOptions
+  ): Promise<CompactInitialReplicationResults> {
     // no-op - checksum cache is not implemented for Postgres yet
     return { buckets: 0 };
   }
@@ -172,8 +187,8 @@ export class PostgresSyncRulesStorage
     });
   }
 
-  setWriteCheckpointMode(mode: storage.WriteCheckpointMode): void {
-    return this.writeCheckpointAPI.setWriteCheckpointMode(mode);
+  setWriteCheckpointMode(config: storage.WriteCheckpointModeConfig): void {
+    return this.writeCheckpointAPI.setWriteCheckpointMode(config);
   }
 
   createManagedWriteCheckpoints(

package/src/storage/batch/PostgresBucketBatch.ts

@@ -19,6 +19,7 @@ import {
   utils
 } from '@powersync/service-core';
 import * as sync_rules from '@powersync/service-sync-rules';
+import { orNull } from '@powersync/service-types';
 import * as timers from 'timers/promises';
 import * as t from 'ts-codec';
 import * as uuid from 'uuid';
@@ -64,10 +65,10 @@ const StatefulCheckpoint = models.ActiveCheckpoint.and(t.object({ state: t.Enum(
 const CheckpointWithStatus = StatefulCheckpoint.and(
   t.object({
     snapshot_done: t.boolean,
-    no_checkpoint_before: t.string.or(t.Null),
+    no_checkpoint_before: orNull(t.string),
     can_checkpoint: t.boolean,
-    keepalive_op: bigint.or(t.Null),
-    new_last_checkpoint: bigint.or(t.Null),
+    keepalive_op: orNull(bigint),
+    new_last_checkpoint: orNull(bigint),
     created_checkpoint: t.boolean
   })
 );
@@ -144,6 +145,7 @@ export class PostgresBucketBatch
 
   async resolveTables(options: storage.ResolveTablesOptions): Promise<storage.ResolveTablesResult> {
     const syncRules = options.parsedSyncConfig?.hydratedSyncConfig ?? this.sync_rules;
+    const reconcile = options.reconcileSourceTables ?? storage.defaultSourceTableReconciler;
     const { connection_id, source } = options;
     const { schema, name: table, objectId, replicaIdColumns, connectionTag, sendsCompleteRows } = source;
 
@@ -154,9 +156,10 @@ export class PostgresBucketBatch
     }));
 
     return this.db.transaction(async (db) => {
-      let sourceTableRow: SourceTableDecoded | null;
+      // Find records that overlap by name or relation id.
+      let candidateRows: SourceTableDecoded[];
       if (objectId != null) {
-        sourceTableRow = await db.sql`
+        candidateRows = await db.sql`
           SELECT
             *
           FROM
@@ -164,15 +167,18 @@ export class PostgresBucketBatch
           WHERE
             group_id = ${{ type: 'int4', value: this.group_id }}
             AND connection_id = ${{ type: 'int4', value: connection_id }}
-            AND relation_id = ${{ type: 'jsonb', value: { object_id: objectId } satisfies StoredRelationId }}
-            AND schema_name = ${{ type: 'varchar', value: schema }}
-            AND table_name = ${{ type: 'varchar', value: table }}
-            AND replica_id_columns = ${{ type: 'jsonb', value: normalizedReplicaIdColumns }}
+            AND (
+              relation_id = ${{ type: 'jsonb', value: { object_id: objectId } satisfies StoredRelationId }}
+              OR (
+                schema_name = ${{ type: 'varchar', value: schema }}
+                AND table_name = ${{ type: 'varchar', value: table }}
+              )
+            )
         `
           .decoded(models.SourceTable)
-          .first();
+          .rows();
       } else {
-        sourceTableRow = await db.sql`
+        candidateRows = await db.sql`
           SELECT
             *
           FROM
@@ -182,15 +188,42 @@ export class PostgresBucketBatch
             AND connection_id = ${{ type: 'int4', value: connection_id }}
             AND schema_name = ${{ type: 'varchar', value: schema }}
             AND table_name = ${{ type: 'varchar', value: table }}
-            AND replica_id_columns = ${{ type: 'jsonb', value: normalizedReplicaIdColumns }}
         `
           .decoded(models.SourceTable)
-          .first();
+          .rows();
       }
 
-      if (sourceTableRow == null) {
+      const candidateTables = candidateRows.map((row) => {
+        const table = this.sourceTableFromRow(row, connectionTag, syncRules);
+        table.storeCurrentData = sendsCompleteRows !== true;
+        return table;
+      });
+      const candidates = candidateTables.map((table) => table.clone());
+      const resolution = await reconcile({ source, candidates });
+      storage.validateSourceTableCandidateResolution(candidates, resolution);
+
+      for (const { id, sourceMetadata } of storage.diffSourceTableUpdates(candidateTables, resolution)) {
+        await db.sql`
+          UPDATE source_tables
+          SET
+            source_metadata = ${{ type: 'jsonb', value: sourceMetadata ?? null }}
+          WHERE
+            id = ${{ type: 'varchar', value: id.toString() }}
+        `.execute();
+      }
+
+      const materializedResolution = storage.materializeSourceTableResolution(candidateTables, resolution);
+      const compatibleTables = materializedResolution.compatibleTables;
+
+      // Keep one record, preferring one that has already been snapshotted.
+      const reuse = compatibleTables.find((candidate) => candidate.snapshotComplete) ?? compatibleTables[0] ?? null;
+
+      let sourceTable: storage.SourceTable;
+      if (reuse != null) {
+        sourceTable = reuse;
+      } else {
         const id = options.idGenerator ? postgresTableId(options.idGenerator()) : uuid.v4();
-        sourceTableRow = await db.sql`
+        const insertedRow = await db.sql`
           INSERT INTO
             source_tables (
               id,
@@ -199,7 +232,8 @@ export class PostgresBucketBatch
               relation_id,
               schema_name,
               table_name,
-              replica_id_columns
+              replica_id_columns,
+              source_metadata
             )
           VALUES
             (
@@ -209,95 +243,27 @@ export class PostgresBucketBatch
               ${{ type: 'jsonb', value: { object_id: objectId } satisfies StoredRelationId }},
               ${{ type: 'varchar', value: schema }},
               ${{ type: 'varchar', value: table }},
-              ${{ type: 'jsonb', value: normalizedReplicaIdColumns }}
+              ${{ type: 'jsonb', value: normalizedReplicaIdColumns }},
+              ${{ type: 'jsonb', value: resolution.newTableValues.sourceMetadata ?? null }}
             )
           RETURNING
             *
         `
           .decoded(models.SourceTable)
           .first();
+        sourceTable = this.sourceTableFromRow(insertedRow!, connectionTag, syncRules);
+        sourceTable.storeCurrentData = sendsCompleteRows !== true;
       }
 
-      const sourceTable = new storage.SourceTable({
-        id: sourceTableRow!.id,
-        ref: source,
-        objectId,
-        replicaIdColumns,
-        snapshotComplete: sourceTableRow!.snapshot_done ?? true,
-        ...syncRules.getMatchingSources(source)
-      });
-      if (!sourceTable.snapshotComplete) {
-        sourceTable.snapshotStatus = {
-          totalEstimatedCount: Number(sourceTableRow!.snapshot_total_estimated_count ?? -1n),
-          replicatedCount: Number(sourceTableRow!.snapshot_replicated_count ?? 0n),
-          lastKey: sourceTableRow!.snapshot_last_key
-        };
-      }
-      sourceTable.syncEvent = syncRules.tableTriggersEvent(source);
-      sourceTable.syncData = sourceTable.bucketDataSources.length > 0;
-      sourceTable.syncParameters = sourceTable.parameterLookupSources.length > 0;
-      sourceTable.storeCurrentData = sendsCompleteRows !== true;
-
-      let truncatedTables: SourceTableDecoded[] = [];
-      if (objectId != null) {
-        truncatedTables = await db.sql`
-          SELECT
-            *
-          FROM
-            source_tables
-          WHERE
-            group_id = ${{ type: 'int4', value: this.group_id }}
-            AND connection_id = ${{ type: 'int4', value: connection_id }}
-            AND id != ${{ type: 'varchar', value: sourceTableRow!.id }}
-            AND (
-              relation_id = ${{ type: 'jsonb', value: { object_id: objectId } satisfies StoredRelationId }}
-              OR (
-                schema_name = ${{ type: 'varchar', value: schema }}
-                AND table_name = ${{ type: 'varchar', value: table }}
-              )
-            )
-        `
-          .decoded(models.SourceTable)
-          .rows();
-      } else {
-        truncatedTables = await db.sql`
-          SELECT
-            *
-          FROM
-            source_tables
-          WHERE
-            group_id = ${{ type: 'int4', value: this.group_id }}
-            AND connection_id = ${{ type: 'int4', value: connection_id }}
-            AND id != ${{ type: 'varchar', value: sourceTableRow!.id }}
-            AND (
-              schema_name = ${{ type: 'varchar', value: schema }}
-              AND table_name = ${{ type: 'varchar', value: table }}
-            )
-        `
-          .decoded(models.SourceTable)
-          .rows();
-      }
+      const dropTables = [
+        ...materializedResolution.incompatibleTables,
+        // PostgreSQL storage only keeps one SourceTable per physical table.
+        ...compatibleTables.filter((candidate) => !storage.sourceTableIdEquals(candidate.id, sourceTable.id))
+      ];
 
       return {
         tables: [sourceTable],
-        dropTables: truncatedTables.map((doc) => {
-          const ref = { connectionTag, schema: doc.schema_name, name: doc.table_name };
-          const dropTable = new storage.SourceTable({
-            id: doc.id,
-            ref,
-            objectId: doc.relation_id?.object_id ?? 0,
-            replicaIdColumns:
-              doc.replica_id_columns?.map(
-                (c) => ({ name: c.name, typeId: c.typeId, type: c.type }) satisfies ColumnDescriptor
-              ) ?? [],
-            snapshotComplete: doc.snapshot_done ?? true,
-            ...syncRules.getMatchingSources(ref)
-          });
-          dropTable.syncEvent = syncRules.tableTriggersEvent(ref);
-          dropTable.syncData = dropTable.bucketDataSources.length > 0;
-          dropTable.syncParameters = dropTable.parameterLookupSources.length > 0;
-          return dropTable;
-        })
+        dropTables
       };
     });
   }
@@ -334,9 +300,10 @@ export class PostgresBucketBatch
       objectId: row.relation_id?.object_id,
       replicaIdColumns:
         row.replica_id_columns?.map(
-          (c) => ({ name: c.name, typeId: c.typeId, type: c.type }) satisfies ColumnDescriptor
+          (column) => ({ name: column.name, typeId: column.type_oid, type: column.type }) satisfies ColumnDescriptor
         ) ?? [],
       snapshotComplete: row.snapshot_done ?? true,
+      sourceMetadata: row.source_metadata,
       ...syncRules.getMatchingSources(ref)
     });
 
@@ -357,7 +324,9 @@ export class PostgresBucketBatch
     // TODO maybe share with abstract class
     const { after, before, sourceTable, tag } = record;
     const storeCurrentData = this.options.store_current_data && sourceTable.storeCurrentData;
-    // Only the table designated as event carrier by resolveTables may fire events.
+    // PostgreSQL storage resolves each physical table to one SourceTable. syncEvent records whether
+    // that table matches any event definition; each matching definition is evaluated once here and
+    // may produce multiple payloads from its matching queries.
     if (sourceTable.syncEvent) {
       for (const event of this.getTableEvents(sourceTable)) {
         this.iterateListeners((cb) =>
@@ -1368,10 +1337,10 @@ export class PostgresBucketBatch
   }
 
   /**
-   * Gets relevant {@link SqlEventDescriptor}s for the given {@link SourceTable}
+   * Gets relevant {@link HydratedEventDescriptor}s for the given {@link SourceTable}
    * TODO maybe share this with an abstract class
    */
-  protected getTableEvents(table: storage.SourceTable): sync_rules.SqlEventDescriptor[] {
+  protected getTableEvents(table: storage.SourceTable): sync_rules.HydratedEventDescriptor[] {
     return this.sync_rules.eventDescriptors.filter((evt) =>
       [...evt.getSourceTables()].some((sourceTable) => sourceTable.matches(table.ref))
     );

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(

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

@@ -6,16 +6,21 @@ import { models } from '../../types/types.js';
 export class PostgresPersistedSyncConfigContent extends storage.PersistedSyncConfigContent {
   constructor(
     private db: lib_postgres.DatabaseClient,
-    row: models.SyncRulesDecoded
+    row: models.SyncRulesDecoded,
+    syncConfigParser: storage.SyncConfigParser
   ) {
-    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
-    });
+    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
+      },
+      syncConfigParser
+    );
   }
 
   async getSyncConfigStatus(): Promise<storage.PersistedSyncConfigStatus | null> {
@@ -53,7 +58,8 @@ export class PostgresPersistedReplicationStream extends storage.PersistedReplica
 
   constructor(
     private db: lib_postgres.DatabaseClient,
-    private readonly row: models.SyncRulesDecoded
+    private readonly row: models.SyncRulesDecoded,
+    private readonly syncConfigParser: storage.SyncConfigParser
   ) {
     super({
       replicationStreamId: Number(row.id),
@@ -61,7 +67,13 @@ export class PostgresPersistedReplicationStream extends storage.PersistedReplica
       state: row.state as storage.SyncRuleState,
       storageVersion: row.storage_version ?? storage.LEGACY_STORAGE_VERSION
     });
-    this.syncConfigContent = [new PostgresPersistedSyncConfigContent(this.db, this.row)];
+    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, this.syncConfigParser)];
   }
 
   parsed(options: storage.ParseSyncConfigOptions): storage.ParsedSyncConfigSet {
@@ -71,6 +83,7 @@ export class PostgresPersistedReplicationStream extends storage.PersistedReplica
   async lock(): Promise<storage.ReplicationLock> {
     const manager = new lib_postgres.PostgresLockManager({
       db: this.db,
+      // Uses the legacy "sync_rules_" lock name prefix for backwards-compatibility. See AGENTS.md.
       name: `sync_rules_${this.replicationStreamId}_${this.replicationStreamName}`
     });
     const lockHandle = await manager.acquire();

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>;