# pg_pathman partitions Postgres tables without the planning overhead

> pg_pathman is a PostgreSQL extension that adds RANGE and HASH partitioning with a custom planner that looks up matching partitions instead of scanning them, plus runtime plan nodes for cross-partition updates. Its own documentation says the project is no longer under development, and that native partitioning is now the recommended path.

**postgrespro/pg_pathman** — Partitioning tool for PostgreSQL

- Repository: https://github.com/postgrespro/pg_pathman
- Stars: 588 · Forks: 70
- Language: C
- License: NOASSERTION
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/postgrespro-pg-pathman

## Why the classic partitioning approach hurt planning

The extension exists to solve a specific planner problem, and the README explains the problem before the solution. Partitioning means splitting one large table into smaller pieces, where each row moves to a single partition according to the partitioning key. PostgreSQL 10 and later provide native partitioning, and the documentation is candid that it is not so different from the classic approach, with implicit check constraints and most of the same limitations. The cost is in the planner. Despite the flexibility, the approach forces the planner to perform an exhaustive search and to check constraints on each partition to decide whether it should appear in the plan. A large number of partitions therefore means significant planning overhead, which is the specific pain pg_pathman was written to remove. The second reason to read the note is that the project is explicit about its own status. It supports Postgres versions 11 to 15, most probably will not be ported to later releases, and the documentation encourages users to switch to native partitioning because that is now pretty mature and has almost everything implemented in pg_pathman.

## A planner that looks up partitions instead of scanning them

The mechanism is a partition-aware planner that uses knowledge of the partition structure rather than re-deriving it. The extension stores its partitioning configuration in a pathman_config table, with one row per partitioned table holding the relation name, the partitioning column and its type. During initialisation the module caches information about child partitions in shared memory, and that cache is used later when plans are constructed. Before a SELECT query runs, pg_pathman walks the condition tree looking for expressions of the shape VARIABLE OP CONST, where the variable is the partitioning key, the operator is one of the supported comparisons, and the constant is a scalar value, so a predicate like WHERE id = 150 is recognised as a partition lookup. Based on the partitioning type and the operator, the module finds the corresponding partitions and builds the plan. Two schemes are supported, RANGE, which maps rows to partitions using key ranges assigned to each partition and optimises the lookup with a binary search, and HASH, which maps rows with a generic hash function. The practical difference from stock behaviour is that the number of partitions stops driving planning time, which is what makes a hundred-partition table behave like a single table.

## Partition management, runtime nodes and the rest of the feature list

The feature list is long and a few entries carry real weight. Partitioning by expression and composite key is supported, and so are integer, floating point, date and other types including domains, with both automatic and manual partition management. Automatic partition creation for newly inserted data works for RANGE partitioning only. A PartitionFilter node is offered as an efficient drop-in replacement for INSERT triggers, and PartitionRouter and PartitionOverseer handle cross-partition UPDATE queries instead of triggers, which is the case that triggers handle badly. RuntimeAppend and RuntimeMergeAppend custom plan nodes pick partitions at runtime, and the module includes an improved COPY FROM that inserts rows directly into partitions, user-defined callbacks for partition creation events, non-blocking concurrent table partitioning for data migration, and FDW support so a partition can live in a foreign table. There is also partial support for declarative partitioning from PostgreSQL 10, and a set of GUC toggles and configurable settings. The module is written in C, and the source tree is laid out as you would expect for a PostgreSQL extension, with the planner and node code in src/ and the SQL interface split into pl_funcs, pl_range_funcs and pl_hash_funcs files.

## Building and installing the extension

Installation is a make invocation in the module directory.

```bash
make install USE_PGXS=1
```

The USE_PGXS flag is what makes this work against an installed PostgreSQL rather than a source tree, and the documentation flags one thing you must not forget: set the PG_CONFIG variable with make PG_CONFIG=... if you want to test against a non-default or custom build of PostgreSQL, with a link to the wiki page on building and installing extension modules. The next step is a configuration change, because the module needs to be preloaded.

```bash
shared_preload_libraries = 'pg_pathman'
```

Restarting the instance is essential. After that you create the schema and the extension in psql.

```sql
CREATE SCHEMA pathman;
GRANT USAGE ON SCHEMA pathman TO PUBLIC;
CREATE EXTENSION pg_pathman WITH SCHEMA pathman;
```

One conflict is called out specifically, and it is worth knowing before you enable it. pg_pathman may conflict with other extensions that use the same hook functions, because it uses ProcessUtility_hook to handle COPY queries for partitioned tables, which means it may interfere with pg_stat_statements from time to time, and the fix is to list the libraries in a particular order, with shared_preload_libraries = 'pg_stat_statements, pg_pathman'.

## The search-path caveat and the Windows build note

The extension ships with a security notice, and it is more nuanced than a blanket assurance. pg_pathman is believed to be secure against the search-path-based attacks described in the PostgreSQL documentation, but if your calls of pathman's functions do not exactly match the signature, they might be vulnerable to malicious overloading. The advice in that case is to install pathman into a clean schema where nobody except superusers has CREATE object permission, which avoids the problem. That is a real operational requirement rather than a footnote, because a schema that a non-superuser can write to is a common situation in a shared database. There is a separate Windows-specific note, which says pg_pathman imports several symbols such as None_Receiver and InvalidObjectAddress from PostgreSQL, which is fine by itself but requires those symbols to be marked as PGDLLIMPORT, and the text then goes on to explain the consequences in a passage that is cut off in the version available here. On the build side, the repository also carries a Makefile with the extension's object list, the upgrade scripts from 1.0 through 1.5, a Dockerfile.tmpl and a docker-compose.yml whose only service builds the image and runs the tests, plus a specs/ directory for the expected outputs and a run_tests.sh script.

## Where pg_pathman is the wrong tool now

The honest answer for most teams is that it is the wrong tool, and the project's own documentation says so. It supports Postgres 11 to 15, so on PostgreSQL 16 or later it is not an option at all, and the note that it most probably will not be ported to later releases means an upgrade path for the server version is not coming from here. The second limit is the maintenance model. The README says plainly that this project is not under development anymore, that the team is still maintaining it by fixing bugs in supported versions, and that no new development is going to happen. The last push to the repository was on 2026-09-07, and the most recent tagged release is 1.5.12 from 2020-11-08, whose title mentions Postgres 13 compatibility and a CVE-2020-14350 fix, with 1.5.11 from April 2020 and 1.5.10 from November 2019 before it. So a fresh install gets a five year old feature set with occasional fixes. The third limit is the licence. The repository is filed under a custom licence that GitHub cannot classify, with the terms in the LICENSE file, and that is worth reading if you intend to redistribute it. The alternative is the obvious one, native declarative partitioning, which the documentation itself recommends, and which comes with the same partitioning model without a C extension, a preload requirement and a planner hook.

## Conclusion

Adopt pg_pathman only if you are on PostgreSQL 11 to 15 and need the partition management functions, the cross-partition update nodes or foreign partitions that the extension provides and native declarative partitioning does not. Skip it for anything new, because the project states that native partitioning is pretty mature now, has almost everything implemented in pg_pathman, and that users are encouraged to switch, with no new development going to happen here. Before you install it, read the security notice about search-path attacks and the note that the extension can conflict with other extensions that hook the same functions, such as pg_stat_statements.

## FAQ

### Is pg_pathman still being developed?

No. The README states that this project is not under development anymore, that the team is still maintaining it by fixing bugs in supported versions, and that no new development is going to happen. The last push was on 2026-09-07 and the most recent release is 1.5.12 from 2020-11-08.

### Which PostgreSQL versions does pg_pathman support?

Postgres versions 11 to 15, with PostgreSQL 12 and 13 fully compatible, 11, 14 and 15 requiring a core patch, and Postgres Pro Standard 11 through 15 plus Postgres Pro Enterprise also listed as compatible.

### How do I install pg_pathman?

Run make install USE_PGXS=1 in the module directory, set PG_CONFIG if you are on a custom PostgreSQL build, add pg_pathman to shared_preload_libraries in postgresql.conf, restart the instance, then create a schema and run CREATE EXTENSION pg_pathman WITH SCHEMA pathman in psql.

### Does pg_pathman conflict with other PostgreSQL extensions?

It can, because it uses ProcessUtility_hook to handle COPY queries for partitioned tables, which may interfere with pg_stat_statements from time to time. The documented workaround is to order the preload list, listing pg_stat_statements before pg_pathman.

## Sources

- [Issues](https://github.com/postgrespro/pg_pathman/issues)
- [postgrespro/pg_pathman on GitHub](https://github.com/postgrespro/pg_pathman)
- [README](https://github.com/postgrespro/pg_pathman/blob/master/README.md)
- [Releases](https://github.com/postgrespro/pg_pathman/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/postgrespro-pg-pathman