geqo_threshold

geqo_threshold — Sets the threshold of FROM items beyond which GEQO is used. Observed in PG9.0–19 Beta 3; its last measured boot default is 12 in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.

Note

Fact — official short description: “Sets the threshold of FROM items beyond which GEQO is used.”

Identity

Type , Valueinteger: Upstream pg_settings type
Context , Valueuser: Settable by an ordinary user
Unit , Value—: Raw unit
Range , Value2 – 2147483647: Raw limits in the last observed version
Enum values , Value—: — for non-enum types
Category , ValueQuery Tuning / Genetic Query Optimizer: Upstream classification
Latest boot value , Value12: 12

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	`12`	—	12

How it works

It counts FROM items and switches eligible join problems to GEQO at or above the threshold; a FULL OUTER JOIN construct counts as one item.

GEQO trades bounded planning time for a heuristic search that can miss the best join order. It still costs scan and join paths with the ordinary planner cost model after constructing candidates.

The setting is read during planning, and GEQO’s randomized search means plan quality can vary with seed and search budget. Collapse limits can change the number of relations exposed to the join search and therefore whether the threshold is crossed. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload	Guidance
OLTP	Keep geqo_threshold at its upstream default unless planning time for many-way joins is measured as a problem. Prefer simplifying generated SQL or fixing join estimates before expanding a randomized search budget globally.
OLAP	For recurring many-table reports, test geqo_threshold with multiple geqo_seed values and compare planning plus execution time. A single lucky seed is not a stable production policy.
Small nodes	Avoid increasing geqo_threshold in ways that consume disproportionate planning CPU on a small host. The default adaptive values are safer than copying a large-system GEQO budget.

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

Judging plan quality from one randomized GEQO run.
Changing a GEQO knob without accounting for geqo_threshold and collapse limits.
Spending much more planning CPU for a marginal or unstable execution-time gain.
Assuming GEQO guarantees the globally best join order.

geqo · geqo_effort · join_collapse_limit · from_collapse_limit · geqo_seed