max_stack_depth

Definition PG 18 manual

Specifies the maximum safe depth of the server's execution stack. The ideal setting for this parameter is the actual stack size limit enforced by the kernel (as set by ulimit -s or local equivalent), less a safety margin of a megabyte or so. The safety margin is needed because the stack depth is not checked in every routine in the server, but only in key potentially-recursive routines. If this value is specified without units, it is taken as kilobytes. The default setting is two megabytes (2MB), which is conservatively small and unlikely to risk crashes. However, it might be too small to allow execution of complex functions. Only superusers and users with the appropriate SET privilege can change this setting.

Setting max_stack_depth higher than the actual kernel limit will mean that a runaway recursive function can crash an individual backend process. On platforms where PostgreSQL can determine the kernel limit, the server will not allow this variable to be set to an unsafe value. However, not all platforms provide the information, so caution is recommended in selecting a value.

How it works

max_stack_depth is a guard used by selected recursive execution paths. It neither allocates a process stack nor changes the operating-system stack limit; the kernel limit remains authoritative.

The catalog's raw boot_val is 100kB in every measured PG9.0–19 Beta 3 image, but the same fresh containers report setting=2048kB, matching the documented 2MB default after configuration/initdb. The 100kB boot fallback must not be presented as the ordinary effective setting.

A safe explicit value is the kernel stack limit, such as ulimit -s, minus roughly 1MB because not every C call site checks depth. Setting it above the real limit can let runaway recursion crash a backend. Its superuser context allows an authorized runtime change without a restart.

Operational considerations

Confusing boot_val=100kB with the measured and documented effective setting of 2048kB.

Treating max_stack_depth as allocated memory or a way to reduce resident memory.

Setting it above the kernel stack limit and allowing recursive code to crash a backend.

Copying a value across hosts without checking the service manager and ulimit stack settings.

Workload guidance

OLAP: Query duration, table size, and bulk I/O do not justify a larger stack ceiling. Change it only for verified deep expression or function recursion, and test backend stability with the same OS service limits used in production.

OLTP: Keep the effective 2MB default unless a reproducible recursive function or expression reaches the PostgreSQL guard. Before raising it, record the service's real kernel stack limit and preserve about 1MB of safety margin.

SMALL: Do not lower or raise it merely to save memory: the value is a safety check, not reserved memory. Keep the configured default unless the kernel stack and a specific recursive workload prove another value safe and necessary.