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:

sql

-- 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:

bash

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

Cross-Module Dependencies

Reference changes from other modules using module:path syntax:

sql

-- 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:

bash

# 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:

text

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

bash

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

bash

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

Triggers After Functions

bash

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

Cross-Module Reference

Module A (users):

bash

pgpm add schemas/users/tables/users

Module B (posts):

bash

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

Viewing Dependencies

Check what a change depends on:

bash

# 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:

text

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):

text

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

After (resolved):

text

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

Deploying with Dependencies

Deploy resolves all dependencies automatically:

bash

# 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