Global Plan Cache

In high-concurrency workloads, each connection maintains its own plan cache for prepared statements. This isolates memory per connection, increasing total memory usage and the risk of Out-of-Memory (OOM) errors—with no way to reuse plans across sessions.

Global Plan Cache (GPC) eliminates this overhead by storing execution plans in shared memory. Connections that issue queries with the same query key share a single cached plan, reducing both memory consumption and plan generation cost.

GPC is supported on PolarDB for PostgreSQL (Compatible with Oracle) clusters running PostgreSQL 11 (revision version 1.1.30 or later) and is enabled by default. To check your cluster's minor version, run SHOW polar_version;.

How GPC works

A query key determines plan sharing. Two queries share a cached plan only when all four components of their query keys match:

Component	Description
Query statement	The SQL text of the prepared statement
Database ID	The database in which the statement runs
Object search path	The schema search path at execution time
User ID	The role executing the statement

When shared memory is full, new plans fall back to local disk. After GPC cleans up infrequently used or invalid entries, those on-disk plans may be promoted back to shared memory.

Limitations

GPC applies only to prepared statements. PL/SQL scenarios are not supported.
Only SELECT, INSERT, UPDATE, and DELETE statements are supported.
Temporary tables are not supported.

Parameters

Parameter	Description	Default	Valid values	Restart required
`polar_gpc_mem`	Memory allocated to GPC, in MB. Set to `0` or a negative value to disable GPC. Must not exceed the shared buffer capacity.	30	Any value within shared buffer capacity	Yes
`polar_enable_gpc_level`	Node types on which GPC is active. `0`: disabled. `1`: read-only nodes only. `2`: read-write and read-only nodes. GPC is active only when `polar_gpc_mem > 0` and this parameter is `1` or `2`. If `polar_gpc_mem > 0` but this parameter is `0`, queries that already used GPC continue to do so, but new queries cannot enter GPC.	0	0, 1, 2	No
`polar_gpc_clean_timeout`	Interval, in seconds, at which infrequently used GPC entries are evicted.	1800	0–86400	No
`polar_worker.gpc_clear_interval`	Interval, in seconds, at which invalid GPC entries are evicted.	60	0–4294967	No
`polar_gpc_clean_max`	Maximum number of GPC entries deleted per cleanup batch.	100	10–10000	No
`polar_gpc_partitions`	Number of hash tables used to store GPC entries.	32	1–1024	Yes
`polar_gpc_entries`	Maximum number of entries per hash table.	1024	1–10000	Yes

Changes to polar_gpc_mem, polar_gpc_partitions, and polar_gpc_entries require a cluster restart to take effect.

Monitor GPC

Overall statistics

Query the polar_stat_gpc view for aggregate GPC metrics:

SELECT * FROM polar_stat_gpc;

Field	Description
`get`	Total cache lookup attempts
`hit`	Successful cache hits
`store`	Plans successfully added to GPC
`store_failed`	Plans that failed to cache due to insufficient memory. A consistently high value indicates that `polar_gpc_mem` may need to be increased.
`store_exists`	Cache attempts skipped because another session had already written the same plan

Use the hit rate (hit / get) to assess GPC effectiveness. If store_failed is growing, increase polar_gpc_mem.

Per-plan details

Query the polar_gpc_plan view for usage and validity of each cached plan:

SELECT * FROM polar_gpc_plan;

Field	Description
`plan_id`	Query plan ID
`stmt_name`	Prepared statement name
`query`	SQL statement
`used_cnt`	Number of times this plan has been used
`last_use_time`	Timestamp of the most recent use
`is_valid`	Whether the plan is still valid

Per-plan memory context

Query the polar_gpc_plan_mcxt view for memory details of each cached plan:

SELECT * FROM polar_gpc_plan_mcxt;

Field	Description
`plan_id`	Query 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

Per-plan query key

Query the polar_gpc_plan_key view to inspect the query key of each cached plan:

SELECT * FROM polar_gpc_plan_key;

Field	Description
`plan_id`	Plan ID
`query`	SQL statement
`dbid`	Database ID
`pid`	Process ID
`num_params`	Number of query parameters
`search_path`	Object search path
`role_id`	User ID

Diagnose uncacheable statements

Query the polar_prepared_statement view to obtain information about all prepared statements of the GPC:

SELECT * FROM polar_prepared_statement;

Field	Description
`is_saved`	Whether the plan has been saved to GPC
`is_valid`	Whether the plan is valid
`cacheable`	Whether the plan is eligible for GPC caching

Filter on cacheable = false to identify prepared statements that cannot enter GPC—for example, those involving temporary tables or unsupported statement types. This is the most direct way to confirm why a specific statement is not being cached.

Manage GPC

GPC is cleaned up automatically based on polar_worker.gpc_clear_interval and polar_gpc_clean_timeout. Use the following functions to trigger cleanup manually.

Delete invalid plans

SELECT polar_gpc_evict_invalid_gpc();

Removes plans marked as invalid—for example, after a DDL change invalidates a cached plan. The system also runs this cleanup automatically at the polar_worker.gpc_clear_interval interval.

Delete infrequently used plans

SELECT polar_gpc_evict_live_gpc();

Removes plans that have not been used within the polar_gpc_clean_timeout window. The system also runs this cleanup automatically at the polar_worker.gpc_clear_interval interval.