Articles on pgmi

Your Deployment Is a PostgreSQL Program

Wed, 26 Aug 2026 00:00:00 +0000

Your Deployment Is a PostgreSQL Program#

Every migration tool is a program that executes your SQL. Invert the control flow and deployment policy becomes SQL the project owns.

By Alexey Evlampiev

Abstract. Every team that adopts a migration tool eventually goes looking for a flag. The release needs one thing the tool did not anticipate — a check that must run after the schema change but before the commit, a concurrent index built in the middle of an otherwise transactional deployment, an ordering rule that filenames cannot express — and the search begins: through the configuration reference, then the issue tracker, then the changelog of a version that has not shipped. The flag is the visible symptom of an invisible arrangement. A migration tool is a program that executes your SQL, which means every deployment semantic — what runs, in what order, inside which transaction, and whether the result is allowed to commit — belongs to the tool’s vocabulary. Anything outside that vocabulary is a feature request. This article describes the inversion: a tool that prepares one PostgreSQL session, materializes the project as relations inside it, and hands deployment policy to a SQL program the project owns. The tool keeps the execution mechanism; the project takes the policy. What used to require a tool feature becomes SQL the project owns. The scope is the database semantics — choosing and ordering the work, controlling its transaction boundaries, validating the result, and deciding whether it may commit — and not the cloud APIs, secret stores, and approval gates around them. The costs are specific too, and the last part names them.

Scenario-Tree Testing in PostgreSQL: Every Authored Branch, Shared History, Before COMMIT

Tue, 25 Aug 2026 00:00:00 +0000

Scenario-Tree Testing in PostgreSQL: Every Authored Branch, Shared History, Before COMMIT#

Express the branching scenarios of your business logic as a directory tree; walk it with savepoints so each branch inherits its history instead of rebuilding it; and let the walk decide whether your deployment commits.

By Alexey Evlampiev

Abstract. Database tests often repeat the same state-building work, because several scenarios share the same prefix: a device may be provisioned before testing its configuration paths; an order may be paid before testing shipment and refund; a workflow may be approved before testing its downstream outcomes. The running example throughout is an order lifecycle — chosen only because its branching states are easy to see, and standing in for whatever lifecycle your own database implements. To test both placed → paid → shipped and placed → paid → refunded, a conventional suite constructs placed → paid twice. This article develops the alternative: express the scenarios as a directory tree and walk it with PostgreSQL savepoints — execute the shared prefix once, test one branch, roll back to the branch point, and test its sibling from the same inherited state. Every scenario then runs against the accumulated state it actually depends on, without rebuilding that state and without seeing a sibling’s changes. A lifecycle’s reachable histories branch like a multiverse, far beyond what a practical suite can cover, so the tree is authored, not exhaustive: you choose the critical paths, and the walk proves each one from the exact parent state it depends on — proof here meaning execution plus declared-invariant checks, not formal verification. And because most PostgreSQL DDL is transactional, the whole walk can run inside a still-uncommitted deployment: apply the migration, run the tree, discard the test state, and commit only if every authored scenario passes.

The Request Becomes a Transaction

Fri, 21 Aug 2026 00:00:00 +0000

The Request Becomes a Transaction#

A transactional API has two halves: a network edge and a transactional operation. Keep the first at that edge; give the second to PostgreSQL, where its authority already lives — and every declared outcome of every operation becomes provable in the same transaction.

By Alexey Evlampiev

Abstract. The last five years consolidated storage into PostgreSQL: the queue, the cache, the search index, and the vector store moved in, one “just use Postgres” argument at a time. The API tier did not move — and the debate over whether it should is usually fought across the wrong boundary. A transactional API has two halves. The network edge authenticates the caller and adapts HTTP. The transactional boundary resolves the operation, validates its input, authorizes it against current state, executes the transition, and shapes the result. Convention puts the first half in a gateway and the second in an application framework — even though every authoritative decision in the second half already terminates in PostgreSQL. This article moves that boundary to where its authority lives, focusing on APIs whose valuable behavior is transactional decision-making over PostgreSQL state. The unit of design becomes the transactional operation: a named database operation with a typed contract, an authorization policy, a declared transaction, an implementation, and tests — and each protocol surface, starting with REST, becomes a binding to it. The payoff is one authority, one transaction, one executable proof: a test can invoke an operation end to end, assert on the response and the state transition in the same snapshot, and roll everything back.

Your ALTER TABLE Is Fast. The Queue Behind It Is Not.

Sat, 01 Aug 2026 00:00:00 +0000

Your ALTER TABLE Is Fast. The Queue Behind It Is Not.#

A schema change that runs in six milliseconds can still stop every read on the table for sixteen seconds — the damage is done by waiting, not by working.

By Alexey Evlampiev

Here is the same statement, run twice against the same table — PostgreSQL 16.14 in a local container, an orders table of 100,000 rows, the contending session held open with pg_sleep. These are illustrative numbers from one machine, not a benchmark; the ratio is the point, and you can reproduce it in about a minute.

Your Transaction Boundary Belongs in the Program, Not the Filename

Sat, 01 Aug 2026 00:00:00 +0000

Your Transaction Boundary Belongs in the Program, Not the Filename#

A phased schema change spans transactional and non-transactional work. Most migration frameworks express that distinction as metadata; pgmi makes it part of the SQL program.

By Alexey Evlampiev

Three facts about PostgreSQL decide how a deployment has to be shaped, and all three are the server’s rules rather than any tool’s.

A table-level lock is held until the end of the transaction that took it, not until the statement finishes — so a six-millisecond ALTER TABLE at the top of a five-minute transaction blocks readers for five minutes. lock_timeout bounds how long a statement waits for a lock, which is a different quantity again. And CREATE INDEX CONCURRENTLY, the statement you reach for precisely because it does not block reads or writes, refuses to run inside a transaction block at all — and refuses a second way, from inside any function, procedure or DO block, with a different error:

Your Migration Numbers Are a Distributed Counter Without Coordination

Fri, 31 Jul 2026 00:00:00 +0000

Your Migration Numbers Are a Distributed Counter Without Coordination#

What migration-number collisions reveal about identity, ordering, and enforcement.

By Alexey Evlampiev

Two engineers branch from the same commit on the same Tuesday. Each adds a migration; each picks the next free number — V42. Git merges both files without complaint: two new files, no textual conflict. The migration runner cannot merge them. Two changes now claim the same position.

Timestamp versions make that exact collision unlikely, but trade it for a subtler problem: late arrival. A migration stamped earlier can merge after a later one has already run in some environment. Flyway ignores the straggler by default; its outOfOrder setting applies it — “a newly discovered version 2.0 will be executed rather than ignored” — at the cost of an application history that now differs from a freshly built environment. If you have run migrations on a team of more than two people you have lived some version of this, and lived the fixes: timestamp prefixes, outOfOrder, renumbering commits, “announce in Slack before you add a migration.”

From Seed Scripts to Desired-State Reference Data in PostgreSQL

Tue, 21 Jul 2026 00:00:00 +0000

From Seed Scripts to Desired-State Reference Data in PostgreSQL#

Version the catalog that should exist — not the procedure that inserts it.

By Alexey Evlampiev

A seed script records how to construct a catalog. What you need to version is the catalog that should exist.

The difference barely matters when seed.sql is twelve lookup rows. It starts to matter once roles reference permissions, workflow states reference their legal transitions, and plan tiers reference feature flags — once every edit has to preserve foreign-key order by hand. At that point the script has quietly become a hand-maintained topological sort of your data model: an acyclic insert-dependency graph, revised on every new relationship and enforced by nothing but SQLSTATE 23503 at deploy time.

AI agents write PostgreSQL like Python

Wed, 15 Jul 2026 00:00:00 +0000

AI agents write PostgreSQL like Python#

The Python habits agents carry into PL/pgSQL — exceptions as control flow, casts as trust, validation scattered everywhere — and the handler discipline that contains them.

By Alexey Evlampiev

Give a coding agent a PostgreSQL-first backend to build and it will write you working SQL. It will also, with remarkable consistency, write you Python — Python’s exception-driven control flow, Python’s trust in casts, Python’s habit of validating wherever the code happens to be — transliterated into PL/pgSQL, where those idioms carry costs the agent never sees.

Test PostgreSQL migrations before COMMIT

Sat, 11 Jul 2026 00:00:00 +0000

Test PostgreSQL migrations before COMMIT#

Test a migration after it applies but before it commits — and let COMMIT depend on the checks.

By Alexey Evlampiev

Most migration pipelines test before deployment or after commit. PostgreSQL allows a third checkpoint: after applying the change, but before committing it. Lint and rehearsal catch what they can in advance; integration suites catch what they can afterwards. The checkpoint in between is the only one where the real target database — with whatever drift it has accumulated — is in its migrated state while rollback is still one statement away.