Managing PGPM Dependencies

Handle dependencies between database changes and across modules in pgpm workspaces.

When to Apply

Use this skill when:

• Adding dependencies between database changes

• Referencing objects from other modules

• Managing cross-module dependencies

• Resolving dependency order issues

Dependency Types

Within-Module Dependencies

Changes within the same module reference each other by path:

-- deploy/schemas/pets/tables/pets.sql -- requires: schemas/pets

CREATE TABLE pets.pets ( id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), name TEXT NOT NULL );

Add with --requires :

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

Cross-Module Dependencies

Reference changes from other modules using module:path syntax:

-- deploy/schemas/app/tables/user_pets.sql -- requires: schemas/app/tables/users -- requires: pets:schemas/pets/tables/pets

CREATE TABLE app.user_pets ( user_id UUID REFERENCES app.users(id), pet_id UUID REFERENCES pets.pets(id), PRIMARY KEY (user_id, pet_id) );

The pets:schemas/pets/tables/pets syntax means:

• pets = module name (from .control file)

• schemas/pets/tables/pets = change path within that module

The .control File

Module metadata and extension dependencies live in the .control file:

pets.control

comment = 'Pet management module' default_version = '0.0.1' requires = 'uuid-ossp,plpgsql'

Field Purpose

comment

Module description

default_version

Semantic version

requires

PostgreSQL extensions needed

Adding Extension Dependencies

When your module needs PostgreSQL extensions:

Interactive mode

pgpm extension

Or edit .control directly

requires = 'uuid-ossp,plpgsql,pgcrypto'

Dependency Resolution

pgpm resolves dependencies recursively:

• Reads pgpm.plan for change order

• Parses -- requires: comments

• Resolves cross-module references

• Deploys in correct topological order

Example deployment order:

1. uuid-ossp (extension)
2. plpgsql (extension)
3. schemas/pets (schema)
4. schemas/pets/tables/pets (table)
5. schemas/app (schema)
6. schemas/app/tables/users (table)
7. schemas/app/tables/user_pets (references both)

Common Patterns

Schema Before Tables

pgpm add schemas/app pgpm add schemas/app/tables/users --requires schemas/app pgpm add schemas/app/tables/posts --requires schemas/app/tables/users

Functions After Tables

pgpm add schemas/app/functions/create_user --requires schemas/app/tables/users

Triggers After Functions

pgpm add schemas/app/triggers/user_updated --requires schemas/app/functions/update_timestamp

Cross-Module Reference

Module A (users):

pgpm add schemas/users/tables/users

Module B (posts):

pgpm add schemas/posts/tables/posts --requires users:schemas/users/tables/users

Viewing Dependencies

Check what a change depends on:

View plan file

cat pgpm.plan

Plan shows dependencies in brackets:

schemas/app/tables/user_pets [schemas/app/tables/users pets:schemas/pets/tables/pets] 2025-11-14T00:00:00Z Author <author@example.com>

Circular Dependencies

pgpm prevents circular dependencies. If you see:

Error: Circular dependency detected

Refactor to break the cycle:

• Extract shared objects to a base module

• Have both modules depend on the base

• Remove direct cross-references

Before (circular):

module-a depends on module-b module-b depends on module-a

After (resolved):

module-base (shared objects) module-a depends on module-base module-b depends on module-base

Deploying with Dependencies

Deploy resolves all dependencies automatically:

Deploy single module (pulls in dependencies)

pgpm deploy --database myapp_dev --createdb --yes

Deploy specific module in workspace

cd packages/posts pgpm deploy --database myapp_dev --yes

Troubleshooting

Issue Solution

"Module not found" Ensure module is in workspace packages/

"Change not found" Check path matches exactly in plan file

"Circular dependency" Refactor to use base module pattern

Wrong deploy order Check -- requires: comments in deploy files

Best Practices

• Explicit dependencies: Always declare what you need

• Minimal dependencies: Only require what's directly used

• Consistent naming: Use same paths in requires and plan

• Test deployments: Verify order with fresh database

References

• Related skill: pgpm-workspace for workspace setup

• Related skill: pgpm-changes for authoring changes

• Related skill: pgpm-testing for testing modules