@powersync/service-module-mysql 0.0.0-dev-20260602073133 → 0.0.0-dev-20260909133214

package/src/utils/mysql-utils.ts

@@ -12,6 +12,13 @@ export type RetriedQueryOptions = {
   retries?: number;
 };
 
+/**
+ *  TCP keepalive initial delay in milliseconds for connections to the MySQL server.
+ *  Keepalive prevents long-lived idle connections from being silently dropped by stateful
+ *  firewalls, which commonly time out idle flows after an hour.
+ */
+export const TCP_KEEPALIVE_INITIAL_DELAY = 40_000;
+
 /**
  * Retry a simple query - up to 2 attempts total.
  */
@@ -54,6 +61,10 @@ export function createPool(config: types.NormalizedMySQLConnectionConfig, option
     timezone: 'Z', // Ensure no auto timezone manipulation of the dates occur
     jsonStrings: true, // Return JSON columns as strings
     dateStrings: true, // We parse and format them ourselves
+    // mysql2 enables TCP keepalive by default, but without an initial delay the OS default of
+    // 7200 seconds applies, which is too late for common 3600 second firewall idle timeouts.
+    enableKeepAlive: true,
+    keepAliveInitialDelay: TCP_KEEPALIVE_INITIAL_DELAY,
     // Apply URL connection parameters (explicit options override these via spread below)
     ...(params.connectTimeout != null ? { connectTimeout: params.connectTimeout } : {}),
     ...(params.connectionLimit != null ? { connectionLimit: params.connectionLimit } : {}),

package/test/src/BinLogListener.test.ts

@@ -1,6 +1,12 @@
 import { MySQLConnectionManager } from '@module/replication/MySQLConnectionManager.js';
 import { BinLogListener, SchemaChange, SchemaChangeType } from '@module/replication/zongji/BinLogListener.js';
-import { getMySQLVersion, qualifiedMySQLTable, satisfiesVersion } from '@module/utils/mysql-utils.js';
+import {
+  getMySQLVersion,
+  qualifiedMySQLTable,
+  satisfiesVersion,
+  TCP_KEEPALIVE_INITIAL_DELAY
+} from '@module/utils/mysql-utils.js';
+import { MySQLConnection } from '@powersync/mysql-zongji';
 import { TablePattern } from '@powersync/service-sync-rules';
 import crypto from 'crypto';
 import { v4 as uuid } from 'uuid';
@@ -13,6 +19,11 @@ import {
   TestBinLogEventHandler
 } from './util.js';
 
+// The zongji type definitions do not expose the connection config.
+type ConnectionWithConfig = MySQLConnection & {
+  config: { enableKeepAlive?: boolean; keepAliveInitialDelay?: number };
+};
+
 describe('BinlogListener tests', { timeout: 60_000 }, () => {
   const MAX_QUEUE_CAPACITY_MB = 1;
   const BINLOG_LISTENER_CONNECTION_OPTIONS = {
@@ -59,6 +70,116 @@ describe('BinlogListener tests', { timeout: 60_000 }, () => {
 
     expect(stopSpy).toHaveBeenCalled();
     expect(queueStopSpy).toHaveBeenCalled();
+    // Zongji destroys its control connection when stopping.
+    expect(binLogListener.zongji.ctrlConnection.state).toBe('disconnected');
+  });
+
+  test('TCP keepalive is enabled on the binlog and control connections', async () => {
+    // Without keepalive, the control connection can idle for hours and be silently dropped by
+    // stateful firewalls. The next metadata query then blocks until the kernel gives up on TCP
+    // retransmissions, freezing the whole binlog pipeline for ~15 minutes.
+    const { connection } = binLogListener.zongji as unknown as { connection: ConnectionWithConfig };
+    const controlConnection = binLogListener.zongji.ctrlConnection as ConnectionWithConfig;
+
+    for (const conn of [connection, controlConnection]) {
+      expect(conn.config.enableKeepAlive).toBe(true);
+      expect(conn.config.keepAliveInitialDelay).toBe(TCP_KEEPALIVE_INITIAL_DELAY);
+    }
+  });
+
+  test('Stop completes when the control connection is unresponsive', { timeout: 20_000 }, async () => {
+    await binLogListener.start();
+
+    // Simulate a control connection that was silently dropped by the network: the KILL query
+    // issued by zongji.stop() never gets a response.
+    vi.spyOn(binLogListener.zongji.ctrlConnection, 'query').mockImplementation(() => {});
+
+    await binLogListener.stop();
+
+    expect(binLogListener.zongji.stopped).toBeTruthy();
+  });
+
+  test('Probe on a healthy control connection passes', { timeout: 20_000 }, async () => {
+    await binLogListener.start();
+
+    // No mocking: the real driver must accept the options form of query and answer the probe.
+    const controlConnection = binLogListener.zongji.ctrlConnection;
+    const realQuery = controlConnection.query.bind(controlConnection);
+    const probeError = new Promise((resolve) => {
+      vi.spyOn(controlConnection, 'query').mockImplementation(((options: any, callback: any) => {
+        realQuery(options, (error: any, results: any, fields: any) => {
+          callback(error, results, fields);
+          resolve(error);
+        });
+      }) as any);
+    });
+
+    binLogListener.probeControlConnection();
+
+    expect(await probeError).toBeNull();
+    expect(binLogListener.zongji.stopped).toBeFalsy();
+
+    await binLogListener.stop();
+  });
+
+  test('Probe detects an unresponsive control connection', { timeout: 20_000 }, async () => {
+    binLogListener = await createBinlogListener({
+      connectionManager,
+      sourceTables: [new TablePattern(connectionManager.databaseName, 'test_DATA')],
+      eventHandler,
+      ctrlConnectionProbeTimeoutMs: 500
+    });
+    await binLogListener.start();
+
+    // The probe query starts executing but never gets a response, like a connection that died
+    // without either side being notified: the driver's query timeout fires.
+    vi.spyOn(binLogListener.zongji.ctrlConnection, 'query').mockImplementation(((_options: any, callback: any) => {
+      const error: any = new Error('Query inactivity timeout');
+      error.code = 'PROTOCOL_SEQUENCE_TIMEOUT';
+      setTimeout(() => callback(error), 10);
+    }) as any);
+
+    const replication = binLogListener.replicateUntilStopped();
+    binLogListener.probeControlConnection();
+
+    await expect(replication).rejects.toThrow('control connection is unresponsive');
+    expect(binLogListener.zongji.stopped).toBeTruthy();
+  });
+
+  test('Probe queued behind a busy control connection does not report it dead', { timeout: 20_000 }, async () => {
+    binLogListener = await createBinlogListener({
+      connectionManager,
+      sourceTables: [new TablePattern(connectionManager.databaseName, 'test_DATA')],
+      eventHandler,
+      ctrlConnectionProbeTimeoutMs: 500
+    });
+    await binLogListener.start();
+
+    // The probe never even starts executing, as if queued behind a long-running metadata query on
+    // a healthy connection. The probe must not report the connection dead, and further probes must
+    // not pile up behind the pending one.
+    const querySpy = vi.spyOn(binLogListener.zongji.ctrlConnection, 'query').mockImplementation((() => {}) as any);
+
+    binLogListener.probeControlConnection();
+    binLogListener.probeControlConnection();
+
+    expect(querySpy).toHaveBeenCalledTimes(1);
+    expect(binLogListener.zongji.stopped).toBeFalsy();
+
+    querySpy.mockRestore();
+    await binLogListener.stop();
+  });
+
+  test('Control connection errors stop the listener', { timeout: 20_000 }, async () => {
+    await binLogListener.start();
+
+    const replication = binLogListener.replicateUntilStopped();
+    // The driver emits 'error' when the socket fails while no query is pending. Without the
+    // forwarding set up in createBinlogListener, this event has no listener and crashes the process.
+    (binLogListener.zongji.ctrlConnection as any).emit('error', new Error('Control connection failure'));
+
+    await expect(replication).rejects.toThrow('Control connection failure');
+    expect(binLogListener.zongji.stopped).toBeTruthy();
   });
 
   test('Zongji listener is stopped when processing queue reaches maximum memory size', async () => {
@@ -111,6 +232,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

@@ -33,7 +33,7 @@ export class BinlogStreamTestContext {
   private streamPromise?: Promise<void>;
   public storage?: SyncRulesBucketStorage;
   private replicationDone = false;
-  private syncRulesContent?: storage.PersistedSyncRulesContent;
+  private syncRulesContent?: storage.PersistedSyncConfigContent;
 
   static async open(factory: storage.TestStorageFactory, options?: { doNotClear?: boolean }) {
     const f = await factory({ doNotClear: options?.doNotClear });
@@ -71,38 +71,38 @@ export class BinlogStreamTestContext {
   }
 
   async updateSyncRules(content: string): Promise<SyncRulesBucketStorage> {
-    const syncRules = await this.factory.updateSyncRules(
+    const replicationStream = await this.factory.updateSyncRules(
       updateSyncRulesFromYaml(content, { validate: true, storageVersion: LEGACY_STORAGE_VERSION })
     );
-    this.syncRulesContent = syncRules;
-    this.storage = this.factory.getInstance(syncRules);
+    this.syncRulesContent = replicationStream.syncConfigContent[0];
+    this.storage = this.factory.getInstance(replicationStream);
     return this.storage!;
   }
 
   async loadNextSyncRules() {
-    const syncRules = await this.factory.getNextSyncRulesContent();
-    if (syncRules == null) {
+    const syncConfig = await this.factory.getDeployingSyncConfig();
+    if (syncConfig == null) {
       throw new Error(`Next replication stream not available`);
     }
 
-    this.syncRulesContent = syncRules;
-    this.storage = this.factory.getInstance(syncRules);
+    this.syncRulesContent = syncConfig.content;
+    this.storage = syncConfig.storage;
     return this.storage!;
   }
 
   async loadActiveSyncRules() {
-    const syncRules = await this.factory.getActiveSyncRulesContent();
-    if (syncRules == null) {
+    const syncConfig = await this.factory.getActiveSyncConfig();
+    if (syncConfig == null) {
       throw new Error(`Active replication stream not available`);
     }
 
-    this.syncRulesContent = syncRules;
-    this.storage = this.factory.getInstance(syncRules);
+    this.syncRulesContent = syncConfig.content;
+    this.storage = syncConfig.storage;
     this.replicationDone = true;
     return this.storage!;
   }
 
-  private getSyncRulesContent(): storage.PersistedSyncRulesContent {
+  private getSyncConfigContent(): storage.PersistedSyncConfigContent {
     if (this.syncRulesContent == null) {
       throw new Error('Sync config not configured - call updateSyncRules() first');
     }
@@ -148,7 +148,7 @@ export class BinlogStreamTestContext {
     });
   }
 
-  async getCheckpoint(options?: { timeout?: number }): Promise<InternalOpId> {
+  async getCheckpoint(options?: { timeout?: number }): Promise<ReplicationCheckpoint> {
     const connection = await this.connectionManager.getConnection();
     let checkpoint = await Promise.race([
       getClientCheckpoint(connection, this.factory, { timeout: options?.timeout ?? 60_000 }),
@@ -165,9 +165,9 @@ export class BinlogStreamTestContext {
 
   async getBucketsDataBatch(buckets: Record<string, InternalOpId>, options?: { timeout?: number }) {
     const checkpoint = await this.getCheckpoint(options);
-    const syncRules = this.getSyncRulesContent();
-    const map = Object.entries(buckets).map(([bucket, start]) => bucketRequest(syncRules, bucket, start));
-    return test_utils.fromAsync(this.storage!.getBucketDataBatch(checkpoint, map));
+    const syncConfigContent = this.getSyncConfigContent();
+    const map = Object.entries(buckets).map(([bucket, start]) => bucketRequest(syncConfigContent, bucket, start));
+    return test_utils.getBatchArray(this.storage!.getBucketDataBatch(checkpoint, map));
   }
 
   async getBucketData(
@@ -179,11 +179,11 @@ export class BinlogStreamTestContext {
     if (typeof start == 'string') {
       start = BigInt(start);
     }
-    const syncRules = this.getSyncRulesContent();
+    const syncConfigContent = this.getSyncConfigContent();
     const checkpoint = await this.getCheckpoint(options);
-    const map = [bucketRequest(syncRules, bucket, start)];
+    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 ?? [];
   }
 }
@@ -192,7 +192,7 @@ export async function getClientCheckpoint(
   connection: mysqlPromise.Connection,
   storageFactory: BucketStorageFactory,
   options?: { timeout?: number }
-): Promise<InternalOpId> {
+): Promise<ReplicationCheckpoint> {
   const start = Date.now();
   const gtid = await readExecutedGtid(connection);
   // This old API needs a persisted checkpoint id.
@@ -203,14 +203,14 @@ export async function getClientCheckpoint(
 
   logger.info('Expected Checkpoint: ' + gtid.comparable);
   while (Date.now() - start < timeout) {
-    const storage = await storageFactory.getActiveStorage();
+    const storage = (await storageFactory.getActiveSyncConfig())?.storage;
     const cp = await storage?.getCheckpoint();
     if (cp == null) {
       throw new Error('No replication stream available');
     }
     lastCp = cp;
     if (cp.lsn && cp.lsn >= gtid.comparable) {
-      return cp.checkpoint;
+      return cp;
     }
 
     await new Promise((resolve) => setTimeout(resolve, 30));

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}`);
+      }
+    });
+  }
+});

package/test/src/mysql-utils.test.ts

@@ -1,4 +1,5 @@
-import { isVersionAtLeast } from '@module/utils/mysql-utils.js';
+import * as types from '@module/types/types.js';
+import { createPool, isVersionAtLeast, TCP_KEEPALIVE_INITIAL_DELAY } from '@module/utils/mysql-utils.js';
 import { describe, expect, test } from 'vitest';
 
 describe('MySQL Utility Tests', () => {
@@ -14,4 +15,21 @@ describe('MySQL Utility Tests', () => {
     expect(isVersionAtLeast(olderVersion, '8.0')).toBeFalsy();
     expect(isVersionAtLeast(improperSemver, '5.7')).toBeTruthy();
   });
+
+  test('Pool connections are configured with a TCP keepalive initial delay', async () => {
+    // mysql2 enables keepalive by default, but without an initial delay the OS default of
+    // 7200 seconds applies, which is too late for common 3600 second firewall idle timeouts.
+    const config = types.normalizeConnectionConfig({
+      type: 'mysql',
+      uri: 'mysql://root:password@localhost:3306/mydatabase'
+    });
+    // The pool is lazy, so no connection is made here.
+    const pool = createPool(config);
+    const { connectionConfig } = (pool as unknown as { config: { connectionConfig: Record<string, unknown> } }).config;
+
+    expect(connectionConfig.enableKeepAlive).toBe(true);
+    expect(connectionConfig.keepAliveInitialDelay).toBe(TCP_KEEPALIVE_INITIAL_DELAY);
+
+    await pool.promise().end();
+  });
 });