Global metadata cache (Global Cache) - PolarDB - Alibaba Cloud Documentation Center

This topic provides background information about the global metadata cache (Global Cache) and explains how to use it.

Applicability

This feature is supported on PolarDB for PostgreSQL that runs PostgreSQL 14 with minor engine version 2.0.14.8.11.0 or later.

Note

You can view the minor engine version number in the console or by running the SHOW polardb_version; statement. If the minor engine version does not meet the requirement, you can upgrade the minor engine version.

Background information

To improve the efficiency of metadata access, PostgreSQL uses multiple metadata caches in each process:

RelCache (Relation Descriptor Cache): Caches relation descriptors.
CatCache/SysCache (System Catalog Cache): Caches system tables.

RelCache and CatCache are private to each process. As a result, when a database has many connections or objects, such as tables, views, and indexes, the database instance consumes a large amount of memory.

The global metadata cache (Global Cache) is a collective term for metadata caches that reside in the shared memory of and PolarDB for PostgreSQL. Global Cache allows all processes to share the same cache entries, which improves memory utilization and reduces the risk of out-of-memory (OOM) errors. Global Cache currently includes:

Global RelCache: A global relation descriptor cache that corresponds to RelCache.
Global CatCache: A global system table cache that corresponds to CatCache/SysCache.

RelCache

RelCache reorganizes and caches all metadata related to a table, including views, indexes, and TOAST tables, in memory for more efficient access. During all stages of SQL processing, such as when retrieving a table's column information, index information, or partitioned table information, RelCache is accessed directly. If a RelCache miss occurs, the system scans the system tables and loads the data into memory.

The RelCache in native PostgreSQL does not have an eviction mechanism. Normally, after the first access, RelCache retains the data in the cache until the process exits. Alternatively, if a Data Definition Language (DDL) operation modifies the table's metadata, it broadcasts a cache invalidation message. After receiving the invalidation message, RelCache removes the invalidated object from memory.

CatCache

CatCache caches tuples from system tables. Built on top of CatCache is another layer, SysCache, which provides a key-value (KV) interface. Essentially, CatCache and SysCache work together to reorganize data from system tables into a KV format in memory to simplify queries. For example, during SQL processing, such as retrieving a name by its object identifier (OID) or finding the number of parameters for a function by its OID, CatCache is accessed directly. If a CatCache miss occurs, the data is loaded from the system tables. The loading and invalidation processes for CatCache are almost identical to those for RelCache.

Parameter descriptions

Parameter	Level	Description
polar_enable_global_catcache	PGC_USERSET	Enables or disables Global CatCache. Valid values: on (default): Enables the Global CatCache feature. off: Disables the Global CatCache feature.
polar_enable_global_relcache	PGC_USERSET	Enables or disables Global RelCache. Valid values: on (default): Enables the Global RelCache feature. off: Disables the Global RelCache feature.
polar_sgc_max_size	PGC_POSTMASTER	Sets the total size of the Global Cache. Value range: 0 to INT_MAX. The default value is 72 MB. A restart is required for the modification to take effect.
polar_global_catcache_size	PGC_SIGHUP	Sets the size of the Global CatCache. Value range: 0 to the value of polar_sgc_max_size. The default value is 32 MB.
polar_global_relcache_size	PGC_SIGHUP	Sets the size of the Global RelCache. Value range: 0 to the value of polar_sgc_max_size. The default value is 32 MB.

Note

The capacity of each Global Cache can be scaled up or down online, as long as it does not exceed the value of polar_sgc_max_size. This provides flexibility for different business scenarios. When you use this feature, note the following:

Ensure that the Global Cache has sufficient capacity. The cache is accessed frequently during all stages of SQL processing. If the capacity is insufficient, eviction is triggered. When the evicted data is accessed again, it must be loaded from files, which can cause extra I/O and performance degradation.
If a cache is already full, you can still scale it down online by adjusting the parameters. The corresponding Global Cache will evict some data. This can affect performance, so perform this operation with caution.
The memory specified by polar_sgc_max_size is allocated to Global RelCache and Global CatCache. A portion of this memory must also be reserved for management purposes, such as internal hash tables, to ensure the Global Cache operates correctly. Therefore, the value of polar_sgc_max_size should be greater than the sum of polar_global_relcache_size and polar_global_catcache_size.

Monitoring interfaces

All monitoring interfaces for the Global Cache are available in the polar_global_cache extension. Run the following command to create the extension.

CREATE EXTENSION polar_global_cache;

Cache statistics information

Global Cache global statistics information

You can view the status information of the Global Cache in the polar_global_cache_stat view. Currently, this view includes statistics for only Global RelCache and Global CatCache.

=> SELECT * FROM polar_global_cache_stat;
-[ RECORD 1 ]----+----------------
cache_name       | Global CatCache
elems            | 2805
nlookup          | 74233
nlookup_miss     | 43576
ninsert          | 9478
nmove            | 0
ndelete          | 0
ninvalidate      | 35843
nflush           | 1
nevict           | 0
nevict_active    | 0
nevict_fail      | 0
lru_active_len   | 402
lru_inactive_len | 2403
data_allocator   | 2
meta_allocator   | 1
component_id     | 1
-[ RECORD 2 ]----+----------------
cache_name       | Global RelCache
elems            | 95
nlookup          | 1203
nlookup_miss     | 1005
ninsert          | 265
nmove            | 0
ndelete          | 0
ninvalidate      | 4404
nflush           | 1
nevict           | 0
nevict_active    | 0
nevict_fail      | 0
lru_active_len   | 3
lru_inactive_len | 92
data_allocator   | 3
meta_allocator   | 1
component_id     | 2

Metric descriptions:

Metric	Description
nlookup	The number of cache lookups.
nlookup_miss	The number of lookup misses. You can use this metric with `nlookup` to evaluate the hit rate of the Global Cache. The hit rate might be low when the system first starts, but it will gradually increase as the cache is prefetched. Set an appropriate capacity to ensure a high hit rate for the Global Cache and avoid performance degradation.
ninsert	The number of new cache insertions.
nmove, ndelete	The number of times cache objects were moved and deleted during scaling.
ninvalidate	The number of cache invalidations.
nflush	The number of times the entire cache was flushed due to a special cache invalidation message or a command such as `drop database;`.
nevict	The total number of objects evicted from the Global Cache. Note Objects in the Global Cache are evicted based on a Least Recently Used (LRU) policy. They are divided into an active list and an inactive list, with objects in the inactive list being evicted first. During eviction, an object that should be evicted according to the LRU policy might not be, because it is currently in use or due to concurrency conflicts. You can ignore these cases. A non-zero value for nevict-related metrics indicates that the current capacity is insufficient. To avoid performance issues, increase the capacity by adjusting the `polar_global_catcache_size` or `polar_global_relcache_size` parameter.
nevict_active	The number of objects evicted from the active list of the Global Cache.
nevict_fail	The number of failed evictions from the Global Cache.
lru_active_len	The length of the active list in the internal LRU list.
lru_inactive_len	The length of the inactive list in the internal LRU list.

Local Cache global statistics information

The metrics in the polar_cache_stat view are a subset of those in the polar_global_cache_stat view. For more information about the metrics, see the metric descriptions for the polar_global_cache_stat view.

Note

Although polar_cache_stat displays information about private caches for each process, the query results from this view aggregate data from all processes.

=> SELECT * FROM polar_cache_stat;
-[ RECORD 1 ]-+--------------
cache_name    | Proc CatCache
nlookup       | 779844
nlookup_miss  | 82390
ninsert       | 150876
ndelete       | 139690
ninvalidate   | 74231
nevict        | 126474
nevict_active | 1808
evict_fail    | 0
-[ RECORD 2 ]-+--------------
cache_name    | Proc RelCache
nlookup       | 295183
nlookup_miss  | 4632
ninsert       | 25968
ndelete       | 3277
ninvalidate   | 8856
nevict        | 0
nevict_active | 0
evict_fail    | 0

CatCache statistics information

Global CatCache statistics information

You can view the status information of the Global CatCache in the polar_global_catcache_stat view.

Note

Compared to polar_global_cache_stat, this view includes additional xxx_clist fields. You can typically ignore these metrics. There are two types of objects in CatCache: CatTuple and CatList. The xxx_clist metrics record various data about CatList objects.

=> SELECT * FROM polar_global_catcache_stat;
-[ RECORD 1 ]-------+----
elems               | 34
nlookup             | 853
nlookup_miss        | 852
ninsert             | 34
nmove               | 0
ndelete             | 0
ninvalidate         | 0
nflush              | 0
nevict              | 0
nevict_active       | 0
nevict_fail         | 0
nlookup_clist       | 41
nlookup_miss_clist  | 41
ninsert_clist       | 0
nmove_clist         | 0
ndelete_clist       | 0
ninvalidate_clist   | 0
nevict_clist        | 0
neivct_active_clist | 0
rehash_fail         | 0
meta_alloc_fail     | 0
data_alloc_fail     | 0
lru_active_len      | 0
lru_inactive_len    | 34
component_id        | 1

Local CatCache statistics information

You can view the status information of the private CatCache for a process in the polar_catcache_stat view. The statistical metrics are a subset of those in polar_global_catcache_stat, and their meanings are the same.

=> SELECT * FROM polar_catcache_stat;
-[ RECORD 1 ]------+-----
nlookup            | 2060
nlookup_miss       | 898
ninsert            | 883
ndelete            | 753
ninvalidate        | 0
nevict             | 753
nevict_active      | 2
evict_fail         | 0
nlookup_clist      | 41
nlookup_miss_clist | 41
ninsert_clist      | 41
ndelete_clist      | 41

RelCache statistics information

Global RelCache statistics information

You can view the status of the Global RelCache in the polar_global_relcache_stat view.

=> SELECT * FROM polar_global_relcache_stat;
-[ RECORD 1 ]----+-----
elems            | 61
nlookup          | 930
nlookup_miss     | 836
ninsert          | 221
nmove            | 0
ndelete          | 0
ninvalidate      | 4344
nflush           | 1
nevict           | 0
nevict_active    | 0
nevict_fail      | 0
meta_alloc_fail  | 0
data_alloc_fail  | 0
lru_active_len   | 3
lru_inactive_len | 58
component_id     | 2

Local RelCache statistics information

You can view the status of the RelCache within the current session in the polar_relcache_stat view.

=> SELECT * FROM polar_relcache_stat;
-[ RECORD 1 ]-+-------
nlookup       | 293458
nlookup_miss  | 4535
ninsert       | 20239
ndelete       | 3277
ninvalidate   | 8856
nevict        | 0
nevict_active | 0
evict_fail    | 0