Managing Database Package Dependencies in a Workspace

Previously: In Testing Your Database Module, we added tests to the pets module. Now let's explore multi-module dependencies.

The real power of pgpm workspaces emerges when you build multiple modules that depend on each other. Instead of manually tracking deployment order, pgpm resolves the entire dependency graph automatically. In this lesson, you'll create modules that depend on other modules, use cross-module references, and leverage recursive deployment.

Prerequisites

See Prerequisites. Requires: Complete Creating Your First Postgres Database Module.

Understanding Module Dependencies

Modules declare dependencies in their .control file. Dependencies can be:

• Native Postgres extensions (pgcrypto, citext, postgis)
• Other database modules in your workspace

When you deploy a module, pgpm automatically deploys all dependencies first.

Step 1: Create a Dependent Module

Let's create an adoptions module that depends on the pets module:

cd my-database-project
pgpm init

Enter the module name:

? Enter the module name: adoptions

The module scaffolds with no dependencies. Now add pets as a dependency with pgpm extension --add:

cd packages/adoptions
pgpm extension --add pets

pgpm discovers pets by scanning the workspace for .control files, and writes it to the requires line:

# adoptions.control
comment = 'Pet adoption tracking module'
default_version = '0.0.1'
requires = 'pets'

You could also declare it up front at init time with pgpm init --extensions pets. Either way you end up with the same .control.

Step 2: Add Schema and Table Changes

Still inside the adoptions module, add a schema:

pgpm add schemas/adoptions

Edit deploy/schemas/adoptions.sql:

-- Deploy schemas/adoptions

CREATE SCHEMA adoptions;

Add an adoptions table:

pgpm add schemas/adoptions/tables/adoptions

Edit deploy/schemas/adoptions/tables/adoptions.sql:

-- Deploy schemas/adoptions/tables/adoptions

CREATE TABLE adoptions.adoptions (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  pet_id UUID NOT NULL REFERENCES pets.pets(id),
  adopter_name TEXT NOT NULL,
  adoption_date DATE DEFAULT CURRENT_DATE,
  created_at TIMESTAMPTZ DEFAULT now()
);

This table references pets.pets(id) from the pets module. pgpm ensures the pets module deploys first.

Step 3: Deploy with Recursive Resolution

Deploy the adoptions module:

pgpm deploy --database pets_dev --package adoptions --yes

pgpm automatically:

1. Detects that adoptions depends on pets
2. Checks if pets is already deployed
3. Deploys pets if needed (skipped if already deployed)
4. Deploys adoptions

This is recursive deployment—pgpm resolves the entire dependency tree automatically.

Step 4: Cross-Module Change Dependencies

You can declare dependencies on specific changes from other modules. Add a change that depends on a specific change in the pets module:

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

Edit deploy/schemas/adoptions/tables/adoption_history.sql:

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

CREATE TABLE adoptions.adoption_history (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  pet_id UUID NOT NULL REFERENCES pets.pets(id),
  event_type TEXT NOT NULL,
  event_date TIMESTAMPTZ DEFAULT now()
);

The -- requires: pets:schemas/pets/tables/pets comment tells pgpm this change depends on the schemas/pets/tables/pets change from the pets module.

Step 5: Understanding Dependency Resolution

pgpm resolves dependencies by:

1. Scanning the workspace for all .control files
2. Building a dependency graph from requires fields
3. Resolving topological order (which modules deploy first)
4. Deploying in sequence with transactional safety

Step 6: Managing Extension Dependencies

pgpm extension is the canonical way to change a module's dependencies after init. It edits only the requires line of the .control file, leaving every other field intact.

Non-interactive (scripts, CI):

cd packages/adoptions
pgpm extension --add pgcrypto        # add one (or --add a,b)
pgpm extension --remove pgcrypto     # remove one
pgpm extension --set pets,pgcrypto   # replace the whole set

Interactive picker:

pgpm extension

? Which extensions / modules does this one depend on?
  ◉ pets
  ◯ pgcrypto
  ◯ citext
  ◯ postgis

Tip: Use spacebar to select/deselect, arrow keys to navigate, and Enter to confirm. pgpm updates the .control file automatically—only the requires line changes, so custom fields you've added (comment, schema, relocatable) are preserved.

Note: The pgpm install command is for installing npm-based database packages (e.g., @pgpm/base32) into your module's extensions/ directory. That's a different workflow covered in advanced lessons.

Key Takeaways

• Modules declare dependencies in .control files
• pgpm automatically resolves dependency graphs
• Recursive deployment deploys all dependencies automatically
• Cross-module references use module:change syntax
• pgpm extension --add/--remove/--set manages dependencies (or run it with no flags for an interactive picker)
• pgpm detects circular dependencies
• Shortest path wins for naming collisions

Multi-module dependencies make pgpm workspaces powerful. Let's explore testing and packaging next.