Plan Files and Deployment Plans

Previously: In Change Naming Conventions, we learned how to organize changes with nested paths. Now let's explore plan files and how pgpm generates them.

The plan file tracks every change in your module. pgpm can automatically generate it from your SQL files, or you can manage it manually with pgpm add.

Plan File Format

Every module has a pgpm.plan file:

%syntax-version=1.0.0
%project=pets
%uri=https://github.com/example/pets

schemas/pets 2025-11-14T10:00:00Z Dan Lynch <dan@example.com>
schemas/pets/tables/pets [schemas/pets] 2025-11-14T10:15:00Z Dan Lynch <dan@example.com>
schemas/pets/tables/adoptions [schemas/pets/tables/pets] 2025-11-14T10:30:00Z Dan Lynch <dan@example.com>

Format: change_name [dependencies] timestamp author <email> # optional note

Two Workflows

Production: Add Changes Incrementally

pgpm add schemas/pets
pgpm add schemas/pets/tables/pets --requires schemas/pets
pgpm add schemas/pets/tables/adoptions --requires schemas/pets/tables/pets

pgpm updates the plan file automatically. Add changes like commits in version control.

Pre-Production: Generate from SQL

Write SQL first for more flexibility. Add -- requires: comments:

-- Deploy schemas/pets/tables/adoptions
-- requires: schemas/pets/tables/pets

CREATE TABLE pets.adoptions (
  id UUID PRIMARY KEY,
  pet_id UUID REFERENCES pets.pets(id)
);

Then generate the plan:

pgpm plan

pgpm scans your SQL files, builds the dependency graph, and updates pgpm.plan.

Note: pgpm plan regenerates the entire plan. In production, use pgpm add to append changes without regenerating history.

Key Takeaways

• pgpm add adds changes manually to the plan
• pgpm plan auto-generates plans from -- requires: comments in SQL
• Use pgpm add for production, pgpm plan for early development