Partition · XB Field Notes

Partition pruning skips whole partitions a query cannot need

Sun, 13 Feb 2028 00:00:00 +0000

Partition pruning excludes entire partitions that cannot contain matching rows. It is different from using an index to find rows within a remaining partition, and it is not a page-level cache trick. PostgreSQL can perform this exclusion while planning a query or later when parameter values become available during execution.

Prove which partitions cannot match

Declarative partitions have bounds derived from their partition key. A predicate restricting a date key to October can prove that September and November are irrelevant. Pruning uses those bounds, not an estimate that another partition probably contains few matches. Statistics still influence other planning decisions, but an inaccurate row estimate does not make partition membership a guess.

Indexes are not required for pruning. After excluding irrelevant partitions, PostgreSQL may choose a sequential scan of a remaining partition because most of its rows are needed. An Index Scan label is therefore not the test for successful pruning. Inspect the relation names and plan structure, then separately evaluate how each remaining relation is accessed.

A restriction must be usable with the partition key and its comparison semantics. Converting a date column to text can hide the direct bound relationship even when a particular string comparison happens to select the same rows. Use typed parameters and predicates that describe the intended interval directly. Do not assume that arbitrary expressions around a partition key preserve pruning or even preserve the original date semantics.

Parameters can prune during execution

A constant can allow planning-time pruning, leaving only the relevant child relation in the plan. A prepared statement’s generic plan cannot know every future parameter value in advance. That does not mean the statement must scan every partition: execution-time pruning can use values known when the plan initializes.

EXPLAIN ANALYZE reports Subplans Removed for partitions discarded during initialization. Other cases, such as parameters changing on the inner side of a nested-loop join, can prune during execution itself. Inspect loop counts and whether subplans actually ran when reasoning about those cases. A never-executed node alone can have other causes, such as an empty outer input, so interpret it in its full plan context.

Avoid turning these observations into a blanket rule that every nonconstant expression disables pruning. Parameter availability and expression support determine when exclusion is possible. Custom and generic prepared plans can differ while returning the same answer. The useful question is which partitions were accessed for the actual values used by the workload.

When it breaks

A filter on an unrelated column may leave every partition relevant. Casting the key into an incompatible expression can do the same. Check the exact predicate and enable_partition_pruning setting before changing the partition layout. Manually inventing a contradictory CHECK constraint is not a repair; ordinary local declarative partitions enforce their bounds, and constraint exclusion is a separate optimization using CHECK constraints.

Pruning also is not a promise of no locking or negligible planning cost. Partitions removed during execution initialization are still locked at the start of execution. Large partition hierarchies can consume planning time and per-session metadata memory even when a query eventually scans only a few children. Choose the hierarchy for realistic query and maintenance patterns rather than maximizing partition count.

Finally, pruning two partitions can still leave thousands of irrelevant rows inside the third. A matching local index may help that second stage. Returning only a hundred rows does not prove that only a hundred rows were examined, and buffer hits are not the same as physical disk reads.

Check it quickly

Save this as partition-pruning.sql and run psql -X -v ON_ERROR_STOP=1 -f partition-pruning.sql in a disposable PostgreSQL 18 database. The script enables pruning within its transaction and uses a generic prepared plan to expose initialization-time pruning. It creates no indexes on the temporary partitions.

\set ON_ERROR_STOP on
BEGIN;
SET LOCAL datestyle='ISO, YMD';
SET LOCAL enable_partition_pruning=on;
CREATE TEMP TABLE observations (day date,id integer) PARTITION BY RANGE(day);
CREATE TEMP TABLE obs_sep PARTITION OF observations FOR VALUES FROM ('2026-09-01') TO ('2026-10-01');
CREATE TEMP TABLE obs_oct PARTITION OF observations FOR VALUES FROM ('2026-10-01') TO ('2026-11-01');
CREATE TEMP TABLE obs_nov PARTITION OF observations FOR VALUES FROM ('2026-11-01') TO ('2026-12-01');
INSERT INTO observations SELECT DATE '2026-09-01'+g%90,g FROM generate_series(0,8999) AS g;
ANALYZE observations;
EXPLAIN (ANALYZE, BUFFERS, TIMING OFF)
SELECT count(*) FROM observations WHERE day>=DATE '2026-10-01' AND day<DATE '2026-11-01';
SET LOCAL plan_cache_mode=force_generic_plan;
PREPARE by_day(date) AS SELECT count(*) FROM observations WHERE day=$1;
EXPLAIN (ANALYZE, BUFFERS, TIMING OFF) EXECUTE by_day(DATE '2026-10-10');
EXECUTE by_day(DATE '2026-10-10');
EXPLAIN (ANALYZE, BUFFERS, TIMING OFF)
SELECT count(*) FROM observations WHERE day::text='2026-10-10';
DO $$ BEGIN
 IF (SELECT count(*) FROM observations WHERE day=DATE '2026-10-10') <> 100 OR
 (SELECT count(*) FROM observations WHERE day>=DATE '2026-10-01' AND day<DATE '2026-11-01') <> 3100 THEN
 RAISE EXCEPTION 'unexpected pruned result';
 END IF;
END $$;
DEALLOCATE by_day;
ROLLBACK;

PostgreSQL 18.6 planned the constant October range as a scan of obs_oct alone, reading 3,100 matching rows. The generic date lookup reported Subplans Removed: 2 and returned 100 rows, but still filtered 3,000 other rows within October. This demonstrates both successful partition exclusion and remaining local work.

The text-cast predicate scanned all three children and returned the same 100 rows under the explicitly chosen ISO DateStyle. Assertions verify the typed query’s counts, and DEALLOCATE plus rollback clean up the prepared statement and temporary tables. These results establish the predicate and pruning relationship for this fixture; measure representative plans separately before choosing an index or changing production partition granularity.

Sources

PostgreSQL table partitioning, planning and execution pruning, bounds, and locking, checked 2026-09-10.
PostgreSQL PREPARE, generic and custom plans and parameter handling, checked 2026-09-10.

Table partitioning splits data by range or key

Thu, 10 Feb 2028 00:00:00 +0000

Range partitioning turns a boundary definition into a write-routing rule. PostgreSQL places a row in the partition whose bounds accept its key, whether the row arrives on time or months late. Correct boundaries, compatible timestamp types, and a plan for missing ranges matter before any query can benefit from pruning.

Use adjacent half-open ranges

A range partition includes its lower bound and excludes its upper bound. September can cover the interval from September first through, but not including, October first. October then starts at that exact boundary without overlap. Do not model a month by guessing its final representable timestamp; adjacent half-open ranges work regardless of the timestamp’s fractional precision.

Queries should express the intended interval just as carefully. A lower-inclusive, upper-exclusive predicate matches a monthly slice. BETWEEN includes both endpoints, so using the next month’s first instant as its upper endpoint can include data from that next month. Partition routing does not correct a predicate that asks for the wrong interval.

The key’s type and time zone are part of the definition. A timestamptz value represents an instant, while a timestamp without time zone represents a local date and time without that instant’s zone interpretation. The example uses explicit UTC offsets for every boundary. If business months follow another time zone, derive boundaries using that zone’s rules instead of assuming every local day has the same elapsed duration.

Missing ranges are an operational state

An insert with no matching partition raises an error unless a DEFAULT partition accepts it. PostgreSQL does not automatically create the next monthly table when the calendar advances. Create needed ranges ahead of demand and account for late data and corrections to old dates. A key need not arrive monotonically for routing to work; its destination simply must still exist.

DEFAULT can absorb values outside the explicitly declared ranges. That can reduce immediate insertion failures, but it also makes missing partition management less visible unless the default table is inspected. A growing default partition can contain several unrelated time ranges and become harder to reorganize. Keep the difference between an intentional exception area and forgotten routine data visible.

Adding a new explicit partition changes which values the default partition may contain. If rows belonging to the new range remain in DEFAULT, PostgreSQL rejects the change rather than leaving overlapping ownership. Move those rows to an appropriate staging table or otherwise reconcile them before attaching the new partition. Bounds are enforced data rules, not labels that can simply be made inaccurate.

When it breaks

A deployment can fail exactly at a month boundary because the next partition was never created. Another can fail while adding that partition because DEFAULT already accumulated its rows. Both failures concern routing and data placement, not stale planner statistics. Inspect the rejected key and existing bounds before running ANALYZE or changing indexes.

ATTACH may need to scan the candidate table to validate its bounds and also check the default partition for conflicting rows. Suitable validated constraints can avoid some scans, but the operation still requires locks and compatible table structure. On active tables, coordinate writers and lock acquisition while relocating data; an isolated transactional demonstration is not a complete online migration procedure.

Nullability is separate from range selection. The example requires a nonnull timestamp so a missing event time cannot quietly become ordinary exception data. Also verify row counts and identifiers after relocation: a successful attach is not proof that an earlier copy step neither lost nor duplicated rows.

Check it quickly

Save this as partition-ranges.sql and run psql -X -v ON_ERROR_STOP=1 -f partition-ranges.sql in a disposable PostgreSQL 18 database. All tables are temporary and the whole experiment is rolled back.

\set ON_ERROR_STOP on
BEGIN;
SET LOCAL timezone='UTC';
CREATE TEMP TABLE samples (at timestamptz NOT NULL,id integer) PARTITION BY RANGE(at);
CREATE TEMP TABLE samples_sep PARTITION OF samples
FOR VALUES FROM ('2026-09-01 00:00:00+00') TO ('2026-10-01 00:00:00+00');
INSERT INTO samples VALUES ('2026-09-01 00:00:00+00',1),('2026-09-30 23:59:59.999999+00',2);
DO $$ BEGIN
 INSERT INTO samples VALUES ('2026-10-01 00:00:00+00',3);
 RAISE EXCEPTION 'upper boundary entered September';
EXCEPTION WHEN check_violation THEN RAISE NOTICE 'upper boundary needs another partition';
END $$;
CREATE TEMP TABLE samples_default PARTITION OF samples DEFAULT;
INSERT INTO samples VALUES ('2026-10-01 00:00:00+00',3);
DO $$ BEGIN
 CREATE TEMP TABLE samples_oct_bad PARTITION OF samples
 FOR VALUES FROM ('2026-10-01 00:00:00+00') TO ('2026-11-01 00:00:00+00');
 RAISE EXCEPTION 'new partition overlapped populated default';
EXCEPTION WHEN check_violation THEN RAISE NOTICE 'matching default rows must be moved first';
END $$;
CREATE TEMP TABLE samples_oct (LIKE samples INCLUDING ALL);
WITH moved AS (
 DELETE FROM samples_default
 WHERE at >= TIMESTAMPTZ '2026-10-01 00:00:00+00' AND at < TIMESTAMPTZ '2026-11-01 00:00:00+00'
 RETURNING *
) INSERT INTO samples_oct SELECT * FROM moved;
ALTER TABLE samples ATTACH PARTITION samples_oct
FOR VALUES FROM ('2026-10-01 00:00:00+00') TO ('2026-11-01 00:00:00+00');
SELECT id,at,tableoid::regclass AS physical_table FROM samples ORDER BY id;
DO $$ BEGIN
 IF (SELECT array_agg(id ORDER BY id) FROM samples_sep) IS DISTINCT FROM ARRAY[1,2] OR
 (SELECT array_agg(id ORDER BY id) FROM samples_oct) IS DISTINCT FROM ARRAY[3] OR
 (SELECT count(*) FROM samples_default) <> 0 THEN
 RAISE EXCEPTION 'range migration lost or duplicated data';
 END IF;
END $$;
ROLLBACK;

PostgreSQL 18.6 accepted the first instant of September and the final tested instant before October. October first was rejected before a destination existed, then entered DEFAULT after that partition was created. Attempting to add an overlapping October partition failed while the matching default row remained there.

The script moved that row using DELETE RETURNING, attached its staging table as October, and displayed each row’s actual tableoid. Ids one and two remained in September, id three appeared in October, and DEFAULT was empty. Assertions verify the final membership and count. This tests both boundary inclusion and a complete relocation path, without treating a quiet default partition as evidence that future range management can be omitted.

Sources

PostgreSQL table partitioning, range boundaries and routing behavior, checked 2026-09-10.
PostgreSQL ALTER TABLE, attach validation, default partitions, and locks, checked 2026-09-10.