[MySQL] Fix idle keepalive LSN stall and multi-server-UUID GTID parsing by michaelbarnes · Pull Request #706 · powersync-ja/powersync-service

michaelbarnes · 2026-07-01T23:49:51Z

Fixes #704
Fixes #705

Background

These fixes address two MySQL replication issues found in the same support case: idle replication could leave checkpoints blocked, and GTID sets containing historical server UUIDs could produce invalid NaN LSNs.

Changes

Keepalive LSNs now use the end position of the last committed transaction across Xid, DDL auto-commit, and non-transactional commit paths.
Replication heads are derived from the active MySQL server UUID instead of storing the complete Executed_Gtid_Set.
Multi-interval and tagged GTID entries are reduced to a single uuid:transaction_id, preventing invalid or NaN comparable LSNs.
Servers with no transactions for the active UUID use a synthetic uuid:0 GTID while retaining the current binlog coordinates.
Resume validation now checks:
- The source server UUID has not changed.
- The binlog file and stored offset remain available.
- Non-zero GTIDs are still present in gtid_executed.
Invalid or rewound resume positions trigger a fresh snapshot.
MySQL replicas are rejected during source configuration checks.
Transactions originating from a server UUID other than the active source are rejected until multi-origin ordering is supported.
Serialized GTIDs and binlog offsets are now validated rather than silently accepting malformed values.

Tests

Added and updated unit coverage for GTID parsing, zero GTIDs, resume validation, replica detection, malformed serialization, and committed keepalive positions.

Current limitations

PowerSync still does not support replication directly from a MySQL replica or binlogs containing transactions from multiple active origins. MySQL 8.4 GTID tags are not preserved; tagged entries are normalized to uuid:transaction_id.

🤖 AI disclosure: Investigated and reproduced issues with Claude Code working from the customer's logs.
Implementation, tests and review were done using Claude Opus 5 and ChatGPT 5.6. Directed and reviewed by @michaelbarnes, @Rentacookie @bean1352

Heartbeat keepalives re-sent the LSN from the start of the last transaction, while checkpoints store the LSN from the end of the same transaction. On an idle server this blocked checkpoint creation ("Waiting before creating checkpoint" every ~30s) until the next transaction arrived. All commit paths (Xid, DDL auto-commit, non-transactional query) now advance the current GTID position to the commit position, so keepalive LSNs are never behind the last checkpoint LSN. The listener also no longer mutates the caller's startGTID position object. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

ReplicatedGTID.comparable assumed a single server UUID in the raw GTID. A gtid_executed containing multiple server UUIDs (e.g. after a failover or restore) was mis-parsed into a NaN transaction id, producing LSNs like "0000000000000NaN|...". On servers with a low transaction count this permanently blocked checkpoint creation, and the corrupted LSN could not be recovered by a service restart. The comparable LSN now parses full GTID sets (multiple UUIDs joined with ",\n", multiple intervals per UUID) and uses the maximum transaction id across the set. Unparseable segments are skipped instead of poisoning the result. deserialize now validates the binlog offset instead of silently producing NaN. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

changeset-bot · 2026-07-01T23:49:55Z

🦋 Changeset detected

Latest commit: 8b5cf9b

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 12 packages

Name	Type
@powersync/service-module-mysql	Minor
@powersync/service-schema	Patch
@powersync/service-image	Patch
@powersync/service-core	Patch
@powersync/service-module-convex	Patch
@powersync/service-module-core	Patch
@powersync/service-module-mongodb-storage	Patch
@powersync/service-module-mongodb	Patch
@powersync/service-module-mssql	Patch
@powersync/service-module-postgres-storage	Patch
@powersync/service-module-postgres	Patch
test-client	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

Rentacookie · 2026-07-02T10:42:51Z

Hi @michaelbarnes
Thank you these changes look great! I just want to investigate the multi-server-UUID GTID sets issue a bit more.
Its good that we parse the GTID sets correctly now, but I am actually not sure what effect it has for our replication consistency were we to process GTIDs from multiple servers 😬

michaelbarnes · 2026-07-02T14:16:37Z

@Rentacookie, when you mention "am actually not sure what effect it has for our replication consistency were we to process GTIDs from multiple servers"

Do you mean multiple servers connecting to a single PowerSync Service instance?

Rentacookie · 2026-07-02T14:28:53Z

@michaelbarnes

Do you mean multiple servers connecting to a single PowerSync Service instance?

No, I mean more that events from multiple MySQL servers are appearing on binlog for the MySQL server that PowerSync is actually connected to. I believe this can happen if the MySQL DB we are connecting to is a replica itself, replicating from other MySQL servers.

Rentacookie

Since the multi server uuid is unsupported, for now we'll add a check that does not allow replication to continue if multiple server uuids are found on the binlog.

…e binlog

bean1352 · 2026-08-06T08:00:23Z

Since the multi server uuid is unsupported, for now we'll add a check that does not allow replication to continue if multiple server uuids are found on the binlog.

I went with a warning rather than a hard stop. Happy to make it a hard error instead if you'd prefer.

Rentacookie · 2026-08-06T08:29:31Z

Since the multi server uuid is unsupported, for now we'll add a check that does not allow replication to continue if multiple server uuids are found on the binlog.

I went with a warning rather than a hard stop. Happy to make it a hard error instead if you'd prefer.

I reckon that is fine for now until we implement the full multi server uuid handling.

Rentacookie

Discussed strategy for selecting current server uuid for choosing which uuidset to use.

…or consistency and added validation for single GTID constraints

…ntax handling and tests

…t cross-server transaction processing errors and handle GTID changes more robustly.

Rentacookie · 2026-08-07T21:26:59Z

 export class ReplicatedGTID {
+  private options: ReplicatedGTIDSpecification;
+
+  constructor(options: ReplicatedGTIDSpecification) {


The main focus here is to ensure that a ReplicatedGTID only represents a single GTID since that preserves the integrity of our checkpoint LSNs.

That means no GTID sets and no transaction ranges are allowed. GTIDs read from events on the Binlog were always already in this format.

When reading the executed GTID set to determine the replication head and for snapshot checkpoints we now determine the correct single GTID based on the active server uuid.

Rentacookie · 2026-08-07T21:37:50Z

+            return false;
+          }
+
+          const isAvailable = await common.isGtidPositionStillAvailable(connection, lastKnowGTID);


In addition to checking if the binlog is still available, we now do the following validation on the resume LSN's GTID as well:

Confirm that the server uuid from the GTID matches the active server uuid

That the transaction id from the GTID is actually still available on the server

If these checks fail a full re-snapshot is required.

michaelbarnes and others added 2 commits July 1, 2026 17:21

michaelbarnes requested a review from Rentacookie July 1, 2026 23:51

Rentacookie added 2 commits August 4, 2026 12:54

Merge branch 'main' into fix/mysql-idle-keepalive-and-gtid-set-parsing

3e225c1

Merge branch 'main' into fix/mysql-idle-keepalive-and-gtid-set-parsing

436683e

Rentacookie marked this pull request as ready for review August 5, 2026 12:22

Rentacookie approved these changes Aug 5, 2026

View reviewed changes

Rentacookie requested changes Aug 5, 2026

View reviewed changes

Warn when multiple server UUIDs are detected in the GTID set or on th…

ab7af18

…e binlog

Rentacookie approved these changes Aug 6, 2026

View reviewed changes

Rentacookie requested changes Aug 6, 2026

View reviewed changes

stevensJourney reviewed Aug 6, 2026

View reviewed changes

Comment thread modules/module-mysql/src/common/ReplicatedGTID.ts Outdated

Order LSNs by the connected server's GTID counter

e773be7

Rentacookie reviewed Aug 6, 2026

View reviewed changes

Comment thread modules/module-mysql/src/common/ReplicatedGTID.ts

Rentacookie added 5 commits August 7, 2026 12:44

Refactored GTID parsing and serialization logic in ReplicatedGTID f…

b6ac720

…or consistency and added validation for single GTID constraints

Add replica check to MySQL source configuration with version-based sy…

0492075

…ntax handling and tests

Enforce active server UUID consistency in MySQL replication to preven…

36817b7

…t cross-server transaction processing errors and handle GTID changes more robustly.

Updated changeset

f58faa7

Ensure active server UUID is always set

e3ca1d4

Rentacookie self-requested a review August 7, 2026 11:31

Rentacookie added 2 commits August 7, 2026 13:52

Handle GTID reset for a restored mysql server with a different UUID

ce722ec

Improve GTID initialization logic

8b5cf9b

Rentacookie reviewed Aug 7, 2026

View reviewed changes

Navigation Menu

Uh oh!

[MySQL] Fix idle keepalive LSN stall and multi-server-UUID GTID parsing - #706

[MySQL] Fix idle keepalive LSN stall and multi-server-UUID GTID parsing#706
michaelbarnes wants to merge 13 commits into
mainfrom
fix/mysql-idle-keepalive-and-gtid-set-parsing

michaelbarnes commented Jul 1, 2026 •

edited by Rentacookie

Loading

Uh oh!

changeset-bot Bot commented Jul 1, 2026 •

edited

Loading

Uh oh!

Rentacookie commented Jul 2, 2026

Uh oh!

michaelbarnes commented Jul 2, 2026

Uh oh!

Rentacookie commented Jul 2, 2026 •

edited

Loading

Uh oh!

Rentacookie left a comment

Uh oh!

bean1352 commented Aug 6, 2026

Uh oh!

Rentacookie commented Aug 6, 2026

Uh oh!

Rentacookie left a comment

Uh oh!

Uh oh!

Uh oh!

Rentacookie Aug 7, 2026 •

edited

Loading

Uh oh!

Rentacookie Aug 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

michaelbarnes commented Jul 1, 2026 • edited by Rentacookie Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Background

Changes

Tests

Current limitations

Uh oh!

changeset-bot Bot commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

Rentacookie commented Jul 2, 2026

Uh oh!

michaelbarnes commented Jul 2, 2026

Uh oh!

Rentacookie commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Rentacookie left a comment

Choose a reason for hiding this comment

Uh oh!

bean1352 commented Aug 6, 2026

Uh oh!

Rentacookie commented Aug 6, 2026

Uh oh!

Rentacookie left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Rentacookie Aug 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Rentacookie Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

michaelbarnes commented Jul 1, 2026 •

edited by Rentacookie

Loading

changeset-bot Bot commented Jul 1, 2026 •

edited

Loading

Rentacookie commented Jul 2, 2026 •

edited

Loading

Rentacookie Aug 7, 2026 •

edited

Loading