@powersync/service-module-mysql 0.14.3 → 0.16.0

package/src/common/ReplicatedGTID.ts

@@ -1,3 +1,4 @@
+import { ReplicationAssertionError } from '@powersync/lib-services-framework';
 import mysql from 'mysql2/promise';
 import * as uuid from 'uuid';
 import * as mysql_utils from '../utils/mysql-utils.js';
@@ -8,7 +9,11 @@ export type BinLogPosition = {
 };
 
 export type ReplicatedGTIDSpecification = {
-  raw_gtid: string;
+  /**
+   * The raw Global Transaction ID. This is of the format `server_uuid:transaction_id`.
+   * Must be a single GTID — not a GTID set (multiple UUIDs) or interval range.
+   */
+  rawGtid: string;
   /**
    * The (end) position in a BinLog file where this transaction has been replicated in.
    */
@@ -16,12 +21,12 @@ export type ReplicatedGTIDSpecification = {
 };
 
 export type BinLogGTIDFormat = {
-  server_id: Buffer;
-  transaction_range: number;
+  serverUuid: Buffer;
+  transactionId: number;
 };
 
 export type BinLogGTIDEvent = {
-  raw_gtid: BinLogGTIDFormat;
+  rawGtid: BinLogGTIDFormat;
   position: BinLogPosition;
 };
 
@@ -31,30 +36,43 @@ export type BinLogGTIDEvent = {
  * and position where this GTID could be located.
  */
 export class ReplicatedGTID {
+  private options: ReplicatedGTIDSpecification;
+
+  constructor(options: ReplicatedGTIDSpecification) {
+    const rawGtid = options.rawGtid.trim();
+    assertSingleGtid(rawGtid);
+    this.options = { ...options, rawGtid };
+  }
+
   static fromSerialized(comparable: string): ReplicatedGTID {
     return new ReplicatedGTID(ReplicatedGTID.deserialize(comparable));
   }
 
   private static deserialize(comparable: string): ReplicatedGTIDSpecification {
     const components = comparable.split('|');
-    if (components.length < 3) {
-      throw new Error(`Invalid serialized GTID: ${comparable}`);
+    if (components.length < 4) {
+      throw new ReplicationAssertionError(`Invalid serialized GTID: ${comparable}`);
+    }
+
+    const offset = parseInt(components[3], 10);
+    if (Number.isNaN(offset)) {
+      throw new ReplicationAssertionError(`Invalid BinLog offset in serialized GTID: ${comparable}`);
     }
 
     return {
-      raw_gtid: components[1],
+      rawGtid: components[1],
       position: {
         filename: components[2],
-        offset: parseInt(components[3])
+        offset: offset
       } satisfies BinLogPosition
     };
   }
 
   static fromBinLogEvent(event: BinLogGTIDEvent) {
-    const { raw_gtid, position } = event;
-    const stringGTID = `${uuid.stringify(raw_gtid.server_id)}:${raw_gtid.transaction_range}`;
+    const { rawGtid, position } = event;
+    const stringGTID = `${uuid.stringify(rawGtid.serverUuid)}:${rawGtid.transactionId}`;
     return new ReplicatedGTID({
-      raw_gtid: stringGTID,
+      rawGtid: stringGTID,
       position
     });
   }
@@ -62,9 +80,12 @@ export class ReplicatedGTID {
   /**
    * Special case for the zero GTID which means no transactions have been executed.
    */
-  static ZERO = new ReplicatedGTID({ raw_gtid: '0:0', position: { filename: '', offset: 0 } });
-
-  constructor(protected options: ReplicatedGTIDSpecification) {}
+  static ZERO(serverUuid: string): ReplicatedGTID {
+    return new ReplicatedGTID({
+      rawGtid: `${serverUuid}:0`,
+      position: { filename: '', offset: 0 }
+    });
+  }
 
   /**
    * Get the BinLog position of this replicated GTID event
@@ -74,14 +95,17 @@ export class ReplicatedGTID {
   }
 
   /**
-   * Get the raw Global Transaction ID. This of the format `server_id:transaction_ranges`
+   * Get the raw Global Transaction ID. This is of the format `server_uuid:transaction_id`
    */
   get raw() {
-    return this.options.raw_gtid;
+    return this.options.rawGtid;
   }
 
-  get serverId() {
-    return this.options.raw_gtid.split(':')[0];
+  /**
+   * The server UUID of the server this transaction originated from
+   */
+  get serverUuid() {
+    return this.options.rawGtid.split(':')[0];
   }
 
   /**
@@ -94,21 +118,9 @@ export class ReplicatedGTID {
    */
   get comparable(): string {
     const { raw, position } = this;
-    const [, transactionRanges] = this.raw.split(':');
+    const [, transactionId] = this.raw.split(':');
 
-    // This means no transactions have been executed on the database yet
-    if (!transactionRanges) {
-      return ReplicatedGTID.ZERO.comparable;
-    }
-
-    let maxTransactionId = 0;
-
-    for (const range of transactionRanges.split(',')) {
-      const [start, end] = range.split('-');
-      maxTransactionId = Math.max(maxTransactionId, parseInt(start, 10), parseInt(end || start, 10));
-    }
-
-    const paddedTransactionId = maxTransactionId.toString().padStart(16, '0');
+    const paddedTransactionId = transactionId.toString().padStart(16, '0');
     return [paddedTransactionId, raw, position.filename, position.offset].join('|');
   }
 
@@ -161,3 +173,24 @@ export class ReplicatedGTID {
     );
   }
 }
+
+/**
+ * Asserts that the given gtid string is a single GTID of the form `server_uuid:transaction_id`,
+ * not a GTID set such as `uuid:1-17` or `uuid1:1,uuid2:2`.
+ */
+function assertSingleGtid(gtid: string): void {
+  // GTID sets join UUID sets with commas (often with newlines: `,\n`).
+  if (gtid.includes(',') || gtid.includes('\n')) {
+    throw new ReplicationAssertionError(`Expected a single GTID (server_uuid:transaction_id), got a GTID set: ${gtid}`);
+  }
+
+  const parts = gtid.split(':');
+  if (parts.length !== 2 || parts[0].length === 0 || parts[1].length === 0) {
+    throw new ReplicationAssertionError(`Expected a single GTID (server_uuid:transaction_id), got: ${gtid}`);
+  }
+
+  // Intervals use `n-m`; a single transaction id must be a non-negative integer.
+  if (!/^\d+$/.test(parts[1])) {
+    throw new ReplicationAssertionError(`Expected a single transaction id, got: ${gtid}`);
+  }
+}

package/src/common/check-source-configuration.ts

@@ -2,6 +2,7 @@ import mysqlPromise from 'mysql2/promise';
 import * as mysql_utils from '../utils/mysql-utils.js';
 
 const MIN_SUPPORTED_VERSION = '5.7.0';
+const REPLICA_TERMINOLOGY_VERSION = '8.0.22';
 
 export async function checkSourceConfiguration(connection: mysqlPromise.Connection): Promise<string[]> {
   const errors: string[] = [];
@@ -11,6 +12,20 @@ export async function checkSourceConfiguration(connection: mysqlPromise.Connecti
     errors.push(`MySQL versions older than ${MIN_SUPPORTED_VERSION} are not supported. Your version is: ${version}.`);
   }
 
+  const replicaStatusQuery = mysql_utils.isVersionAtLeast(version, REPLICA_TERMINOLOGY_VERSION)
+    ? 'SHOW REPLICA STATUS'
+    : 'SHOW SLAVE STATUS';
+  const [replicaStatuses] = await mysql_utils.retriedQuery({
+    connection,
+    query: replicaStatusQuery
+  });
+
+  if (replicaStatuses.length > 0) {
+    errors.push(
+      'Connecting PowerSync to a MySQL replica is not supported. Please connect PowerSync directly to the primary server.'
+    );
+  }
+
   const [[result]] = await mysql_utils.retriedQuery({
     connection,
     query: `

package/src/common/read-executed-gtid.ts

@@ -2,6 +2,17 @@ import mysqlPromise from 'mysql2/promise';
 import * as mysql_utils from '../utils/mysql-utils.js';
 import { ReplicatedGTID } from './ReplicatedGTID.js';
 
+/**
+ * Gets the `@@server_uuid` of the current connected server
+ */
+export async function readServerUuid(connection: mysqlPromise.Connection): Promise<string> {
+  const [[result]] = await mysql_utils.retriedQuery({
+    connection,
+    query: `SELECT @@server_uuid AS server_uuid`
+  });
+  return result.server_uuid;
+}
+
 /**
  * Gets the current master HEAD GTID
  */
@@ -28,21 +39,80 @@ export async function readExecutedGtid(connection: mysqlPromise.Connection): Pro
     offset: parseInt(binlogStatus.Position)
   };
 
+  const activeServerUuid = await readServerUuid(connection);
+  const executedGtidSet = binlogStatus.Executed_Gtid_Set.trim();
+
+  if (executedGtidSet.length === 0) {
+    // New server with no transactions executed yet. Keep the current binlog
+    // coordinate so this synthetic GTID can still be validated after a restart.
+    return new ReplicatedGTID({
+      rawGtid: `${activeServerUuid}:0`,
+      position
+    });
+  }
+
+  const gtidSets = executedGtidSet.split(',');
+  const latestActiveGtid = await getLatestActiveGtid(gtidSets, activeServerUuid);
   return new ReplicatedGTID({
-    // The head always points to the next position to start replication from
-    position,
-    raw_gtid: binlogStatus.Executed_Gtid_Set
+    rawGtid: latestActiveGtid,
+    position
   });
 }
 
-export async function isBinlogStillAvailable(
+export async function getLatestActiveGtid(gtidSets: string[], activeServerUuid: string): Promise<string> {
+  for (const gtidSet of gtidSets) {
+    const [serverUuid, ...intervals] = gtidSet.trim().split(':');
+    if (serverUuid === activeServerUuid) {
+      let maxTransactionId: number | null = null;
+      for (const interval of intervals) {
+        const [start, end] = interval.split('-');
+        const startId = parseInt(start, 10);
+        const endId = end !== undefined ? parseInt(end, 10) : startId;
+        if (!Number.isNaN(startId)) {
+          maxTransactionId = Math.max(maxTransactionId ?? 0, startId);
+        }
+        if (!Number.isNaN(endId)) {
+          maxTransactionId = Math.max(maxTransactionId ?? 0, endId);
+        }
+      }
+      return activeServerUuid + ':' + maxTransactionId;
+    }
+  }
+
+  return `${activeServerUuid}:0`;
+}
+
+/**
+ * Checks that a stored resume GTID is still part of the server's executed history and that its
+ * binlog coordinate is still readable. This detects source rewinds where a restored server keeps
+ * the same UUID or recreates a binlog with the same filename but a shorter length.
+ */
+export async function isGtidPositionStillAvailable(
   connection: mysqlPromise.Connection,
-  binlogFile: string
+  gtid: ReplicatedGTID
 ): Promise<boolean> {
   const [logFiles] = await mysql_utils.retriedQuery({
     connection,
     query: `SHOW BINARY LOGS;`
   });
+  const logFile = logFiles.find((file) => file['Log_name'] == gtid.position.filename);
+
+  if (!logFile || Number(logFile['File_size']) < gtid.position.offset) {
+    return false;
+  }
+
+  // Transaction zero is PowerSync's synthetic position before the first
+  // transaction from this server UUID. It is not valid MySQL GTID_SET syntax,
+  // so its availability is determined by the binlog coordinate above.
+  if (gtid.raw.split(':')[1] === '0') {
+    return true;
+  }
+
+  const [[result]] = await mysql_utils.retriedQuery({
+    connection,
+    query: `SELECT GTID_SUBSET(?, @@GLOBAL.gtid_executed) AS is_executed`,
+    params: [gtid.raw]
+  });
 
-  return logFiles.some((f) => f['Log_name'] == binlogFile);
+  return result.is_executed === 1;
 }

package/src/common/schema-utils.ts

@@ -1,3 +1,4 @@
+import { ErrorCode, ServiceError } from '@powersync/lib-services-framework';
 import { ColumnDescriptor } from '@powersync/service-core';
 import { TablePattern } from '@powersync/service-sync-rules';
 import mysqlPromise from 'mysql2/promise';
@@ -147,6 +148,13 @@ export async function getTablesFromPattern(
   connection: mysqlPromise.Connection,
   tablePattern: TablePattern
 ): Promise<string[]> {
+  if (tablePattern.isSchemaWildcard) {
+    throw new ServiceError(
+      ErrorCode.PSYNC_R2201,
+      'Schema wildcards ("%") in table patterns are not supported for MySQL connections.'
+    );
+  }
+
   const schema = tablePattern.schema;
 
   if (tablePattern.isWildcard) {

package/src/replication/BinLogStream.ts

@@ -73,6 +73,8 @@ export class BinLogStream {
 
   private readonly logger: Logger;
 
+  private activeServerUuid: string | null = null;
+
   private tableCache = new Map<string | number, storage.SourceTable[]>();
 
   private replicationLag = new ReplicationLagTracker();
@@ -220,16 +222,23 @@ export class BinLogStream {
       this.logger.info(`Initial replication already done.`);
 
       if (lastKnowGTID) {
-        // Check if the specific binlog file is still available. If it isn't, we need to snapshot again.
         const connection = await this.connections.getConnection();
         try {
-          const isAvailable = await common.isBinlogStillAvailable(connection, lastKnowGTID.position.filename);
+          // Check if the active server uuid matches the one in the GTID
+          if (this.activeServerUuid !== lastKnowGTID.serverUuid) {
+            this.logger.info(
+              `The source server uuid has changed. Active server uuid ${this.activeServerUuid} does not match the server uuid from the resume checkpoint: ${lastKnowGTID.serverUuid}, re-snapshotting to ensure consistency.`
+            );
+            return false;
+          }
+
+          const isAvailable = await common.isGtidPositionStillAvailable(connection, lastKnowGTID);
           if (!isAvailable) {
             this.logger.info(
-              `BinLog file ${lastKnowGTID.position.filename} is no longer available, starting initial replication again.`
+              `Resume GTID ${lastKnowGTID.raw} at ${lastKnowGTID.position.filename}:${lastKnowGTID.position.offset} is no longer present in the executed GTID history or available BinLogs, re-snapshotting to ensure consistency.`
             );
+            return false;
           }
-          return isAvailable;
         } finally {
           connection.release();
         }
@@ -267,7 +276,7 @@ export class BinLogStream {
       const flushResults = await this.storage.startBatch(
         {
           logger: this.logger,
-          zeroLSN: common.ReplicatedGTID.ZERO.comparable,
+          zeroLSN: common.ReplicatedGTID.ZERO(this.activeServerUuid!).comparable,
           defaultSchema: this.defaultSchema,
           storeCurrentData: false
         },
@@ -363,7 +372,19 @@ export class BinLogStream {
     }
   }
 
+  private async ensureActiveServerUuid() {
+    if (this.activeServerUuid == null) {
+      const connection = await this.connections.getConnection();
+      try {
+        this.activeServerUuid = await common.readServerUuid(connection);
+      } finally {
+        connection.release();
+      }
+    }
+  }
+
   async initReplication() {
+    await this.ensureActiveServerUuid();
     const connection = await this.connections.getConnection();
     const errors = await common.checkSourceConfiguration(connection);
     connection.release();
@@ -382,7 +403,7 @@ export class BinLogStream {
       await this.storage.startBatch(
         {
           logger: this.logger,
-          zeroLSN: common.ReplicatedGTID.ZERO.comparable,
+          zeroLSN: common.ReplicatedGTID.ZERO(this.activeServerUuid!).comparable,
           defaultSchema: this.defaultSchema,
           storeCurrentData: false
         },
@@ -406,21 +427,30 @@ export class BinLogStream {
   }
 
   async streamChanges() {
+    await this.ensureActiveServerUuid();
     const serverId = createRandomServerId(this.storage.replicationStreamId);
 
     const connection = await this.connections.getConnection();
-    const { resumeLsn: resume_lsn } = await this.storage.getStatus();
-    if (resume_lsn) {
-      this.logger.info(`Existing resume LSN found: ${resume_lsn}`);
+    let fromGTID: common.ReplicatedGTID;
+    try {
+      const { resumeLsn: resume_lsn } = await this.storage.getStatus();
+      if (resume_lsn) {
+        this.logger.info(`Existing resume LSN found: ${resume_lsn}`);
+      }
+      fromGTID = resume_lsn
+        ? common.ReplicatedGTID.fromSerialized(resume_lsn)
+        : await common.readExecutedGtid(connection);
+    } finally {
+      connection.release();
     }
-    const fromGTID = resume_lsn
-      ? common.ReplicatedGTID.fromSerialized(resume_lsn)
-      : await common.readExecutedGtid(connection);
-    connection.release();
 
     if (!this.stopped) {
       await this.storage.startBatch(
-        { zeroLSN: common.ReplicatedGTID.ZERO.comparable, defaultSchema: this.defaultSchema, storeCurrentData: false },
+        {
+          zeroLSN: common.ReplicatedGTID.ZERO(this.activeServerUuid!).comparable,
+          defaultSchema: this.defaultSchema,
+          storeCurrentData: false
+        },
         async (batch) => {
           const binlogEventHandler = this.createBinlogEventHandler(batch);
           const binlogListener = new BinLogListener({
@@ -429,6 +459,7 @@ export class BinLogStream {
             startGTID: fromGTID,
             connectionManager: this.connections,
             serverId: serverId,
+            activeServerUuid: this.activeServerUuid!,
             eventHandler: binlogEventHandler
           });
 

package/src/replication/zongji/BinLogListener.ts

@@ -1,4 +1,4 @@
-import { Logger, logger as defaultLogger } from '@powersync/lib-services-framework';
+import { Logger, ReplicationAssertionError, logger as defaultLogger } from '@powersync/lib-services-framework';
 import { BinLogEvent, BinLogQueryEvent, StartOptions, TableMapEntry, ZongJi } from '@powersync/mysql-zongji';
 import { TablePattern } from '@powersync/service-sync-rules';
 import async from 'async';
@@ -76,7 +76,14 @@ export interface BinLogListenerOptions {
   connectionManager: MySQLConnectionManager;
   eventHandler: BinLogEventHandler;
   sourceTables: TablePattern[];
+  /**
+   *  Id that identifies this replication client.
+   */
   serverId: number;
+  /**
+   *  The server uuid of the source MySQL server that is being replicated.
+   */
+  activeServerUuid: string;
   startGTID: common.ReplicatedGTID;
   logger?: Logger;
   keepAliveInactivitySeconds?: number;
@@ -88,8 +95,6 @@ export interface BinLogListenerOptions {
  */
 export class BinLogListener {
   private sqlParser: ParserType;
-  private connectionManager: MySQLConnectionManager;
-  private eventHandler: BinLogEventHandler;
   private binLogPosition: common.BinLogPosition;
   private currentGTID: common.ReplicatedGTID;
   private logger: Logger;
@@ -101,6 +106,7 @@ export class BinLogListener {
 
   // Flag to indicate if are currently in a transaction that involves multiple row mutation events.
   private isTransactionOpen = false;
+
   zongji: ZongJi;
   processingQueue: async.QueueObject<BinLogEvent>;
 
@@ -111,9 +117,8 @@ export class BinLogListener {
 
   constructor(public options: BinLogListenerOptions) {
     this.logger = options.logger ?? defaultLogger;
-    this.connectionManager = options.connectionManager;
-    this.eventHandler = options.eventHandler;
-    this.binLogPosition = options.startGTID.position;
+    // Copy the position: the listener mutates it as events are processed, and the caller's startGTID must not change
+    this.binLogPosition = { ...options.startGTID.position };
     this.currentGTID = options.startGTID;
     this.sqlParser = new Parser();
     this.processingQueue = this.createProcessingQueue();
@@ -122,6 +127,18 @@ export class BinLogListener {
     this.databaseFilter = this.createDatabaseFilter(options.sourceTables);
   }
 
+  private get connectionManager(): MySQLConnectionManager {
+    return this.options.connectionManager;
+  }
+
+  private get eventHandler(): BinLogEventHandler {
+    return this.options.eventHandler;
+  }
+
+  private get activeServerUuid(): string {
+    return this.options.activeServerUuid;
+  }
+
   /**
    *  The queue memory limit in bytes as defined in the connection options.
    *  @private
@@ -292,29 +309,41 @@ export class BinLogListener {
     return async (evt: BinLogEvent) => {
       switch (true) {
         case zongji_utils.eventIsGTIDLog(evt):
-          this.currentGTID = common.ReplicatedGTID.fromBinLogEvent({
-            raw_gtid: {
-              server_id: evt.serverId,
-              transaction_range: evt.transactionRange
+          const transactionGTID = common.ReplicatedGTID.fromBinLogEvent({
+            rawGtid: {
+              serverUuid: evt.serverId, // The server uuid this transaction originated from
+              transactionId: evt.transactionRange
             },
             position: {
               filename: this.binLogPosition.filename,
               offset: evt.nextPosition
             }
           });
+
+          if (transactionGTID.serverUuid !== this.activeServerUuid) {
+            throw new ReplicationAssertionError(
+              `Detected a transaction from a different MySQL server UUID: ${transactionGTID.serverUuid} than the server that is currently being replicated from: ${this.activeServerUuid}. ` +
+                `A re-snapshot is required to ensure consistency.`
+            );
+          }
+
+          this.currentGTID = transactionGTID;
           this.binLogPosition.offset = evt.nextPosition;
+
           await this.eventHandler.onTransactionStart({ timestamp: new Date(evt.timestamp) });
           this.logger.info(`Processed GTID event: ${this.currentGTID.comparable}`);
           break;
         case zongji_utils.eventIsRotation(evt):
           // The first event when starting replication is a synthetic Rotate event
-          // It describes the last binlog file and position that the replica client processed
+          // It describes the the position and file that the replica requested to start from
+          const isNewFile = this.binLogPosition.filename !== evt.binlogName;
+
           this.binLogPosition.filename = evt.binlogName;
-          this.binLogPosition.offset = evt.nextPosition !== 0 ? evt.nextPosition : evt.position;
+          this.binLogPosition.offset = evt.position;
+
           await this.eventHandler.onRotate();
 
-          const newFile = this.binLogPosition.filename !== evt.binlogName;
-          if (newFile) {
+          if (isNewFile) {
             this.logger.info(
               `Processed Rotate event. New BinLog file is: ${this.binLogPosition.filename}:${this.binLogPosition.offset}`
             );
@@ -359,11 +388,7 @@ export class BinLogListener {
           break;
         case zongji_utils.eventIsXid(evt):
           this.isTransactionOpen = false;
-          this.binLogPosition.offset = evt.nextPosition;
-          const LSN = new common.ReplicatedGTID({
-            raw_gtid: this.currentGTID.raw,
-            position: this.binLogPosition
-          }).comparable;
+          const LSN = this.advanceCommitPosition(evt.nextPosition);
           await this.eventHandler.onCommit(LSN);
           this.logger.info(`Processed Xid event - transaction complete. LSN: ${LSN}.`);
           break;
@@ -376,6 +401,21 @@ export class BinLogListener {
     };
   }
 
+  /**
+   *  Advances the binlog position to the end of a committed transaction and updates the currentGTID to match.
+   *  This ensures subsequent heartbeat keepalives report an LSN that is not behind the last commit LSN,
+   *  which would otherwise block checkpoint creation until the next transaction arrives.
+   *  Returns the commit LSN.
+   */
+  private advanceCommitPosition(nextPosition: number): string {
+    this.binLogPosition.offset = nextPosition;
+    this.currentGTID = new common.ReplicatedGTID({
+      rawGtid: this.currentGTID.raw,
+      position: { ...this.binLogPosition }
+    });
+    return this.currentGTID.comparable;
+  }
+
   private async processQueryEvent(event: BinLogQueryEvent): Promise<void> {
     const { query, nextPosition } = event;
 
@@ -398,11 +438,7 @@ export class BinLogListener {
       // DDL queries are auto commited, but do not come with a corresponding Xid event, in those cases we trigger a manual commit if we are not already in a transaction.
       // Some DDL queries include row events, and in those cases will include a Xid event.
       if (!this.isTransactionOpen) {
-        this.binLogPosition.offset = nextPosition;
-        const LSN = new common.ReplicatedGTID({
-          raw_gtid: this.currentGTID.raw,
-          position: this.binLogPosition
-        }).comparable;
+        const LSN = this.advanceCommitPosition(nextPosition);
         await this.eventHandler.onCommit(LSN);
       }
 
@@ -419,11 +455,7 @@ export class BinLogListener {
         await this.restartZongji();
       }
     } else if (!this.isTransactionOpen) {
-      this.binLogPosition.offset = nextPosition;
-      const LSN = new common.ReplicatedGTID({
-        raw_gtid: this.currentGTID.raw,
-        position: this.binLogPosition
-      }).comparable;
+      const LSN = this.advanceCommitPosition(nextPosition);
       await this.eventHandler.onCommit(LSN);
     }
   }

package/test/src/BinLogListener.test.ts

@@ -111,6 +111,24 @@ describe('BinlogListener tests', { timeout: 60_000 }, () => {
     expect(eventHandler.lastKeepAlive).toEqual(binLogListener.options.startGTID.comparable);
   });
 
+  test('Keepalive LSN after a commit is not less than the commit LSN', async () => {
+    binLogListener.options.keepAliveInactivitySeconds = 1;
+    await binLogListener.start();
+
+    await insertRows(connectionManager, 1);
+    await vi.waitFor(() => expect(eventHandler.commitCount).equals(1), { timeout: 5000 });
+    const commitLsn = eventHandler.lastCommitLsn!;
+
+    // Wait for a heartbeat keepalive that arrives after the commit.
+    // A keepalive LSN behind the commit LSN blocks checkpoint creation until the next transaction arrives.
+    await vi.waitFor(() => expect(eventHandler.lastKeepAlive && eventHandler.lastKeepAlive >= commitLsn).toBeTruthy(), {
+      timeout: 10_000
+    });
+    await binLogListener.stop();
+    // No binlog rotation happens in this test, so the keepalive LSN should exactly match the commit LSN
+    expect(eventHandler.lastKeepAlive).toEqual(commitLsn);
+  });
+
   test('Schema change event: Rename table', async () => {
     await binLogListener.start();
     await connectionManager.query(`ALTER TABLE test_DATA RENAME test_DATA_new`);

package/test/src/BinlogStreamUtils.ts

@@ -167,7 +167,7 @@ export class BinlogStreamTestContext {
     const checkpoint = await this.getCheckpoint(options);
     const syncConfigContent = this.getSyncConfigContent();
     const map = Object.entries(buckets).map(([bucket, start]) => bucketRequest(syncConfigContent, bucket, start));
-    return test_utils.fromAsync(this.storage!.getBucketDataBatch(checkpoint, map));
+    return test_utils.getBatchArray(this.storage!.getBucketDataBatch(checkpoint, map));
   }
 
   async getBucketData(
@@ -183,7 +183,7 @@ export class BinlogStreamTestContext {
     const checkpoint = await this.getCheckpoint(options);
     const map = [bucketRequest(syncConfigContent, bucket, start)];
     const batch = this.storage!.getBucketDataBatch(checkpoint, map);
-    const batches = await test_utils.fromAsync(batch);
+    const batches = await test_utils.getBatchArray(batch);
     return batches[0]?.chunkData.data ?? [];
   }
 }