All Products
Search

This Product

    PolarDB:Global plan cache (GPC)

    Document Center

    PolarDB:Global plan cache (GPC)

    Last Updated:Mar 30, 2026

    Global plan cache (GPC) lets connections in PolarDB for PostgreSQL share execution plans, reducing per-connection memory overhead and the cost of repeated plan generation.

    How GPC works

    In standard PostgreSQL, each connection maintains its own plan cache. At scale—with hundreds or thousands of concurrent connections executing the same queries—every connection independently compiles and stores an identical plan. This multiplies memory consumption proportionally with connection count and increases the risk of out-of-memory (OOM) errors.

    GPC moves plan storage into shared memory. Once one connection compiles a plan, all connections that match the same query key reuse it directly without recompiling. The result is lower aggregate memory usage and faster query execution for prepared statements.

    Plans are shared when their query keys match. A query key consists of:

    • The query text

    • The database ID

    • The search path

    • The user ID

    Supported versions

    GPC is available on the following versions of PolarDB for PostgreSQL:

    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.9.15.0
    PostgreSQL 11 2.0.11.9.28.0

    To check your minor engine version, run SHOW polardb_version; or view it in the console. If your cluster does not meet the requirement, upgrade the minor engine version.

    GPC is enabled by default on clusters that meet the version requirements.

    Limitations

    • GPC supports only prepared statements. Plan caching in PL/SQL scenarios is not supported.

    • Only SELECT, INSERT, UPDATE, and DELETE statements are supported.

    • Temporary tables are not supported.

    Parameters

    Parameter Description Default Dynamic
    polar_gpc_mem Shared memory allocated to GPC, in MB. Must not exceed shared_buffer. Set to 0 or a negative value to disable GPC. Requires a cluster restart to take effect. 30 MB No
    polar_enable_gpc_level Scope at which GPC is active. 0: disabled. 1: read-only (RO) nodes only. 2: both the primary (RW) and read-only nodes. 0 Yes
    polar_gpc_clean_timeout How often infrequently used GPC entries are evicted, in seconds. Range: 0 seconds to 24 hours. 1800 s Yes
    polar_worker.gpc_clear_interval How often invalid GPC entries are cleared, in seconds. Maximum: (2^32 − 1) / 1000 seconds. 60 s Yes
    polar_gpc_clean_max Number of GPC entries cleared per eviction run. Range: 10–10000. 100 Yes
    polar_gpc_partitions Number of hash tables used to store GPC entries. Range: 1–1024. Requires a cluster restart to take effect. 32 No
    polar_gpc_entries Maximum entries per hash table. Range: 1–10000. Requires a cluster restart to take effect. 1024 No

    How `polar_gpc_mem` and `polar_enable_gpc_level` interact:

    • GPC is active only when both polar_gpc_mem > 0 and polar_enable_gpc_level > 0.

    • If polar_gpc_mem > 0 but polar_enable_gpc_level = 0, existing queries continue using cached plans, but new queries are not cached.

    • If shared memory is full, new plans are stored locally per session. When infrequently used or invalid GPC entries are cleared and memory is released, the system moves those local plans into the GPC.

    Monitor and manage GPC

    GPC monitoring views and management functions are provided by the polar_gpc extension. Install it once per database:

    CREATE EXTENSION IF NOT EXISTS polar_gpc;

    Views

    polar_stat_gpc — Overall GPC usage statistics

    SELECT * FROM polar_stat_gpc;
    Column Description
    get Number of attempts to retrieve a matching GPC entry
    hit Number of times a matching GPC entry was found
    store Number of plans successfully saved to the GPC
    store_failed Number of times a plan failed to store due to a temporary OOM error in the GPC. A consistently rising value indicates polar_gpc_mem is set too low.
    store_exists Number of times the system attempted to add a local plan to the GPC, but another session had already stored it

    polar_gpc_plan — Per-entry memory usage

    SELECT * FROM polar_gpc_plan;
    Column Description
    plan_id Execution plan ID
    stmt_name Name of the prepared statement
    query Query text
    used_cnt Number of times the plan has been used
    last_use_time Timestamp of the most recent use
    is_valid Whether the plan is currently valid

    polar_gpc_plan_mcxt — MemoryContext details per entry

    SELECT * FROM polar_gpc_plan_mcxt;
    Column Description
    plan_id Execution plan ID
    mcxt_name MemoryContext name
    totalspace Total allocated memory
    freespace Available memory within the context
    used Memory in use
    nblocks Number of memory blocks

    polar_gpc_plan_key — Query keys for each GPC entry

    SELECT * FROM polar_gpc_plan_key;
    Column Description
    plan_id Plan ID
    query Query text
    dbid Database ID
    pid Process ID
    num_params Number of parameters in the query
    search_path Search path at the time the plan was stored
    role_id User ID

    polar_prepared_statement — All prepared statements in the GPC

    SELECT * FROM polar_prepared_statement;
    Column Description
    is_saved Whether the execution plan is saved to the GPC
    is_valid Whether the plan is currently valid
    cacheable Whether the plan is eligible for caching

    Functions

    Clear invalid GPC entries

    SELECT polar_gpc_evict_invalid_gpc();

    Immediately removes invalid GPC entries. If not called manually, the system clears them automatically at the interval set by polar_worker.gpc_clear_interval.

    Evict infrequently used GPC entries

    SELECT polar_gpc_evict_live_gpc();

    Immediately evicts GPC entries that have not been used recently. If not called manually, the system evicts them automatically at the interval set by polar_worker.gpc_clear_interval.

    What's next