The Warm Buffer Pool feature for fast restarts and performance - PolarDB

When a PolarDB for MySQL primary node restarts, its InnoDB buffer pool starts empty. The database reloads pages from storage on demand, so performance is degraded until the pool repopulates—a process that can take minutes under heavy write workloads or large transaction volumes. Warm Buffer Pool eliminates this cold-start period by storing the buffer pool in Linux shared memory, independent of the database process. The buffer pool persists across restarts and is immediately available when the node comes back up.

Prerequisites

Before you enable Warm Buffer Pool, make sure that:

The PolarDB cluster runs MySQL 8.0.2 with revision version 8.0.2.1.0 or later. To check the version, see the "Query the engine version" section of Engine versions.
The table compression feature is not enabled.

How it works

Warm Buffer Pool stores the InnoDB buffer pool in Linux shared memory rather than process memory. Because the buffer pool is independent of the PolarDB process, it survives a restart.

Key behaviors:

Persistence across restarts: Buffer pool control data, page metadata, and page data are stored in shared memory. When PolarDB starts, it attaches to the existing shared-memory buffer pool instead of allocating a new one.
Crash recovery: After a node crash, PolarDB detects and repairs any inconsistencies in the shared-memory buffer pool before attaching to it.
Faster clean shutdown: On a manual restart, PolarDB saves the main transaction state before shutting down. This skips both the rollback at shutdown and the restoration at startup, cutting restart time significantly.
O&M operations: The mysqlshm tool lets you query configuration and release shared-memory buffer pools from the command line.

Benefits

Faster restarts

Warm Buffer Pool reduces primary node restart time from minutes to seconds. The improvement is most pronounced when the primary node has a large buffer pool and handles heavy write workloads or large transactions.

Consistent post-restart performance

Because the buffer pool stays in shared memory, recently accessed pages are still available after the restart. There is no warm-up period and no performance drop.

The following figure shows throughput during a restart with a 50 GB buffer pool, using Sysbench OLTP read-only workloads.

Without Warm Buffer Pool (orange line): throughput drops to 2% of normal immediately after restart and takes about 200 seconds to recover.
With Warm Buffer Pool (blue line): throughput is unaffected during the restart.

Enable Warm Buffer Pool

For a manual restart

Set innodb_buf_shm_key to a non-zero value in my.cnf, then start the PolarDB cluster.
Verify that the feature is active:
```
SHOW GLOBAL STATUS LIKE 'innodb_shared_buffer_pool_status';
```
The value should be Allocate from shared memory.
Set innodb_fast_shutdown to 3:
```
SET GLOBAL innodb_fast_shutdown = 3;
```
Restart the primary node.
After the restart, check the status again:
```
SHOW GLOBAL STATUS LIKE 'innodb_shared_buffer_pool_status';
```
The value should be Attach to clean shutdown shared memory, which means the node attached to a buffer pool that was cleanly shut down.

For an exception-triggered restart

Set innodb_buf_shm_key to a non-zero value in my.cnf, then start the PolarDB cluster.
Verify that the feature is active:
```
SHOW GLOBAL STATUS LIKE 'innodb_shared_buffer_pool_status';
```
The value should be Allocate from shared memory.
Terminate the mysqld process to simulate a node crash.
Wait for the node to restart.
After the restart, check the status again:
```
SHOW GLOBAL STATUS LIKE 'innodb_shared_buffer_pool_status';
```
The value should be Attach to abnormal shutdown shared memory, which means PolarDB detected and recovered the shared-memory buffer pool from a crash state.

Reference

Parameters

Parameter	Type	Level	Description
`innodb_buf_shm_key`	Integer	Global	Unique identifier for the shared-memory buffer pool. Set to a non-zero value to enable Warm Buffer Pool. Valid values: 0 to 2^64-1. Default: `0` (disabled).
`innodb_buf_shm_base_addr`	Integer	Global	Base offset of the virtual memory address for the shared buffer pool. Valid values: `0x300000000000` to 2^64-1. Default: `0x567800000000`.
`innodb_buf_page_desc_free_list_size`	Integer	Global	Number of pages reserved for compressed page descriptors. Valid values: 8–128. Default: `16`.
`innodb_buf_free_zip_pages`	Integer	Global	How to handle compressed pages on restart. Valid values: `1` (release the compressed pages when the node restarts due to exceptions), `2` (force release the compressed pages during the restart). Default: `1`.
`innodb_buffer_pool_parallel_scan_threads`	Integer	Global	Number of threads for parallel buffer pool scan. Valid values: 0–512. Default: `4`.
`innodb_buf_shm_huge_page`	Bool	Global	Whether to use large pages when allocating shared memory. Valid values: `ON`, `OFF`. Default: `ON`.
`innodb_fast_shutdown`	Integer	Global	InnoDB shutdown mode. Valid values: `0`, `1`, `2`, `3`. The value `3` is PolarDB-specific: same behavior as `2` but without rolling back uncommitted transactions. Default: `1`.

Status values

Query the current state of Warm Buffer Pool:

SHOW GLOBAL STATUS LIKE 'innodb_shared_buffer_pool_status';

Value	Meaning
`Using process private memory`	Warm Buffer Pool is disabled. The node uses standard process-private memory.
`Allocate from shared memory`	Warm Buffer Pool is active. The buffer pool is allocated in shared memory.
`Attach to clean shutdown shared memory`	The node attached to a buffer pool that was cleanly shut down. Full restart acceleration applies.
`Attach to abnormal shutdown shared memory`	The node attached to a buffer pool that survived a crash. PolarDB has repaired any inconsistencies.

mysqlshm

mysqlshm is a command-line tool for managing the shared-memory buffer pool. Use it to inspect or release a buffer pool without restarting the database.

Usage: mysqlshm -k key [options]
   -h, Display this help and exit.
   -k, The shared memory key  [REQUIRED]
   -i, Prinf the basic info of shared memory
   -f, Free the shared memory