max_stack_depth

max_stack_depth — Sets the maximum stack depth, in kilobytes. Observed in PG9.0–19 Beta 3; its last measured boot default is 100 KiB in PG19 Beta 3, with superuser context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.

Note

Fact — official short description: “Sets the maximum stack depth, in kilobytes.”

Identity

Type , Valueinteger: Upstream pg_settings type
Context , Valuesuperuser: Settable at runtime by a superuser
Unit , ValuekB: Raw unit
Range , Value100 – 2147483647: Raw limits in the last observed version
Enum values , Value—: — for non-enum types
Category , ValueResource Usage / Memory: Upstream classification
Latest boot value , Value100: 100 KiB

Lifecycle

Fact	Value
First observed	PG9.0 (research boundary)
Present in	PG9.0–19 Beta 3
Removed in	No
Introduction commit	Not asserted: predates the PG9.0 research boundary
Commit date	—
Discussion	—

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions	Raw `boot_val`	Unit	Human value
PG9.0–19 Beta 3	`100`	`kB`	100 KiB

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.

Tuning advice

Tip

Advice. These are workload-specific starting points and must be validated with measurements.

Workload	Guidance
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.
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.
Small nodes	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.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG19 Beta 3; this does not assert current Pigsty support for that historical or beta release.

Template	Effective value	Versus upstream boot	Source expression
OLTP	Unmodified	—	—
OLAP	Unmodified	—	—
CRIT	Unmodified	—	—
TINY	Unmodified	—	—

Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 unmodified; OLAP: PG9.0–19 Beta 3 unmodified; CRIT: PG9.0–19 Beta 3 unmodified; TINY: PG9.0–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

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.

max_worker_processes · shared_buffers · work_mem · max_connections