Skip to content

Commit 4c4b85b

Browse files
patrickbirchpatrickbirch
committed
PS-11496 [DOCS] - Review MyRocks server variables 8.4
 modified: docs/myrocks-server-variables.md
1 parent 6cdb7d9 commit 4c4b85b

5 files changed

Lines changed: 343 additions & 15 deletions

File tree

‎docs/myrocks-background-jobs.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Size MyRocks background jobs
2+
3+
Select [`rocksdb_max_background_jobs`](myrocks-server-variables.md#rocksdb_max_background_jobs) from the workload of the host. The value shares CPU cores with foreground query threads. Compaction receives roughly three quarters of the configured jobs. See [Slot distribution between flushes and compaction](myrocks-server-variables.md#slot-distribution-between-flushes-and-compaction).
4+
5+
## Dedicated MyRocks instance
6+
7+
Set `rocksdb_max_background_jobs` equal to the physical CPU core count. RocksDB `IncreaseParallelism()` uses a one-to-one mapping for dedicated key-value workloads. MyRocks applies the same limit through `rocksdb_max_background_jobs`. Use the one-to-one ratio when MyRocks can consume host CPU for flush and compaction.
8+
9+
## Database server with mixed query traffic
10+
11+
Set `rocksdb_max_background_jobs` to the CPU core count divided by four. The result is 25 percent of available cores. The one-to-four ratio leaves CPU for foreground query threads.
12+
13+
## Write-heavy workload on NVMe storage
14+
15+
Set `rocksdb_max_background_jobs` to the CPU core count divided by two. The result is 50 percent of available cores. Cap the value at eight to 16 jobs. Values above 16 add thread contention and latency variance without higher throughput.
16+
17+
## Starting values by core count
18+
19+
| Available CPU cores | Dedicated instance (1:1) | Database server (1:4) | Write-heavy NVMe (1:2, cap 8 to 16) |
20+
|---------------------|--------------------------|-----------------------|-------------------------------------|
21+
| 4 | 4 | 1 | 2 |
22+
| 8 | 8 | 2 | 4 |
23+
| 16 | 16 | 4 | 8 |
24+
| 32 | 32 | 8 | 8 to 16 |
25+
| 64 or more | 64 | 16 | 16 |
26+
27+
The database-server column uses integer division. Four cores produce one job. Raise that value to two only when write stalls persist and the host retains spare CPU.
28+
29+
## Combined thread budget
30+
31+
Keep the sum of active client threads and `rocksdb_max_background_jobs` at or below the logical CPU thread count. A sum above that count increases latency through CPU context switches.
32+
33+
On a server that also runs InnoDB, include InnoDB purge threads and page-cleaner threads in the same budget.

‎docs/myrocks-index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,8 @@ engines, if your workload uses fast storage, such as SSD:
4646

4747
[MyRocks Server Variables](myrocks-server-variables.md)
4848

49+
[Size MyRocks background jobs](myrocks-background-jobs.md)
50+
4951
[MyRocks Information Schema Tables](myrocks-information-schema-tables.md)
5052

5153
[Performance Schema MyRocks changes](performance-schema-myrocks-changes.md)

‎docs/myrocks-limitations.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,134 @@ These operations does not require a full table rebuild. However, operations that
2626

2727
**Note:** Dropping a partition permanently deletes any data stored in it unless that data is reassigned to another partition.
2828

29+
`INPLACE` `ADD PARTITION` and `DROP PARTITION` require [`rocksdb_allow_unsafe_alter`](myrocks-server-variables.md#rocksdb_allow_unsafe_alter) set to `ON`. MyRocks does not support `INPLACE` `ADD PARTITION` for `HASH` partitions.
30+
31+
With `ALGORITHM=INPLACE`, the server deletes rows in the dropped partition. With `ALGORITHM=COPY`, the server can move compatible rows into another partition.
32+
33+
### Recover mismatched partition metadata
34+
35+
An `INPLACE` `ADD PARTITION` or `DROP PARTITION` under [`rocksdb_allow_unsafe_alter`](myrocks-server-variables.md#rocksdb_allow_unsafe_alter) is crash-unsafe. A stop before the operation completes can leave the MySQL data dictionary and the MyRocks data dictionary in a mismatched state. Use the following procedure to recover.
36+
37+
MyRocks does not support atomic DDL. An `INPLACE` partition alter updates storage-engine objects and data-dictionary metadata in separate stages. A stop before every stage completes can leave incomplete DDL and inconsistent metadata.
38+
39+
The incomplete DDL can produce the following outcomes:
40+
41+
* Schema mismatch between the MySQL data dictionary and the MyRocks data dictionary
42+
43+
* Orphan partition objects in MyRocks that the MySQL data dictionary does not list
44+
45+
* Partition entries in the MySQL data dictionary that lack matching MyRocks objects
46+
47+
* Startup failure when [`rocksdb_validate_tables`](myrocks-server-variables.md#rocksdb_validate_tables) equals `1`
48+
49+
* Partial `ADD PARTITION` or `DROP PARTITION` results that require repair or restore
50+
51+
!!! warning
52+
53+
The following actions can make recoverable data inaccessible.
54+
55+
* Do not repeat the interrupted `ALTER TABLE` statement.
56+
57+
* Do not edit the MyRocks data dictionary by hand.
58+
59+
* Do not delete RocksDB files.
60+
61+
* Do not run another partition operation against the affected table.
62+
63+
#### Step 1: Preserve the current state
64+
65+
1. Stop the server.
66+
67+
2. Preserve a copy or storage snapshot of the complete MySQL data directory and [`rocksdb_datadir`](myrocks-server-variables.md#rocksdb_datadir).
68+
69+
3. Retain the error log and binary logs.
70+
71+
#### Step 2: Select a recovery source
72+
73+
Recover from a known-consistent source. Use the first branch that applies:
74+
75+
| Source | Action |
76+
|--------|--------|
77+
| Healthy replica | If a healthy replica holds matching table and MyRocks metadata, use that replica as the recovery source. Rebuild the damaged server from that replica. |
78+
| Verified backup | If no healthy replica is available, restore a backup taken before the interrupted `ALTER TABLE`. Apply binary logs only to a verified consistent position. Do not replay the interrupted unsafe statement. |
79+
| No replica and no backup | If neither source exists, contact Percona Support or an experienced MyRocks administrator. Do not change the instance before that contact. |
80+
81+
#### Step 3: Diagnose a startup mismatch
82+
83+
Complete this step only when validation reports a mismatch and the server cannot start.
84+
85+
1. Run diagnostics on a copy of the damaged instance.
86+
87+
2. Start that copy in an isolated, read-only environment with the following configuration:
88+
89+
```ini
90+
[mysqld]
91+
rocksdb_validate_tables=2
92+
```
93+
94+
!!! note
95+
96+
`rocksdb_validate_tables=2` allows startup despite validation errors. This setting does not repair the mismatch.
97+
98+
3. Compare the partition definitions held by MySQL and MyRocks:
99+
100+
```sql
101+
SELECT PARTITION_NAME
102+
FROM INFORMATION_SCHEMA.PARTITIONS
103+
WHERE TABLE_SCHEMA = 'database_name'
104+
AND TABLE_NAME = 'table_name'
105+
AND PARTITION_NAME IS NOT NULL
106+
ORDER BY PARTITION_NAME;
107+
108+
SELECT DISTINCT PARTITION_NAME
109+
FROM INFORMATION_SCHEMA.ROCKSDB_DDL
110+
WHERE TABLE_SCHEMA = 'database_name'
111+
AND TABLE_NAME = 'table_name'
112+
AND PARTITION_NAME IS NOT NULL
113+
ORDER BY PARTITION_NAME;
114+
```
115+
116+
#### Step 4: Choose a recovery path
117+
118+
Select the branch that matches the query results:
119+
120+
| Condition | Action |
121+
|-----------|--------|
122+
| Every expected partition is accessible and the table reads completely | Perform a logical salvage. Complete the following logical salvage steps. |
123+
| An expected partition is missing or cannot be read | Restore from a backup or healthy replica. Do not create an empty replacement partition to force a metadata match. The interrupted operation may have deleted or orphaned data for that partition. |
124+
125+
Complete the following logical salvage steps on a copy or separate recovery instance:
126+
127+
1. Export the table schema and rows.
128+
129+
2. Create a new table or clean instance with the intended partition definition.
130+
131+
3. Load the exported rows.
132+
133+
4. Validate row counts, partition placement, and application-level checksums before replacement of the damaged table or instance.
134+
135+
!!! note
136+
137+
Do not repair the internal MyRocks entries directly.
138+
139+
#### Step 5: Return the server to service
140+
141+
1. Remove `rocksdb_validate_tables=2` or restore the default value of `1`.
142+
143+
2. Set `rocksdb_allow_unsafe_alter=OFF`.
144+
145+
3. Restart the server.
146+
147+
4. Confirm that startup validation succeeds.
148+
149+
5. Confirm that both partition queries return matching names.
150+
151+
6. Confirm that all partitions are readable.
152+
153+
7. Confirm that replication is consistent.
154+
155+
For a `ROCKSDB_CORRUPTED` marker file, see [`rocksdb_allow_to_start_after_corruption`](myrocks-server-variables.md#rocksdb_allow_to_start_after_corruption).
156+
29157
### Instant DDL support
30158

31159
MyRocks provides limited Instant DDL support that is disabled by default, and you can activate the specific instant operations you need by setting the appropriate configuration variables.

0 commit comments

Comments
 (0)