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:

1. Reads pgpm.plan for change order
2. Parses -- requires: comments
3. Resolves cross-module references
4. 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:

1. Extract shared objects to a base module
2. Have both modules depend on the base
3. 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

1. Explicit dependencies: Always declare what you need
2. Minimal dependencies: Only require what's directly used
3. Consistent naming: Use same paths in requires and plan
4. 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