Skip to content

Latest commit

 

History

History
181 lines (125 loc) · 4.99 KB

v1.2.4.md

File metadata and controls

181 lines (125 loc) · 4.99 KB

MygramDB v1.2.4 Release Notes

Release Date: 2025-11-21 Type: Patch Release (Critical Bug Fix)

Overview

Version 1.2.4 is a critical patch release that fixes a GTID parsing crash affecting systems with multiple MySQL replication sources. This issue was discovered in production environments running MySQL 8.4 with complex replication topologies. The release also includes a fix for RPM package upgrade errors.

Critical Fixes

1. GTID Parsing Crash (MySQL 8.4 Compatibility)

Problem: MygramDB would crash with std::invalid_argument during replication startup when receiving GTID strings from MySQL 8.4 servers with multiple replication sources.

Root Cause:

  • MySQL 8.4's GTID formatting includes embedded newlines for readability when multiple UUIDs are present
  • Format: uuid1:1-100,\nuuid2:1-200,\nuuid3:1-300 (comma followed by newline)
  • This is MySQL's official behavior defined in default_string_format with ",\n" as the UUID separator
  • Long GTID strings (6+ UUIDs from multiple replication sources) would cause parsing failures

Solution:

  • GTID strings are now normalized by removing all whitespace characters (newlines, spaces, tabs)
  • Implementation follows MySQL's official parser behavior (SKIP_WHITESPACE() macro)
  • Compatible with both single and multi-source replication topologies

Affected Scenarios:

  • Systems replicating from multiple MySQL sources
  • MySQL 8.4 servers with long GTID execution sets
  • Production environments observed with 6 UUIDs (292 characters, 5 newlines)

Example GTID Format:

Original (from MySQL):
023cdb62-8398-11ee-9327-4a0008d26241:1-8178383,
ba13f0ad-f09a-11e8-b079-b2869295776e:1-183978832,
cf65e299-d4d1-11ec-9b58-caab0c3eeec8:1-107084115

Normalized (by MygramDB):
023cdb62-8398-11ee-9327-4a0008d26241:1-8178383,ba13f0ad-f09a-11e8-b079-b2869295776e:1-183978832,cf65e299-d4d1-11ec-9b58-caab0c3eeec8:1-107084115

Technical Details:

  • Modified: src/storage/snapshot_builder.cpp
  • Uses std::remove_if with std::isspace for whitespace removal
  • Applied immediately after GTID retrieval from MySQL
  • Zero performance impact (one-time operation during snapshot)

2. RPM Package Upgrade Failures

Problem: RPM package upgrades would fail with "fg: no job control" error during the preun scriptlet execution.

Solution:

  • Added error suppression to %systemd_preun macro in RPM spec
  • Syntax: %systemd_preun %{name}.service || :
  • Ensures smooth package updates without manual intervention

Benefits:

  • Eliminates upgrade failures on production systems
  • No service interruption during package updates
  • Compatible with all supported Linux distributions

Testing

New Test Coverage

Added comprehensive GTID whitespace handling tests (tests/integration/server/gtid_dump_test.cpp):

Test Cases:

  1. Single UUID with trailing newlines
  2. Multiple UUIDs with newlines after commas (MySQL 8.4 format)
  3. Real-world 6-UUID production scenario
  4. Mixed whitespace (spaces, tabs, newlines)
  5. Leading and trailing whitespace

Validation:

  • All 13 GTID integration tests passing
  • Verified against MySQL 8.4.7 behavior
  • Tested with production-scale GTID strings (292 characters)

Migration Guide

From v1.2.3

No configuration changes required. This is a transparent bug fix release.

Upgrade Steps:

Docker users:

# Pull the new image
docker pull ghcr.io/libraz/mygram-db:v1.2.4

# Or update docker-compose.yml
services:
  mygramdb:
    image: ghcr.io/libraz/mygram-db:v1.2.4

RPM users:

# Download and install new RPM
sudo rpm -Uvh mygramdb-1.2.4-1.el9.x86_64.rpm

Source build:

git checkout v1.2.4
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel

Rollback Procedure

If issues arise, rollback is straightforward:

# Docker
docker pull ghcr.io/libraz/mygram-db:v1.2.3

# RPM
sudo rpm -Uvh --oldpackage mygramdb-1.2.3-1.el9.x86_64.rpm

Compatibility

MySQL Versions:

  • MySQL 8.0.x ✓
  • MySQL 8.4.x ✓ (now fully compatible)

Operating Systems:

  • Linux (all major distributions)
  • macOS (development/testing)

Breaking Changes: None

Deprecated Features: None

Performance Impact

Zero performance impact:

  • GTID normalization is a one-time operation during snapshot
  • No changes to query execution or binlog processing
  • No additional memory allocation

Known Issues

None.

Upgrade Recommendation

Priority: High for production systems using:

  • MySQL 8.4
  • Multi-source replication
  • RPM-based deployments

Priority: Low for:

  • Single-source replication setups
  • MySQL 8.0 without multi-source replication

Contributors

  • @libraz

Links

Questions or Issues? Please open an issue on GitHub Issues