max_stack_depth — PostgreSQL configuration parameter

Specifies the maximum safe depth of the server’s execution stack.

At a glance

What it does

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.

(Description quoted from the official PostgreSQL documentation.)

How to apply a change

Can be set per session with SET, per role/database with ALTER ROLE/DATABASE ... SET, or globally in postgresql.conf.

Inspect the current value and source with SHOW max_stack_depth; or SELECT name, setting, unit, context, source FROM pg_settings WHERE name = 'max_stack_depth';.

Tuning guidance

Keep it a safe margin below the OS limit (ulimit -s); the default 2MB is conservative. Raise it only if deeply recursive functions hit “stack depth limit exceeded”, and never above the kernel limit.

Reference

PostgreSQL documentation — max_stack_depth.