Get started with modular databases in minutes. Install prerequisites and deploy your first module.

Quickstart: Getting Up and Running

Set up Node.js, PostgreSQL, and pgpm. Everything you need to get started with modular database development.

Prerequisites

Experience the power of modular databases by installing a pre-built module and deploying it to PostgreSQL—no SQL writing required.

Spinning Up a Modular Database in 2 Minutes

Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.

Modular PostgreSQL Development with Database Packages

Understand how pgpm workspaces bring npm-style modularity to PostgreSQL development.

pgpm Workspaces: A New Way to Organize PostgreSQL Projects

Set up your first pgpm workspace with proper configuration and structure.

Initializing a Workspace for Modular PostgreSQL Development

Build your first database module with deploy, revert, and verify scripts.

Creating Your First PostgreSQL Database Module

Write and run tests for your database module with watch mode for rapid feedback.

Testing Your Database Module

Master module dependencies, cross-module references, and automatic dependency resolution.

Managing Database Package Dependencies in a Workspace

Master the workflow for adding, organizing, and managing database changes with pgpm.

Authoring Database Changes

Learn the fundamental workflow for adding database changes using the pgpm add command and the three-file pattern for safe, reversible migrations.

Adding Your First Database Change

Structure migrations using nested paths for maintainable schemas.

Change Naming Conventions

Understand the plan file format and how pgpm generates deployment plans from SQL dependencies.

Plan Files and Deployment Plans

Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.

End-to-End PostgreSQL Testing with TypeScript

Create ephemeral PostgreSQL databases for testing with pgsql-test. Fast, isolated, and automatically cleaned up.

Spinning Up Temporary Testing Databases for Postgres

Test RLS policies by simulating different users and roles. Verify that your security policies actually work as intended.

How to Test Row-Level Security (RLS) in PostgreSQL

Test complex multi-user scenarios by switching between users within tests. Master the savepoint pattern to handle exceptions and aborted transactions when testing operations that should fail.

Advanced RLS Testing Scenarios - Simulating Many Users and Roles

Learn how to seed test databases with realistic data using loadJson, loadSql, and loadCsv methods for comprehensive testing scenarios.

Seeding PostgreSQL Test Databases

TypeScript-native testing for Supabase with modern workflows.

Supabase Testing

Introducing Supabase Test Suite: TypeScript-native testing for Supabase with isolated databases, RLS testing, and instant feedback loops.

Supabase Testing for the Modern Developer

Get started with supabase-test: install dependencies, configure local Supabase, and write your first isolated database test with automatic rollbacks.

Setting Up Local Supabase Database Testing

Create your first Supabase test with supabase-test's getConnections(), understand test isolation, and verify your setup with simple database queries.

Writing Your First Supabase Test in TypeScript

Test Supabase RLS policies by simulating authenticated users and anonymous access. Verify your security policies work as intended with supabase-test.

Testing Row-Level Security Policies in Supabase

Learn how to seed Supabase test databases with auth.users, realistic data using loadJson, loadSql, and loadCsv methods for comprehensive testing.

Seeding Supabase Test Databases

Set up GitHub Actions CI/CD pipeline to automatically test your Supabase database with every commit. Learn how to configure workflows, start Supabase, and run tests.

Running Supabase Tests in GitHub Actions

Automate Supabase testing in GitHub Actions: provision local Supabase stack, run tests in CI, and optimize for fast feedback loops.

Supabase Troubleshooting

Common issues and solutions for pgpm, PostgreSQL, and testing.

Troubleshooting

Quick fixes for common pgpm, PostgreSQL, and testing issues.

Common Issues and Solutions


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](#what-you-need)
- [Install Node.js](#install-nodejs)
- [Install pnpm](#install-pnpm)
- [Install Docker](#install-docker)
- [Install pgpm](#install-pgpm)
- [Install Postgres](#install-postgres)
  - [Install PostgreSQL Client](#install-postgresql-client)
  - [Load Environment Variables](#load-environment-variables)
  - [Verify PostgreSQL Connection](#verify-postgresql-connection)
  - [Bootstrap Database Users](#bootstrap-database-users)

## What You Need

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

## Install Node.js

Check if you have Node 20+ installed:

```bash
node --version
```

If not, download from [nodejs.org](https://nodejs.org/) or use a version manager like [nvm](https://github.com/nvm-sh/nvm):

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

```bash
npm install -g pnpm
```

Or if you prefer, you can install it via corepack (included with Node.js 16.13+):

```bash
corepack enable
corepack prepare pnpm@latest --activate
```

Verify installation:

```bash
pnpm --version
```

## Install Docker

Install Docker Desktop from [docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop/)

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

## Install pgpm

Install the PostgreSQL Package Manager globally:

```bash
npm install -g pgpm
```

Verify installation:

```bash
pgpm --version
```

## Install Postgres

### Install PostgreSQL Client

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

Follow the guide: [Install psql without PostgreSQL](https://docs.risingwave.com/deploy/install-psql-without-postgresql)

Verify the client is installed:

```bash
psql --version
```

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

### Start PostgreSQL

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

```bash
pgpm docker start
```

This command:
- Pulls the PostgreSQL Docker image (if not already downloaded)
- Starts PostgreSQL with default configuration
- Sets up a ready-to-use database

### Load Environment Variables

You have two options for configuring your PostgreSQL connection environment:

#### Option 1: Using pgpm (Recommended)

The simplest approach is to use pgpm:

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

```bash
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 PostgreSQL Connection

Test your connection:

```bash
psql -c "SELECT version();"
```

You should see your PostgreSQL version printed out.

### Bootstrap Database Users

Create database users for testing and development:

```bash
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.
