Product Documentation

Appearance

All platforms

Frontend Memory Manager Overview ​

The Frontend Memory Manager prevents system-level out-of-memory (OOM) conditions by enforcing global memory limits across all client (frontend) processes during query parsing, analysis, and planning. It has no effect on query executors or background process backends.

It ensures system stability and preserves low latency for active workloads, even when many concurrent users are connected.

Overview ​

In large environments, multiple queries running in parallel can collectively consume more memory than the system can safely provide. When this happens, the operating system may kill the PostgreSQL process, causing a full database restart.

The Frontend Memory Manager prevents this by monitoring memory usage across all backends and controlling how new queries start and how existing queries continue to consume memory.

How It Works ​

When enabled, the Frontend Memory Manager automatically:

  • Throttles new queries if total planner memory exceeds a configurable threshold.
  • Cancels large queries when global memory use reaches a critical level.
  • Resumes throttled queries automatically once memory pressure subsides.

This mechanism applies only to query planning (parsing, rewriting, and analysis). It does not limit backend memory usage during execution phases such as joins or sorts.

Configuration Parameters ​

Use the following configuration parameters to control the Frontend Memory Manager. All parameters are cluster-wide and can be changed with ALTER SYSTEM.

ParameterDescriptionDefault / Example
enable_memory_managerEnables the background memory manager process. When off, the memory manager is disabled and takes no action.off
memory_manager_high_watermark_mbThreshold (in MB) at which the system begins canceling queries.120 GB
memory_manager_low_watermark_mbThreshold (in MB) at which cancellation stops.80 GB
memory_manager_throttle_threshold_mbThreshold (in MB) at which new queries are paused (throttled).90 GB
memory_manager_runaway_limit_mbPer-backend memory limit (in MB) that participates in global tracking.50 MB
context_memory_threshold_mbHard cap for memory used by a single planning backend.40 GB
memory_manager_refresh_interval_msFrequency, in milliseconds, at which global usage is refreshed.1000 ms

When deployed in Yellowbrick Cloud, some memory management thresholds are automatically sized during system setup based on total available memory.

During installation, we apply proportional limits to ensure safe defaults:

ParameterFormula
memory_manager_high_watermark_mb95% of total available memory
memory_manager_low_watermark_mb80% of total available memory
memory_manager_throttle_threshold_mb85% of total available memory
context_memory_threshold_mbMinimum of 50% of total available memory and 40 GB

Enabling or Disabling the Memory Manager ​

The Memory Manager runs automatically when thresholds are configured. To temporarily disable it:

sql
ALTER SYSTEM SET enable_memory_manager = off;
SELECT pg_reload_conf();

When disabled, no throttling or cancellation will occur, even if configured thresholds are exceeded. Existing memory manager parameters remain defined but inactive until re-enabled.

When Queries Are Throttled ​

A query may be temporarily delayed at start-up if the system is under global memory pressure.

  • When total planner memory exceeds the throttle limit, new queries wait until usage drops below that limit.
  • Once sufficient memory becomes available, waiting queries resume automatically.

When queries are throttled, they appear in pg_stat_activity with state = 'memory throttle'. This allows administrators to identify waiting sessions in real time.

This behavior is cluster-wide and does not require manual intervention.

Note: Superuser, system users and background process sessions are never throttled.

When Queries Are Canceled ​

If total planner memory usage exceeds the high watermark, the system cancels the largest queries until usage falls below the low watermark.

  • Queries are canceled gracefully and return a standard PostgreSQL error.

Some types of queries are never canceled:

  • Superuser and system users queries.
  • Autovacuum, background processes and maintenance operations.
  • LOAD and UNLOAD operations

Best Practices ​

  • Keep the high and low watermarks at least 30% apart to prevent oscillation.
  • Leave enable_memory_manager set to on in production environments to prevent OOM risks.
  • Review queries that are frequently canceled or throttled to identify excessive planner memory usage.

Monitoring and Logs ​

When the memory manager intervenes, PostgreSQL logs report key events such as query cancellation or throttling.

  • Canceling of session 1234 query:
text
LOG:  YBDMemMgr: canceling backend 1234 (5075 MB)
  • Throttling of new queries:
text
LOG:  YBDMemMgr: throttling new queries (3075 MB used)
LOG:  YBDMemMgr: unthrottled new queries (3071 MB used)

Any session being throttled trying to run a new query should also see a WARNING:

text
WARNING:  System under memory pressure — pausing new queries
WARNING:  Memory pressure cleared - continuing after 1350 ms under throttle

Monitoring tools can use these messages to detect and report memory pressure events.

See Also ​