Prerequisites

Before diving into modular database development, you need a few tools installed. If you already have Docker and Homebrew installed, this takes about 3 minutes.

Table of Contents

• What You Need
• Install Node.js
• Install pnpm
• Install Docker
• Install pgpm
• Install Postgres
  • Install Postgres Client
  • Load Environment Variables
  • Verify Postgres Connection
  • Bootstrap Database Users

What You Need

• Node.js 20+ - Required for pgpm and pnpm
• pnpm - Fast, disk space efficient package manager
• Docker - Runs Postgres server
• Postgres Client - Command-line tools (psql, createdb, dropdb)
• pgpm - Postgres Package Manager

Install Node.js

Check if you have Node 20+ installed:

node --version

If not, download from nodejs.org or use a version manager like nvm:

# Using nvm
nvm install 20
nvm use 20

Install pnpm

pnpm is a fast, disk space efficient package manager that's becoming the standard for modern Node.js projects. Install it globally:

npm install -g pnpm

Verify installation:

pnpm --version

Install Docker

Install Docker Desktop from docker.com/products/docker-desktop

After installation, open Docker Desktop and ensure it's running before proceeding.

Install pgpm

Install the Postgres Package Manager globally:

npm install -g pgpm

Verify installation:

pgpm --version

Install Postgres

Install Postgres Client

While we use Docker for the Postgres server (no local server installation needed), you need the Postgres client tools locally for commands like psql, createdb, and dropdb.

Follow the guide: Install psql without Postgres

Verify the client is installed:

psql --version

You should see the Postgres client version (the server will run in Docker).

Start Postgres

Make sure Docker is running. If you see "Cannot connect to the Docker daemon," start Docker and try again.

pgpm uses Docker to set up and run Postgres:

pgpm docker start

This command:

• Pulls the Postgres Docker image (if not already downloaded)
• Starts Postgres with default configuration
• Sets up a ready-to-use database

Load Environment Variables

You have two options for configuring your Postgres connection environment:

Option 1: Using pgpm (Recommended)

The simplest approach is to use pgpm:

eval "$(pgpm env)"

This automatically configures all necessary environment variables.

Tip: Add eval "$(pgpm env)" to your shell config (~/.bashrc, ~/.zshrc, etc.) to automatically set these variables in new terminal sessions.

Option 2: Manual Configuration

If you prefer to set environment variables manually:

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

Tip: Add these exports to your shell config (~/.bashrc, ~/.zshrc, etc.) to set them automatically in new sessions.

Verify Postgres Connection

Test your connection:

psql -c "SELECT version();"

You should see your Postgres version printed out.

Bootstrap Database Users

Create database users for testing and development:

pgpm admin-users bootstrap --yes

This creates anonymous, authenticated, and administrator roles needed for realistic database testing scenarios. You only need to run this command once.

What's Next

You're ready to spin up a modular database in 2 minutes. In the next lesson, you'll install a pre-built database module and deploy it to your database—no code required.