geqo_pool_size

Definition PG 18 manual

Controls the pool size used by GEQO, that is the number of individuals in the genetic population. It must be at least two, and useful values are typically 100 to 1000. If it is set to zero (the default setting) then a suitable value is chosen based on geqo_effort and the number of tables in the query.

How it works

It sets the number of candidate join orders in the genetic population; zero asks PostgreSQL to derive a value from effort and query size.

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.

Operational considerations

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.

Workload guidance

OLAP: For recurring many-table reports, test geqo_pool_size with multiple geqo_seed values and compare planning plus execution time. A single lucky seed is not a stable production policy.

OLTP: Keep geqo_pool_size 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.

SMALL: Avoid increasing geqo_pool_size in ways that consume disproportionate planning CPU on a small host. The default adaptive values are safer than copying a large-system GEQO budget.