All Products
Search

This Product

    PolarDB:Global caches

    Document Center

    PolarDB:Global caches

    Last Updated:May 17, 2024

    This topic describes the background information about the global cache feature and how to use this feature.

    Usage notes

    The global cache feature is supported for PolarDB for PostgreSQL clusters that run the following engine:

    Note

    You can execute the following statement to query the revision version of your PolarDB for PostgreSQL cluster:

    select version();

    Background information

    To improve the efficiency of metadata queries, PostgreSQL introduces the following metadata caches in each process:

    • RelCache: caches relation descriptors.

    • CatCache and SysCache: cache system catalogs.

    Each process has its own RelCache and CatCache. If a large number of connections are established or a database contains a large number of objects such as tables, views, and indexes, memory consumption of the caches is high.

    The global cache feature is supported for PolarDB for PostgreSQL. Global caches are metadata caches stored in the shared memory that all processes can access. This helps maximize memory usage by allowing all processes to share cache entries and reduces the chances of out-of-memory (OOM) issues. The following global caches are supported:

    • Global RelCache: caches relation descriptors for global access.

    • Global CatCache: caches system catalogs for global access.

    RelCache

    A RelCache reorganizes and caches all metadata of a table, such as views, indexes, and The Oversized-Attribute Storage Technique (TOAST) tables, in the memory for more efficient access. The RelCache is accessed in any steps of processing an SQL statement whenever table metadata is required. For example, the system needs to query table metadata to obtain the information about the columns, indexes, or partitions of a table. If the requested data is not found in the RelCache, the system scans system tables for the data and caches the data in the RelCache.

    A RelCache of native PostgreSQL does not have an eviction mechanism. In most cases, when a RelCache is accessed for the first time, it keeps caching data until the related process exits. A RelCache evicts invalid objects from the memory only after it receives a cache invalidation message that is broadcast by a DDL operation.

    CatCache

    A CatCache caches tuples in system tables. On top of a CatCache, a SysCache is used to provide key-value (KV) interfaces. In essence, a CatCache and a SysCache reorganize the data in system tables into KV pairs and cache them in the memory for more efficient access. For example, if the system needs to query an object name or the number of parameters in a function by object identifier (OID) when the system is processing an SQL statement, the system checks a CatCache for the data. If the requested data is not found in the CatCache, the system scans system tables for the data and caches the data in the CatCache. The rules for caching and evicting data in a CatCache are basically the same as those for a RelCache.

    Parameters

    Parameter

    Level

    Description

    polar_enable_global_catcache

    PGC_USERSET

    Specifies whether to enable the global CatCache. Valid values:

    • on (default)

    • off

    polar_enable_global_relcache

    PGC_USERSET

    Specifies whether to enable the global RelCache. Valid values:

    • on (default)

    • off

    polar_sgc_max_size

    PGC_POSTMASTER

    The total size of global caches. Valid values: 0 to INT_MAX. Default value: 72. Unit: MB. After you change the parameter value, you must restart your cluster for the change to take effect.

    polar_global_catcache_size

    PGC_SIGHUP

    The size of the global CatCache. Valid values: 0 to the value of the polar_sgc_max_size parameter. Default value: 32. Unit: MB.

    polar_global_relcache_size

    PGC_SIGHUP

    The size of the global RelCache. Valid values: 0 to the value of the polar_sgc_max_size parameter. Default value: 32. Unit: MB.

    Note

    You can increase or decrease the capacity of each global cache online as long as the total size of global caches does not exceed the value of the polar_sgc_max_size parameter. This provides flexibility for various business scenarios. When you specify cache sizes, take note of the following items:

    • Make sure that the capacities of global caches are sufficient. During the processing of SQL statements, global caches are frequently accessed. If the capacity of a global cache is used up, evictions are triggered. Then, if the evicted data is requested, the data must be cached from files again. This may lead to additional I/O and affect performance.

    • If the capacity of a global cache is used up, you can still decrease the capacity online by modifying the preceding parameters. Accordingly, the global cache evicts some data, which affects performance. Exercise caution when you perform this operation.

    • A part of the memory that is allocated to global caches as specified by the polar_sgc_max_size parameter is reserved for memory management to maintain the normal operation of global caches. For example, the hash tables are stored in the reserved memory. Therefore, the value of the polar_sgc_max_size parameter is normally greater than the sum of the values of the polar_global_relcache_size and polar_global_catcache_size parameters.

    Monitoring

    The polar_global_cache extension allows you to monitor global caches. Execute the following statement to create the extension: 

    CREATE EXTENSION polar_global_cache;

    Statistics on caches

    Statistics on global caches

    You can view the information about global caches in the polar_global_cache_stat view. The information about the global RelCache and the global CatCache is displayed. 

    => 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

    Metrics

    Metric

    Description

    nlookup

    The number of queries.

    nlookup_miss

    The number of query misses. This metric can be used in combination with the nlookup metric to evaluate the hit rate of a global cache. The hit rate may be low in the early stage of system startup and gradually increases with cache prefetching. You must specify an appropriate capacity for a global cache to ensure the hit rate of the global cache and system performance.

    ninsert

    The number of insert operations.

    nmove and ndelete

    The number of move and delete operations during scaling.

    ninvalidate

    The number of invalidate operations.

    nflush

    The number of operations to flush the cache due to reasons such as the special-purpose cache invalidation message and the DROP DATABASE; statement.

    nevict

    The number of evictions.

    Note

    The objects in a global cache are put in the active and inactive lists, and are evicted based on the Least Recently Used (LRU) policy. The objects in the inactive list are preferentially evicted. The objects may not be evicted as specified in the LRU policy because the objects are being used or due to concurrency conflicts. You can ignore such cases.

    If the values of nevict-related metrics are not 0, the current capacity is insufficient. To prevent performance degradation, you can increase the capacity by modifying the polar_global_catcache_size or polar_global_relcache_size parameter.

    nevict_active

    The number of evictions in the active list.

    nevict_fail

    The number of failed evictions.

    lru_active_len

    The length of the active list in the internal LRU lists.

    lru_inactive_len

    The length of the inactive list in the internal LRU lists.

    Statistics on local caches

    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 preceding Metrics table for the polar_global_cache_stat view.

    Note

    The polar_cache_stat view aggregates the data of local caches for 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

    Statistics on CatCaches

    Statistics on the global CatCache

    You can view the information about the global CatCache in the polar_global_catcache_stat view.

    Note

    Compared with the polar_global_cache_stat view, xxx_clist metrics are added in this view, which you can ignore in most cases. Two types of objects are stored in a CatCache: CatTuple and CatList. xxx_clist metrics record various data about objects of the CatList type. 

    => 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

    Statistics on local CatCaches

    You can view the information about process-specific CatCaches in the polar_catcache_stat view. The metrics in this view are a subset of those in the polar_global_catcache_stat view. 

    => 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

    Statistics on RelCaches

    Statistics on the global RelCache

    You can view the information about 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

    Statistics on local RelCaches

    You can view the information about process-specific RelCaches 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