Skip to content

Commit a59ca2f

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 a59ca2f

15 files changed

+1480
-4
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 (the provided CMake presets for Boost, AWS SDK, and the main application require CMake 3.21.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: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
# Command Reference
2+
3+
Percona Binary Log Server supports the following commands. Use the tables in this section to find a command or argument quickly.
4+
5+
## Commands and arguments
6+
7+
| Command | Arguments | Description |
8+
|--------|-----------|-------------|
9+
| `version` | (none) | Prints the semantic version and exits with status 0. |
10+
| `fetch` | `<json_config_file>` | One-time collection: reads all available binlog events from the source, writes to storage, then exits. |
11+
| `pull` | `<json_config_file>` | Continuous collection: reads binlog events, waits for more, reconnects as needed, runs until stopped. |
12+
| `search_by_timestamp` | `<json_config_file>` `<timestamp>` | Returns stored binlog files that contain events with timestamp ≤ the given ISO timestamp. |
13+
| `search_by_gtid_set` | `<json_config_file>` `<gtid_set>` | Returns the minimal set of stored binlog files that cover the given GTID set (GTID mode only). |
14+
15+
| Argument | Description |
16+
|----------|-------------|
17+
| `<json_config_file>` | Path to the JSON configuration file. |
18+
| `<timestamp>` | ISO timestamp (for example, `2026-02-10T14:30:00`). |
19+
| `<gtid_set>` | GTID set (for example, `11111111-aaaa-1111-aaaa-111111111111:1:3,22222222-bbbb-2222-bbbb-222222222222:1-6`). |
20+
21+
## Operation modes summary
22+
23+
| Mode | When to use | Behavior |
24+
|------|-------------|----------|
25+
| `version` | Check installed version. | Prints version, exits 0. |
26+
| `fetch` | One-time or on-demand archive. | Connects, reads all current events, writes to storage, exits. Stops on any error. |
27+
| `pull` | Continuous binlog collection. | Connects, reads events, waits for more; reconnects after timeout or network error. Runs until stopped or fatal error. |
28+
| `search_by_timestamp` | Find files for point-in-time recovery by time. | Reads metadata, returns list of stored files with events up to the given timestamp. |
29+
| `search_by_gtid_set` | Find minimal file set for a GTID set. | Reads metadata, returns minimal set of stored files covering the GTID set. Requires GTID-based storage. |
30+
31+
## Command syntax
32+
33+
```bash
34+
./binlog_server version
35+
./binlog_server fetch <json_config_file>
36+
./binlog_server pull <json_config_file>
37+
./binlog_server search_by_timestamp <json_config_file> <timestamp>
38+
./binlog_server search_by_gtid_set <json_config_file> <gtid_set>
39+
```
40+
41+
## `version`
42+
43+
`version` prints the semantic version embedded in the binary and exits with status code `0`.
44+
45+
Example:
46+
47+
```bash
48+
./binlog_server version
49+
```
50+
51+
Example output:
52+
53+
```text
54+
0.1.0
55+
```
56+
57+
## `fetch`
58+
59+
`fetch` connects to the remote MySQL server, reads all binary log events currently available on that server, stores the data, then exits.
60+
61+
Use `fetch` when a one-time archive run is needed.
62+
63+
Behavior summary:
64+
65+
* reading existing binary logs from the source server
66+
67+
* exiting after the last available event
68+
69+
* stopping immediately on errors such as network loss or storage failure
70+
71+
## `pull`
72+
73+
`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.
74+
75+
Use `pull` when continuous collection is needed.
76+
77+
Behavior summary:
78+
79+
* following new binary log events over time
80+
81+
* retrying after network-related failures
82+
83+
* stopping on serious failures such as storage problems
84+
85+
## `search_by_timestamp`
86+
87+
`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.
88+
89+
Example:
90+
91+
```bash
92+
./binlog_server search_by_timestamp config.json 2026-02-10T14:30:00
93+
```
94+
95+
Example successful output:
96+
97+
```json
98+
{
99+
"status": "success",
100+
"result": [
101+
{
102+
"name": "binlog.000001",
103+
"size": 134217728,
104+
"uri": "s3://binsrv-bucket/storage/binlog.000001",
105+
"min_timestamp": "2026-02-09T17:22:01",
106+
"max_timestamp": "2026-02-09T17:22:08",
107+
"initial_gtids": "",
108+
"added_gtids": "11111111-aaaa-1111-aaaa-111111111111:1-123456"
109+
},
110+
{
111+
"name": "binlog.000002",
112+
"size": 134217728,
113+
"uri": "s3://binsrv-bucket/storage/binlog.000002",
114+
"min_timestamp": "2026-02-09T17:22:08",
115+
"max_timestamp": "2026-02-09T17:22:09",
116+
"initial_gtids": "11111111-aaaa-1111-aaaa-111111111111:1-123456",
117+
"added_gtids": "11111111-aaaa-1111-aaaa-111111111111:123457-246912"
118+
}
119+
]
120+
}
121+
```
122+
123+
Possible error messages include:
124+
125+
* `Invalid timestamp format`
126+
127+
* `Binlog storage is empty`
128+
129+
* `Timestamp is too old`
130+
131+
## `search_by_gtid_set`
132+
133+
`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.
134+
135+
Example:
136+
137+
```bash
138+
./binlog_server search_by_gtid_set config.json 11111111-aaaa-1111-aaaa-111111111111:10-20
139+
```
140+
141+
Example successful output:
142+
143+
```json
144+
{
145+
"status": "success",
146+
"result": [
147+
{
148+
"name": "binlog.000001",
149+
"size": 134217728,
150+
"uri": "s3://binsrv-bucket/storage/binlog.000001",
151+
"min_timestamp": "2026-02-09T17:22:01",
152+
"max_timestamp": "2026-02-09T17:22:08",
153+
"initial_gtids": "",
154+
"added_gtids": "11111111-aaaa-1111-aaaa-111111111111:1-123456"
155+
}
156+
]
157+
}
158+
```
159+
160+
Possible error messages include:
161+
162+
* `cannot parse GTID set`
163+
164+
* `Binlog storage is empty`
165+
166+
* `The specified GTID set cannot be covered`
167+
168+
* `GTID set search is not supported in storages created in position-based replication mode`

0 commit comments

Comments
 (0)