@powersync/service-module-mysql 0.15.0 → 0.16.0

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/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/ReplicatedGTID.test.ts

@@ -0,0 +1,138 @@
+import { ReplicatedGTID } from '@module/common/ReplicatedGTID.js';
+import * as uuid from 'uuid';
+import { describe, expect, test } from 'vitest';
+
+describe('ReplicatedGTID', () => {
+  const SERVER_UUID = 'a7d0ff7b-0c0e-11f0-8b38-566fbaa00004';
+  const POSITION = { filename: 'binlog.000042', offset: 1234 };
+
+  describe('single GTID', () => {
+    test('exposes its raw value, server UUID, and binlog position', () => {
+      const gtid = new ReplicatedGTID({
+        rawGtid: `${SERVER_UUID}:5`,
+        position: POSITION
+      });
+
+      expect(gtid.raw).toEqual(`${SERVER_UUID}:5`);
+      expect(gtid.serverUuid).toEqual(SERVER_UUID);
+      expect(gtid.position).toEqual(POSITION);
+    });
+
+    test('formats a comparable LSN using the transaction id', () => {
+      const gtid = new ReplicatedGTID({
+        rawGtid: `${SERVER_UUID}:17`,
+        position: POSITION
+      });
+
+      expect(gtid.comparable).toEqual(`0000000000000017|${SERVER_UUID}:17|binlog.000042|1234`);
+      expect(gtid.toString()).toEqual(gtid.comparable);
+    });
+
+    test('normalizes surrounding whitespace', () => {
+      const gtid = new ReplicatedGTID({
+        rawGtid: ` \n\t${SERVER_UUID}:17 \r\n`,
+        position: POSITION
+      });
+
+      expect(gtid.raw).toEqual(`${SERVER_UUID}:17`);
+      expect(gtid.serverUuid).toEqual(SERVER_UUID);
+      expect(gtid.comparable).toEqual(`0000000000000017|${SERVER_UUID}:17|binlog.000042|1234`);
+    });
+
+    test('keeps the ZERO GTID format stable', () => {
+      expect(ReplicatedGTID.ZERO(SERVER_UUID).raw).toEqual(`${SERVER_UUID}:0`);
+      expect(ReplicatedGTID.ZERO(SERVER_UUID).comparable).toEqual(`0000000000000000|${SERVER_UUID}:0||0`);
+    });
+  });
+
+  describe('validation', () => {
+    test.each([
+      ['', 'missing server UUID and transaction id'],
+      [SERVER_UUID, 'missing transaction id'],
+      [`${SERVER_UUID}:`, 'empty transaction id'],
+      [`:${17}`, 'empty server UUID'],
+      [`${SERVER_UUID}:1-17`, 'transaction interval'],
+      [`${SERVER_UUID}:1:17`, 'multiple transaction components'],
+      [`${SERVER_UUID}:abc`, 'non-numeric transaction id'],
+      [`${SERVER_UUID}:-1`, 'negative transaction id'],
+      [`${SERVER_UUID}:17,another-server:9`, 'comma-separated GTID set'],
+      [`${SERVER_UUID}:17,\nanother-server:9`, 'newline-separated GTID set']
+    ])('rejects %s (%s)', (rawGtid) => {
+      expect(() => new ReplicatedGTID({ rawGtid, position: POSITION })).toThrow();
+    });
+  });
+
+  describe('serialization', () => {
+    test('round-trips a single GTID', () => {
+      const gtid = new ReplicatedGTID({
+        rawGtid: `${SERVER_UUID}:17`,
+        position: POSITION
+      });
+
+      const deserialized = ReplicatedGTID.fromSerialized(gtid.comparable);
+
+      expect(deserialized.raw).toEqual(gtid.raw);
+      expect(deserialized.serverUuid).toEqual(SERVER_UUID);
+      expect(deserialized.position).toEqual(POSITION);
+      expect(deserialized.comparable).toEqual(gtid.comparable);
+    });
+
+    test('throws on malformed serialized GTIDs', () => {
+      expect(() => ReplicatedGTID.fromSerialized('abc')).toThrow('Invalid serialized GTID');
+      expect(() => ReplicatedGTID.fromSerialized(`0000000000000001|${SERVER_UUID}:1|binlog.000001`)).toThrow(
+        'Invalid serialized GTID'
+      );
+      expect(() => ReplicatedGTID.fromSerialized(`0000000000000001|${SERVER_UUID}:1|binlog.000001|notanumber`)).toThrow(
+        'Invalid BinLog offset'
+      );
+    });
+
+    test('rejects a serialized GTID set', () => {
+      const serialized = `0000000000000017|${SERVER_UUID}:1-17|binlog.000042|1234`;
+
+      expect(() => ReplicatedGTID.fromSerialized(serialized)).toThrow('Expected a single transaction id');
+    });
+  });
+
+  describe('binlog events', () => {
+    test('creates a single GTID from a binlog event', () => {
+      const gtid = ReplicatedGTID.fromBinLogEvent({
+        rawGtid: {
+          serverUuid: Buffer.from(uuid.parse(SERVER_UUID)),
+          transactionId: 17
+        },
+        position: POSITION
+      });
+
+      expect(gtid.raw).toEqual(`${SERVER_UUID}:17`);
+      expect(gtid.position).toEqual(POSITION);
+      expect(gtid.comparable).toEqual(`0000000000000017|${SERVER_UUID}:17|binlog.000042|1234`);
+    });
+  });
+
+  describe('LSN ordering', () => {
+    test('orders GTIDs from the same server by transaction id', () => {
+      const earlier = new ReplicatedGTID({ rawGtid: `${SERVER_UUID}:9`, position: POSITION });
+      const later = new ReplicatedGTID({ rawGtid: `${SERVER_UUID}:18`, position: POSITION });
+
+      expect(earlier.comparable < later.comparable).toBeTruthy();
+    });
+
+    test('orders LSNs for the same transaction by binlog offset', () => {
+      // The binlog offset is not zero-padded, so lexicographic ordering only holds for
+      // offsets with the same number of digits. This format cannot change while existing
+      // LSNs remain persisted in bucket storage.
+      const rawGtid = `${SERVER_UUID}:18`;
+      const transactionStart = new ReplicatedGTID({
+        rawGtid,
+        position: { filename: 'binlog.000042', offset: 157 }
+      });
+      const transactionEnd = new ReplicatedGTID({
+        rawGtid,
+        position: { filename: 'binlog.000042', offset: 300 }
+      });
+
+      expect(transactionStart.comparable < transactionEnd.comparable).toBeTruthy();
+    });
+  });
+});

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

@@ -0,0 +1,70 @@
+import { checkSourceConfiguration } from '@module/common/check-source-configuration.js';
+import { describe, expect, test } from 'vitest';
+import { createMockMySQLConnection } from './util.js';
+
+describe('checkSourceConfiguration', () => {
+  test('accepts a primary MySQL server', async () => {
+    const { connection, query } = createConnection({ version: '8.4.0', replicaStatuses: [] });
+
+    await expect(checkSourceConfiguration(connection)).resolves.toEqual([]);
+    expect(query).toHaveBeenCalledWith('SHOW REPLICA STATUS', []);
+  });
+
+  test('rejects a replica on MySQL 8.0.22 and later', async () => {
+    const { connection, query } = createConnection({
+      version: '8.0.22',
+      replicaStatuses: [{ Channel_Name: '' }]
+    });
+
+    await expect(checkSourceConfiguration(connection)).resolves.toContain(
+      'Connecting PowerSync to a MySQL replica is not supported. Please connect PowerSync directly to the primary server.'
+    );
+    expect(query).toHaveBeenCalledWith('SHOW REPLICA STATUS', []);
+    expect(query).not.toHaveBeenCalledWith('SHOW SLAVE STATUS', []);
+  });
+
+  test('uses legacy replica-status syntax before MySQL 8.0.22', async () => {
+    const { connection, query } = createConnection({
+      version: '5.7.44',
+      replicaStatuses: [{ Channel_Name: '' }]
+    });
+
+    await expect(checkSourceConfiguration(connection)).resolves.toContain(
+      'Connecting PowerSync to a MySQL replica is not supported. Please connect PowerSync directly to the primary server.'
+    );
+    expect(query).toHaveBeenCalledWith('SHOW SLAVE STATUS', []);
+    expect(query).not.toHaveBeenCalledWith('SHOW REPLICA STATUS', []);
+  });
+
+  function createConnection(options: { version: string; replicaStatuses: Record<string, unknown>[] }) {
+    return createMockMySQLConnection(async (sql) => {
+      switch (sql.trim()) {
+        case 'SELECT VERSION() as version':
+          return [[{ version: options.version }], []];
+        case 'SHOW REPLICA STATUS':
+        case 'SHOW SLAVE STATUS':
+          return [options.replicaStatuses, []];
+        case "SHOW VARIABLES LIKE 'binlog_format';":
+          return [[{ Value: 'ROW' }], []];
+        case "SHOW GLOBAL VARIABLES LIKE 'binlog_row_image';":
+          return [[{ Value: 'FULL' }], []];
+        default:
+          if (sql.includes('@@GLOBAL.gtid_mode AS gtid_mode')) {
+            return [
+              [
+                {
+                  gtid_mode: 'ON',
+                  log_bin: 1,
+                  server_id: 1,
+                  binlog_file: '/var/lib/mysql/binlog',
+                  binlog_index_file: '/var/lib/mysql/binlog.index'
+                }
+              ],
+              []
+            ];
+          }
+          throw new Error(`Unexpected query: ${sql}`);
+      }
+    });
+  }
+});