Initializing a Workspace for Modular Postgres Development

Previously: In pgpm Workspaces: A New Way to Organize Postgres Projects, we explored how workspaces bring modularity to Postgres. Now let's initialize your first workspace.

Ready to build your first pgpm workspace? In this lesson, you'll scaffold a complete workspace structure, configure it for your project, and prepare for modular database development. By the end, you'll have a working workspace ready for module creation.

Prerequisites

See Prerequisites.

Step 1: Install pgpm

Install pgpm globally:

npm install -g pgpm

This gives you the pgpm command for workspace management, module scaffolding, and deployment.

Step 2: Initialize Your Workspace

Create a new workspace:

pgpm init workspace

pgpm prompts for a workspace name:

? Enter workspace name: my-database-project

pgpm scaffolds a complete pnpm monorepo:

my-database-project/
├── docker-compose.yml
├── pgpm.json
├── lerna.json
├── LICENSE
├── Makefile
├── package.json
├── packages/
├── pnpm-workspace.yaml
├── README.md
└── tsconfig.json

This structure gives you everything needed for modular database development.

Step 3: Understanding the Workspace Structure

pgpm extends pnpm workspaces by adding a pgpm.json configuration file:

{
  "packages": ["packages/*"]
}

This points pgpm to your modules directory, similar to how pnpm-workspace.yaml works for pnpm. You can customize the packages pattern or add additional configuration as needed.

Step 4: Configure Your Environment

First, see what environment variables pgpm will set:

pgpm env

This outputs the export statements:

export PGHOST=localhost
export PGPORT=5432
export PGUSER=postgres
export PGPASSWORD=password
export PGDATABASE=postgres

Now inject them into your current shell:

eval $(pgpm env)

This sets PGHOST, PGUSER, PGPASSWORD, and other connection variables. See Prerequisites if you need help.

Step 5: Verify Your Setup

Check that Postgres is accessible:

psql -c "SELECT version();"

You should see Postgres version information. If not, ensure Docker is running and Postgres is started. See Prerequisites for help.

What's Next

You now have a working pgpm workspace. In the next lesson, we'll create your first database module inside this workspace. You'll learn about module structure, the .control file, and the pgpm.plan file that tracks your migrations.

Key Takeaways

• pgpm init workspace scaffolds a complete pnpm monorepo
• The pgpm.json file configures module discovery
• Ensure Postgres is running locally before starting
• Environment variables configure Postgres connection

Your workspace is now ready for modular database development. Let's create your first module.