From 42bd1639872859913b1e1dac7b60583a19b22926 Mon Sep 17 00:00:00 2001 From: Alexey Shalaev <75322386+AlexeyShalaev@users.noreply.github.com> Date: Tue, 27 Oct 2026 19:02:33 +0400 Subject: [PATCH] docs: say when to use it, and when something else fits better --- README.md | 26 ++++++++++++++++++++++++++ docs/index.md | 21 +++++++++++++++++++++ 2 files changed, 47 insertions(+) diff --git a/README.md b/README.md index 361a242..fc49479 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,32 @@ Three ways in, one version number: > docs page is also served as raw Markdown at its own URL, and a **Copy page** button at > the top of each one hands it straight to a chat window. +## When to use it, and when not + +pg-partsmith is for native PostgreSQL partitioning whose lifecycle (create ahead, expire, +detach, drop) should run from your own code or deploy: a Python service, a CronJob, a CI +step. It runs in production at its maintainer's company. + +Something else is probably the better fit when: + +- **pg_partman already works for you.** It is mature, lives in the database and serves any + client language. pg-partsmith is worth it when you can't install an extension, want + maintenance outside the database, or want to read a plan before any DDL runs. + [Migrating from pg_partman](https://bedrock-python.github.io/pg-partsmith/guide/migration/) + maps its settings one to one. +- **You want time-series features, not partitions.** TimescaleDB hypertables come with + compression and continuous aggregates. pg-partsmith manages plain declarative partitions + and nothing else. +- **You are on Django and only need time-based range partitions.** + [django-postgres-extra](https://github.com/SectorLabs/django-postgres-extra)'s + partitioning manager already fits Django migrations. pg-partsmith starts paying off with + other shapes (UUIDv7 or integer keys, hash or list under a period) or when you want a plan + before apply. +- **The table is small, or nothing in it ever expires.** Partitioning has costs of its own: + more work for the planner, and the partition key in every unique constraint. A plain table + with an index and a batched `DELETE` may be all you need. +- **Your PostgreSQL is older than 15.** It is not supported. + ## Features - **Any topology** — `RANGE(time)`, `RANGE(id)`, root `HASH`, root `LIST`, a sliding diff --git a/docs/index.md b/docs/index.md index 1c7171e..3d8fb69 100644 --- a/docs/index.md +++ b/docs/index.md @@ -68,6 +68,27 @@ result = await service.apply(config, plan) # takes the table's lock, runs the scheduler, PostgreSQL advisory or Redis locks, hooks for archiving, Pydantic configuration that round-trips through JSON and environment variables. +It runs in production at its maintainer's company. + +## When something else fits better + +- **pg_partman already works for you.** It is mature, lives in the database and serves any + client language. pg-partsmith is worth it when you can't install an extension, want + maintenance outside the database, or want to read a plan before any DDL runs. + [Migrating from pg_partman](guide/migration.md) maps its settings one to one. +- **You want time-series features, not partitions.** TimescaleDB hypertables come with + compression and continuous aggregates. pg-partsmith manages plain declarative partitions + and nothing else. +- **You are on Django and only need time-based range partitions.** + [django-postgres-extra](https://github.com/SectorLabs/django-postgres-extra)'s + partitioning manager already fits Django migrations. pg-partsmith starts paying off with + other shapes (UUIDv7 or integer keys, hash or list under a period) or when you want a plan + before apply. +- **The table is small, or nothing in it ever expires.** Partitioning has costs of its own: + more work for the planner, and the partition key in every unique constraint. A plain table + with an index and a batched `DELETE` may be all you need. +- **Your PostgreSQL is older than 15.** It is not supported. + ## Where to start