The Relation Size Cache (RSC) eliminates redundant file system calls when PolarDB for PostgreSQL queries block counts for tables and indexes. On PolarFileSystem (PolarFS), where lseek latency is significantly higher than on a local file system, RSC cuts block-count lookup latency from ~55 µs to ~0.07 µs—a ~780x improvement—with no application-level changes required.
RSC is enabled by default on all node types.
Supported versions
RSC is supported on the following PolarDB for PostgreSQL versions:
| PostgreSQL version | Minimum minor engine version |
|---|---|
| PostgreSQL 18 | 2.0.18.0.1.0 |
| PostgreSQL 17 | 2.0.17.2.1.0 |
| PostgreSQL 16 | 2.0.16.3.1.1 |
| PostgreSQL 15 | 2.0.15.7.1.1 |
| PostgreSQL 14 | 2.0.14.12.23.1 |
To check your minor engine version, view the minor engine version number in the console or run SHOW polardb_version;. If the version requirement is not met, upgrade the minor engine version.Configure RSC
Use the following Grand Unified Configuration (GUC) parameters to control RSC per node type. All parameters default to on.
| Node type | GUC parameter | Default | Description |
|---|---|---|---|
| Primary | polar_enable_rel_size_cache | on | Enables RSC on the primary node. Set to off to disable. |
| Replica | polar_enable_replica_rel_size_cache | on | Enables RSC on replica nodes. Set to off to disable. |
| Standby | polar_enable_standby_rel_size_cache | on | Enables RSC on standby nodes. Set to off to disable. |
How RSC works
Every SQL execution triggers multiple block-count lookups for the tables and indexes it touches. PolarDB for PostgreSQL handles these through the smgrnblocks interface in the storage management (smgr) layer, which calls the lseek system call to measure file length and then divides by block size. Because smgrnblocks sits on the critical path of SQL processing, and because lseek latency on PolarFS is much higher than on a local file system, frequent calls add up and slow query execution.
RSC addresses this by caching block counts in shared memory, so smgrnblocks reads from memory instead of hitting the file system.
Cache structure
RSC stores block counts in a one-dimensional array in shared memory. A hash table maps each relation's unique storage-layer identifier (RelFileNode) to its entry in the array. Each entry holds the block count for one relation—either a table or an index.
All processes look up block counts through two index levels:
Level 1 index: Caches a pointer and generation number (version) for the last accessed cache entry. If the same relation is accessed again and the generation hasn't changed, the block count is read directly from the pointer. This makes the level 1 index highly effective in read-heavy workloads against a specific table. When a mapping in the RSC hash table changes, the corresponding entry's generation increments, which invalidates the level 1 index.
Level 2 index: When the level 1 index misses, RSC queries the hash table in shared memory to find the cache entry, retrieves the block count, and refreshes the level 1 index.
If neither index level finds the entry, cache eviction runs. A Segmented Least Recently Used (SLRU) algorithm evicts a less-recently-used entry, then lseek is called to fetch the actual block count. The result repopulates the evicted entry, and both index levels are updated.
Updates on primary and standby nodes
When RSC is enabled, any smgr interface that changes a table's file size also updates the corresponding cache entry in shared memory:
File extend: Updates the block count for the extended file.
File truncate: Updates the block count for the truncated file.
Standby nodes use physical replication and apply Write-Ahead Log (WAL) records through the same smgr interfaces as the primary node, so their RSC entries update through the same path.
Updates on replica nodes
Replica nodes share physical storage with the primary node and synchronize through the LogIndex mechanism. Because replica nodes don't write to storage, they can't update RSC entries through smgr interfaces.
Instead, replica nodes parse the data block numbers referenced in WAL records and compare them against the current cached block count:
If a WAL record references a block number greater than the cached count, RSC updates the cached value to the new block count.
If a WAL record indicates a file truncation, RSC discards the cached block count. The cache repopulates on the next file system call.
Benchmark RSC performance
Use polar_smgrperf_nblocks to measure block-count lookup latency for a table of a given size.
RSC disabled (~55 µs latency):
SHOW polar_enable_rel_size_cache;
polar_enable_rel_size_cache
-----------------------------
off
(1 row)
SELECT polar_smgrperf_nblocks(32, true, false);
NOTICE: testing logical file length with 32 GB
INFO: iops=18341.1/s, lat=54.52us
INFO: iops=17504.0/s, lat=57.13us
INFO: iops=17960.8/s, lat=55.68us
INFO: iops=17973.0/s, lat=55.64us
INFO: iops=17603.5/s, lat=56.81us
INFO: iops=17403.8/s, lat=57.46us
INFO: iops=17506.2/s, lat=57.12us
INFO: iops=18061.7/s, lat=55.37usRSC enabled (~0.07 µs latency):
SHOW polar_enable_rel_size_cache;
polar_enable_rel_size_cache
-----------------------------
on
(1 row)
SELECT polar_smgrperf_nblocks(32, true, false);
NOTICE: testing logical file length with 32 GB
INFO: iops=14155515.6/s, lat=0.07us
INFO: iops=13897273.6/s, lat=0.07us
INFO: iops=13869926.3/s, lat=0.07us
INFO: iops=13779602.7/s, lat=0.07us
INFO: iops=14159120.5/s, lat=0.07us
INFO: iops=14147065.6/s, lat=0.07us
INFO: iops=14124141.9/s, lat=0.07us
INFO: iops=14162773.3/s, lat=0.07usWith RSC enabled, block-count lookup IOPS increases from ~18,000/s to ~14,000,000/s, and latency drops from ~55 µs to ~0.07 µs.