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


Database development shouldn't feel like you're stuck in 2005. When you want to build a new feature, you shouldn't spend hours configuring migration tools, manually tracking dependencies, or wondering if your schema changes will deploy in the right order. pgpm workspaces solve this by treating database schemas as composable modules—just like npm packages for your frontend code.

## The Problem: Monolithic Database Development

Traditional database development treats your entire schema as one giant migration chain. You write SQL files, number them sequentially, and hope they run in order. When you want to reuse a schema across projects, you copy-paste SQL files and lose all version history. When modules depend on each other, you manually track what needs to deploy first.

This doesn't scale. Frontend developers expect modularity—they install packages with `npm install`, compose applications from reusable components, and let the package manager handle dependency resolution. Database development deserves the same sophistication.

## pgpm Workspaces: npm for PostgreSQL

pgpm workspaces bring npm-style modularity to PostgreSQL. Instead of monolithic migration scripts, you build focused modules that declare their dependencies explicitly. Instead of manual deployment orchestration, you get automatic dependency resolution.

A pgpm workspace is a pnpm monorepo containing multiple database modules. Each module is self-contained with its own migrations, dependencies, and version tags. When you deploy, pgpm discovers all modules, resolves the dependency graph, and deploys everything in the correct order.

## Workspace vs Module: Understanding the Distinction

**Workspace**: The top-level directory containing your entire project. It has a `pgpm.json` configuration file and a `packages/` directory where modules live. Think of it like your npm project root with `package.json`.

**Module**: A self-contained database package inside the workspace. Each module has its own `pgpm.plan` file, `.control` file, and `deploy/`, `revert/`, `verify/` directories. Think of it like an individual npm package.

Example structure:
```text
my-workspace/              # Workspace root
├── pgpm.json         # Workspace config
├── packages/             # Modules directory
│   ├── users/           # Module: user management
│   │   ├── pgpm.plan
│   │   ├── users.control
│   │   ├── deploy/
│   │   ├── revert/
│   │   └── verify/
│   └── organizations/   # Module: org management
│       ├── pgpm.plan
│       ├── organizations.control
│       ├── deploy/
│       ├── revert/
│       └── verify/
```

## How Modules Declare Dependencies

Modules declare dependencies in their `.control` file, similar to `package.json`:

```sh
# organizations.control
comment = 'Organization management module'
default_version = '0.0.1'
requires = 'users,uuid-ossp'
```

This tells pgpm that the `organizations` module depends on the `users` module and the `uuid-ossp` PostgreSQL extension. When you deploy `organizations`, pgpm automatically deploys `users` first.

## Automatic Dependency Resolution

When you run `pgpm deploy`, pgpm:

1. Scans your workspace for all modules (by finding `.control` files)
2. Builds a dependency graph from the `requires` fields
3. Resolves the topological order (which modules must deploy first)
4. Deploys modules in the correct sequence
5. Tracks what's been deployed in the `pgpm_migrate` schema

You never manually specify deployment order. pgpm handles the orchestration automatically.

## Cross-Module References

Modules can reference changes from other modules in their dependency declarations. If your `organizations` module needs a specific change from the `users` module, you can declare it:

```sql
-- Deploy tables/memberships
-- requires: users:tables/users

CREATE TABLE organizations.memberships (
  user_id UUID REFERENCES users(id),
  organization_id UUID REFERENCES organizations(id)
);
```

The `-- requires: users:tables/users` comment tells pgpm that this change depends on the `tables/users` change from the `users` module. pgpm ensures `users:tables/users` deploys before this change.

## Benefits of Modular Development

- **Composability** - Build reusable modules that work across projects
- **Explicit Dependencies** - Dependencies are declared in code, not documentation
- **Transactional Safety** - All deployments happen in transactions with automatic rollback
- **Fast Iteration** - TypeScript-based engine deploys complex schemas in milliseconds
- **Cross-Project Reuse** - Publish modules to npm and install them with `pgpm install`

## What's Next

In the next lesson, we'll initialize your first pgpm workspace. You'll see how to scaffold the directory structure, configure the workspace, and prepare for module development. Then we'll create your first module and deploy it to PostgreSQL.

The future of database development is modular, composable, and fast. Let's build it together.
