Skip to content

Commit 3c2d667

Browse files
patrickbirchpatrickbirch
committed
PS-10594 [DOCS] - Document Binary log server
 new file: docs/build-from-source.md new file: docs/command-reference.md new file: docs/configuration-reference.md new file: docs/get-started.md modified: docs/index.md new file: docs/install.md new file: docs/operational-behavior-reference.md new file: docs/storage-reference.md modified: mkdocs-base.yml
1 parent ac04ff3 commit 3c2d667

13 files changed

+1007
-3
lines changed

‎docs/_static/binlog-arch.png‎

22 KB
Loading

‎docs/build-from-source.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# Build Percona Binary Log Server From Source
2+
3+
Use a source build when local compilation, debugging, packaging work, or source-code changes are required.
4+
5+
For general product information, command usage, and configuration details, see the main page:
6+
7+
* [Percona Binary Log Server](index.md)
8+
9+
## Build Requirements
10+
11+
Build from source with CMake and a supported compiler.
12+
13+
Dependencies:
14+
15+
* CMake 3.20.0 or later
16+
17+
* Clang 15 through 19, or GCC 12 through 14
18+
19+
* Boost 1.88.0 from the Boost Git repository
20+
21+
* MySQL client library 8.0.x (`libmysqlclient`)
22+
23+
* libcurl 8.6.0 or later
24+
25+
* AWS SDK for C++ 1.11.570
26+
27+
## Create a Build Workspace
28+
29+
```bash
30+
mkdir ws
31+
cd ws
32+
```
33+
34+
## Clone the Source Repository
35+
36+
```bash
37+
git clone https://github.com/Percona-Lab/percona-binlog-server.git
38+
```
39+
40+
## Select a Build Preset
41+
42+
Set `BUILD_PRESET` to a supported configuration and toolchain.
43+
44+
Supported configurations:
45+
46+
* `debug`
47+
48+
* `release`
49+
50+
* `asan`
51+
52+
Supported toolchains:
53+
54+
* `gcc14`
55+
56+
* `clang19`
57+
58+
Example:
59+
60+
```bash
61+
export BUILD_PRESET=release_gcc14
62+
```
63+
64+
## Build Boost
65+
66+
```bash
67+
git clone --recurse-submodules -b boost-1.88.0 --jobs=8 https://github.com/boostorg/boost.git
68+
cd boost
69+
git switch -c required_release
70+
cp ../percona-binlog-server/extra/cmake_presets/boost/CMakePresets.json .
71+
cmake . --preset "${BUILD_PRESET}"
72+
cmake --build "../boost-build-${BUILD_PRESET}" --parallel
73+
cmake --install "../boost-build-${BUILD_PRESET}"
74+
cd ..
75+
```
76+
77+
## Build AWS SDK for C++
78+
79+
```bash
80+
git clone --recurse-submodules -b 1.11.570 --jobs=8 https://github.com/aws/aws-sdk-cpp
81+
cd aws-sdk-cpp
82+
git switch -c required_release
83+
cp ../percona-binlog-server/extra/cmake_presets/aws-sdk-cpp/CMakePresets.json .
84+
cmake . --preset "${BUILD_PRESET}"
85+
cmake --build "../aws-sdk-cpp-build-${BUILD_PRESET}" --parallel
86+
cmake --install "../aws-sdk-cpp-build-${BUILD_PRESET}"
87+
cd ..
88+
```
89+
90+
## Build Percona Binary Log Server
91+
92+
```bash
93+
cmake ./percona-binlog-server --preset "${BUILD_PRESET}"
94+
cmake --build "./percona-binlog-server-build-${BUILD_PRESET}" --parallel
95+
```
96+
97+
The final binary is available at:
98+
99+
```text
100+
ws/percona-binlog-server-build-${BUILD_PRESET}/binlog_server
101+
```
102+
103+
Source project: [Percona Binary Log Server README](https://github.com/Percona-Lab/percona-binlog-server/blob/main/README.md)

‎docs/command-reference.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
# Command Reference
2+
3+
Percona Binary Log Server supports the following command syntax:
4+
5+
```bash
6+
./binlog_server version
7+
./binlog_server fetch <json_config_file>
8+
./binlog_server pull <json_config_file>
9+
./binlog_server search_by_timestamp <json_config_file> <timestamp>
10+
./binlog_server search_by_gtid_set <json_config_file> <gtid_set>
11+
```
12+
13+
Arguments:
14+
15+
* `<json_config_file>`: path to a JSON configuration file
16+
17+
* `<timestamp>`: ISO timestamp such as `2026-02-10T14:30:00`
18+
19+
* `<gtid_set>`: GTID set such as `11111111-aaaa-1111-aaaa-111111111111:1:3,22222222-bbbb-2222-bbbb-222222222222:1-6`
20+
21+
## `version`
22+
23+
`version` prints the semantic version embedded in the binary and exits with status code `0`.
24+
25+
Example:
26+
27+
```bash
28+
./binlog_server version
29+
```
30+
31+
Example output:
32+
33+
```text
34+
0.1.0
35+
```
36+
37+
## `fetch`
38+
39+
`fetch` connects to the remote MySQL server, reads all binary log events currently available on that server, stores the data, then exits.
40+
41+
Use `fetch` when a one-time archive run is needed.
42+
43+
Behavior summary:
44+
45+
* reading existing binary logs from the source server
46+
47+
* exiting after the last available event
48+
49+
* stopping immediately on errors such as network loss or storage failure
50+
51+
## `pull`
52+
53+
`pull` connects to the remote MySQL server, reads binary log events, waits for more events, disconnects after `connection.read_timeout`, sleeps for `replication.idle_time`, then reconnects and continues.
54+
55+
Use `pull` when continuous collection is needed.
56+
57+
Behavior summary:
58+
59+
* following new binary log events over time
60+
61+
* retrying after network-related failures
62+
63+
* stopping on serious failures such as storage problems
64+
65+
## `search_by_timestamp`
66+
67+
`search_by_timestamp` returns the list of saved binary log files that contain at least one event with a timestamp less than or equal to the supplied timestamp.
68+
69+
Example:
70+
71+
```bash
72+
./binlog_server search_by_timestamp config.json 2026-02-10T14:30:00
73+
```
74+
75+
Example successful output:
76+
77+
```json
78+
{
79+
"status": "success",
80+
"result": [
81+
{
82+
"name": "binlog.000001",
83+
"size": 134217728,
84+
"uri": "s3://binsrv-bucket/storage/binlog.000001",
85+
"min_timestamp": "2026-02-09T17:22:01",
86+
"max_timestamp": "2026-02-09T17:22:08",
87+
"initial_gtids": "",
88+
"added_gtids": "11111111-aaaa-1111-aaaa-111111111111:1-123456"
89+
},
90+
{
91+
"name": "binlog.000002",
92+
"size": 134217728,
93+
"uri": "s3://binsrv-bucket/storage/binlog.000002",
94+
"min_timestamp": "2026-02-09T17:22:08",
95+
"max_timestamp": "2026-02-09T17:22:09",
96+
"initial_gtids": "11111111-aaaa-1111-aaaa-111111111111:1-123456",
97+
"added_gtids": "11111111-aaaa-1111-aaaa-111111111111:123457-246912"
98+
}
99+
]
100+
}
101+
```
102+
103+
Possible error messages include:
104+
105+
* `Invalid timestamp format`
106+
107+
* `Binlog storage is empty`
108+
109+
* `Timestamp is too old`
110+
111+
## `search_by_gtid_set`
112+
113+
`search_by_gtid_set` returns the minimum set of saved binary log files required to cover the supplied GTID set. This mode requires storage created with GTID-based replication.
114+
115+
Example:
116+
117+
```bash
118+
./binlog_server search_by_gtid_set config.json 11111111-aaaa-1111-aaaa-111111111111:10-20
119+
```
120+
121+
Example successful output:
122+
123+
```json
124+
{
125+
"status": "success",
126+
"result": [
127+
{
128+
"name": "binlog.000001",
129+
"size": 134217728,
130+
"uri": "s3://binsrv-bucket/storage/binlog.000001",
131+
"min_timestamp": "2026-02-09T17:22:01",
132+
"max_timestamp": "2026-02-09T17:22:08",
133+
"initial_gtids": "",
134+
"added_gtids": "11111111-aaaa-1111-aaaa-111111111111:1-123456"
135+
}
136+
]
137+
}
138+
```
139+
140+
Possible error messages include:
141+
142+
* `cannot parse GTID set`
143+
144+
* `Binlog storage is empty`
145+
146+
* `The specified GTID set cannot be covered`
147+
148+
* `GTID set search is not supported in storages created in position-based replication mode`

0 commit comments

Comments
 (0)