Skip to content

Commit 417fc2e

Browse files
librazlibraz
committed
docs: add v1.2.4 release documentation
- Add comprehensive v1.2.4 release notes - Document GTID parsing fix and RPM upgrade fix - Update changelog with critical bug fixes - Update release notes index
1 parent 1e632c3 commit 417fc2e

File tree

3 files changed

+208
-1
lines changed

3 files changed

+208
-1
lines changed

‎CHANGELOG.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
77

88
## [Unreleased]
99

10+
## [1.2.4] - 2025-11-21
11+
12+
### Fixed
13+
14+
- **Critical: Fixed GTID parsing crash during replication startup (MySQL 8.4 compatibility)**
15+
- MySQL 8.4 returns GTID strings with embedded newlines for readability (e.g., `uuid1:1-100,\nuuid2:1-200`)
16+
- Long GTID strings from multiple replication sources would cause `std::invalid_argument` crash
17+
- Now properly removes whitespace from GTID strings, following MySQL's official parser behavior
18+
- Affects systems replicating from multiple MySQL sources (6+ UUIDs)
19+
- Fixed RPM package upgrade failures
20+
- Added error suppression to `%systemd_preun` macro
21+
- Eliminates "fg: no job control" errors during package updates
22+
- Ensures smooth upgrades without manual intervention
23+
24+
### Added
25+
26+
- Comprehensive GTID whitespace handling tests
27+
- 5 test cases covering various whitespace patterns (newlines, spaces, tabs)
28+
- Real-world 6-UUID production scenario validation
29+
- Documented MySQL 8.4 GTID formatting behavior
30+
1031
## [1.2.3] - 2025-11-20
1132

1233
### Added

‎docs/releases/README.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,11 @@ This directory contains detailed release notes for each version of MygramDB.
44

55
## Available Versions
66

7-
- [v1.2.0](v1.2.0.md) - Latest release (2025-11-19)
7+
- [v1.2.4](v1.2.4.md) - Latest release (2025-11-21) - Critical Bug Fix
8+
- [v1.2.3](v1.2.3.md) - 2025-11-20
9+
- [v1.2.2](v1.2.2.md) - 2025-11-20
10+
- [v1.2.1](v1.2.1.md) - 2025-11-19
11+
- [v1.2.0](v1.2.0.md) - 2025-11-19
812
- [v1.1.0](v1.1.0.md) - Production-ready release (2025-11-17)
913
- v1.0.0 - Initial release (2025-11-13)
1014

‎docs/releases/v1.2.4.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
# MygramDB v1.2.4 Release Notes
2+
3+
**Release Date:** 2025-11-21
4+
**Type:** Patch Release (Critical Bug Fix)
5+
6+
---
7+
8+
## Overview
9+
10+
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.
11+
12+
## Critical Fixes
13+
14+
### 1. GTID Parsing Crash (MySQL 8.4 Compatibility)
15+
16+
**Problem:** MygramDB would crash with `std::invalid_argument` during replication startup when receiving GTID strings from MySQL 8.4 servers with multiple replication sources.
17+
18+
**Root Cause:**
19+
- MySQL 8.4's GTID formatting includes embedded newlines for readability when multiple UUIDs are present
20+
- Format: `uuid1:1-100,\nuuid2:1-200,\nuuid3:1-300` (comma followed by newline)
21+
- This is MySQL's official behavior defined in `default_string_format` with `",\n"` as the UUID separator
22+
- Long GTID strings (6+ UUIDs from multiple replication sources) would cause parsing failures
23+
24+
**Solution:**
25+
- GTID strings are now normalized by removing all whitespace characters (newlines, spaces, tabs)
26+
- Implementation follows MySQL's official parser behavior (`SKIP_WHITESPACE()` macro)
27+
- Compatible with both single and multi-source replication topologies
28+
29+
**Affected Scenarios:**
30+
- Systems replicating from multiple MySQL sources
31+
- MySQL 8.4 servers with long GTID execution sets
32+
- Production environments observed with 6 UUIDs (292 characters, 5 newlines)
33+
34+
**Example GTID Format:**
35+
36+
```
37+
Original (from MySQL):
38+
023cdb62-8398-11ee-9327-4a0008d26241:1-8178383,
39+
ba13f0ad-f09a-11e8-b079-b2869295776e:1-183978832,
40+
cf65e299-d4d1-11ec-9b58-caab0c3eeec8:1-107084115
41+
42+
Normalized (by MygramDB):
43+
023cdb62-8398-11ee-9327-4a0008d26241:1-8178383,ba13f0ad-f09a-11e8-b079-b2869295776e:1-183978832,cf65e299-d4d1-11ec-9b58-caab0c3eeec8:1-107084115
44+
```
45+
46+
**Technical Details:**
47+
- Modified: `src/storage/snapshot_builder.cpp`
48+
- Uses `std::remove_if` with `std::isspace` for whitespace removal
49+
- Applied immediately after GTID retrieval from MySQL
50+
- Zero performance impact (one-time operation during snapshot)
51+
52+
### 2. RPM Package Upgrade Failures
53+
54+
**Problem:** RPM package upgrades would fail with "fg: no job control" error during the preun scriptlet execution.
55+
56+
**Solution:**
57+
- Added error suppression to `%systemd_preun` macro in RPM spec
58+
- Syntax: `%systemd_preun %{name}.service || :`
59+
- Ensures smooth package updates without manual intervention
60+
61+
**Benefits:**
62+
- Eliminates upgrade failures on production systems
63+
- No service interruption during package updates
64+
- Compatible with all supported Linux distributions
65+
66+
## Testing
67+
68+
### New Test Coverage
69+
70+
Added comprehensive GTID whitespace handling tests (`tests/integration/server/gtid_dump_test.cpp`):
71+
72+
**Test Cases:**
73+
1. Single UUID with trailing newlines
74+
2. Multiple UUIDs with newlines after commas (MySQL 8.4 format)
75+
3. Real-world 6-UUID production scenario
76+
4. Mixed whitespace (spaces, tabs, newlines)
77+
5. Leading and trailing whitespace
78+
79+
**Validation:**
80+
- All 13 GTID integration tests passing
81+
- Verified against MySQL 8.4.7 behavior
82+
- Tested with production-scale GTID strings (292 characters)
83+
84+
## Migration Guide
85+
86+
### From v1.2.3
87+
88+
**No configuration changes required.** This is a transparent bug fix release.
89+
90+
**Upgrade Steps:**
91+
92+
**Docker users:**
93+
94+
```bash
95+
# Pull the new image
96+
docker pull ghcr.io/libraz/mygram-db:v1.2.4
97+
98+
# Or update docker-compose.yml
99+
services:
100+
mygramdb:
101+
image: ghcr.io/libraz/mygram-db:v1.2.4
102+
```
103+
104+
**RPM users:**
105+
106+
```bash
107+
# Download and install new RPM
108+
sudo rpm -Uvh mygramdb-1.2.4-1.el9.x86_64.rpm
109+
```
110+
111+
**Source build:**
112+
113+
```bash
114+
git checkout v1.2.4
115+
cmake -B build -DCMAKE_BUILD_TYPE=Release
116+
cmake --build build --parallel
117+
```
118+
119+
### Rollback Procedure
120+
121+
If issues arise, rollback is straightforward:
122+
123+
```bash
124+
# Docker
125+
docker pull ghcr.io/libraz/mygram-db:v1.2.3
126+
127+
# RPM
128+
sudo rpm -Uvh --oldpackage mygramdb-1.2.3-1.el9.x86_64.rpm
129+
```
130+
131+
## Compatibility
132+
133+
**MySQL Versions:**
134+
- MySQL 8.0.x ✓
135+
- MySQL 8.4.x ✓ (now fully compatible)
136+
- MariaDB 10.x ✓
137+
138+
**Operating Systems:**
139+
- Linux (all major distributions)
140+
- macOS (development/testing)
141+
142+
**Breaking Changes:** None
143+
144+
**Deprecated Features:** None
145+
146+
## Performance Impact
147+
148+
**Zero performance impact:**
149+
- GTID normalization is a one-time operation during snapshot
150+
- No changes to query execution or binlog processing
151+
- No additional memory allocation
152+
153+
## Known Issues
154+
155+
None.
156+
157+
## Upgrade Recommendation
158+
159+
**Priority:** High for production systems using:
160+
- MySQL 8.4
161+
- Multi-source replication
162+
- RPM-based deployments
163+
164+
**Priority:** Low for:
165+
- Single-source replication setups
166+
- MySQL 8.0 without multi-source replication
167+
168+
## Contributors
169+
170+
- @libraz
171+
172+
## Links
173+
174+
- [Full Changelog](https://github.com/libraz/mygram-db/compare/v1.2.3...v1.2.4)
175+
- [Docker Image](https://github.com/libraz/mygram-db/pkgs/container/mygram-db)
176+
- [Configuration Reference](../en/configuration.md)
177+
- [Replication Guide](../en/replication.md)
178+
179+
---
180+
181+
**Questions or Issues?**
182+
Please open an issue on [GitHub Issues](https://github.com/libraz/mygram-db/issues)

0 commit comments

Comments
 (0)