Partitions you declare
Every quarter, somebody on your team writes CREATE TABLE events_2026_q3 PARTITION OF events FOR VALUES FROM …, runs it in each environment, and hopes they typed the bound the same way four times. The partitioned table is in your package. Its partitions are in a wiki page and somebody’s shell history.
From 2026.12.0 the partitions go in the package with the table. (Until that release is out, the lab runs on a CLI built from main.) Let’s see what SchemaSmith will and won’t do with them, because with partitions that line matters more than anywhere else.
The declaration
Section titled “The declaration”Partitioning names the method, the key, and the partitions, each with its bound written the way PostgreSQL’s \d+ shows it:
"Partitioning": { "Method": "RANGE", "Expression": "created_at", "Partitions": [ { "Name": "events_2026_q1", "Bound": "FOR VALUES FROM ('2026-01-01') TO ('2026-04-01')" }, { "Name": "events_2026_q2", "Bound": "FOR VALUES FROM ('2026-04-01') TO ('2026-07-01')" }, { "Name": "events_default", "Bound": "DEFAULT" } ]}Deploy, and the table arrives with its three partitions, created before any key or index so the primary key reaches every one of them. LIST and HASH work the same way, and a partition can carry its own Partitioning one level down: a LIST by region whose eu partition is itself RANGE by date.
One rule to know before you write a bound. A timestamp with time zone bound with no offset means UTC. SchemaSmith creates and compares partitions under UTC whatever your session’s time zone is, so '2026-07-01' and '2026-07-01 00:00:00+00' are the same bound, and a laptop in New York and a runner in Frankfurt deploy the same partitions. Ask from a New York session and that Q2 boundary reads 2026-06-30 20:00:00-04. Same instant, different clock.
Create, append, verify. Never move a row.
Section titled “Create, append, verify. Never move a row.”Here’s the posture, and every refusal in the lab is a consequence of it.
Appending is the routine release. Add next quarter’s line to the file and deploy. That’s it. One line, one deploy.
Unless rows are already waiting in DEFAULT. In the lab an August row lands in events_default before Q3 exists. Declare Q3, and the deploy stops:
Partition public.events_2026_q3 cannot be added to public.events: its DEFAULT partition events_default holds rows inside the bound FOR VALUES FROM ('2026-07-01') TO ('2026-10-01'). Adding it would move those rows, which SchemaSmith does not do -- move them manually, then redeploy.PostgreSQL would happily move them, scanning DEFAULT under a lock while it does. That’s a data migration, and a deploy shouldn’t start one nobody asked for. Exit 2, nothing changed, and the message tells you exactly which rows are in the way.
Adding a partition locks the table, briefly but completely. Under OnlineApply: Require it’s refused by name, the same promise Course 6 makes for indexes.
A changed bound is refused before anything happens. Moving Q1’s start to December means a DETACH and a re-ATTACH, which moves or re-checks rows, and the message says so in those words. A changed key, or a leaf partition’s tablespace, gets the same answer. Do it by hand, then correct the declaration.
A partition you didn’t declare is left alone. A lot of teams let pg_partman or a cron job create partitions ahead of time. When the deploy finds one the package doesn’t name, it logs not declared in the package (left as it is; SchemaSmith does not drop or detach partitions) and moves on. A partition is data. So the package and a partition manager can share a table, and if the manager owns every partition, "Partitions": [] is legal.
And --Validate catches the shapes PostgreSQL won’t accept before a deploy tries them: a primary key without the partition key in it (SS-PART-005), a generated column in the key, an unlogged partitioned table.
SchemaTongs extracts all of it: a partitioned table comes out with its partitions under Partitioning, and no partition gets a file of its own.
Check yourself: Your partition manager pre-creates next month's partitions at midnight. Your package declares only the partitions from last year. What does each deploy do with the manager's partitions, and what would make the deploy refuse to run?
It leaves them alone. A partition the package doesn’t declare is reported in the log and never dropped or detached, so the manager and the package can share the table. The deploy refuses, by name and before changing anything, when a declared partition would need rows moved or re-checked: a new partition whose range already has rows sitting in DEFAULT, a declared bound or key that differs from the deployed one, or a declared partition that already exists as a standalone table or under another parent. Adding a partition is also refused under OnlineApply: Require, because it locks the table.
Partitions are the one place a schema file sits right on top of the data. So SchemaSmith works like a careful smith with a finished piece on the anvil. It’ll add new metal, check what’s there, and name any blow that would crack what’s already been forged. Then it puts the hammer down and waits for you.
Running partitions by script in four environments and tired of the quarterly ritual? Email me at forgebarrett@schemasmith.com. I read every one.
Until then, may every quarter arrive with its partition already waiting.
— Forge