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 Postgres 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.

End-to-End Postgres Testing with Supabase

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.

Troubleshooting Supabase Test

Learn to test PostgreSQL databases with Drizzle ORM, including RLS policies and context management.

End-to-End Postgres Testing with Drizzle ORM

Set up Drizzle ORM with drizzle-orm-test for PostgreSQL testing. Create type-safe database queries with automatic test isolation.

How to Setup Drizzle ORM for End-to-End Testing

Test RLS policies with Drizzle ORM using automatic context management. Verify security policies with type-safe queries.

Testing Row-Level Security with Drizzle ORM

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

Troubleshooting

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

Common Issues and Solutions


See [Prerequisites](/learn/quickstart/prerequisites).

Experience the power of modular databases in under 2 minutes. You'll install a pre-built database module from npm and deploy it to PostgreSQL—no SQL writing required. This is your first taste of modular database development.

## What You'll Build

By the end of this lesson, you'll have a working PostgreSQL database with UUID generation capabilities, deployed using pgpm's module system. This demonstrates how pgpm modules work like npm packages—install, deploy, done.

## Step 1: Create a Workspace

Create a directory for your project:

```bash
pgpm init workspace
```

pgpm prompts for a workspace name:

```sh
? Enter the workspace name: quickstart-demo
```

This creates a complete workspace structure with everything you need.

## Step 2: Create Your First Module

Change directory to your workspace:

```bash
cd quickstart-demo
```

Initialize a module inside your workspace:

```bash
pgpm init
```

Answer the prompts:

```sh
? Enter the module name: demo
? Which extensions? (Press space to select, enter to continue)
```

Just press Enter to skip extensions for now. pgpm scaffolds a complete module structure:

```md
packages/demo/
├── demo.control
├── pgpm.plan
├── deploy/
├── revert/
└── verify/
```

## Step 3: Install a Database Module

Navigate to your module and install a pre-built database module:

```bash
cd packages/demo
pgpm install @pgpm/faker
```

pgpm downloads the module from npm and installs it into your workspace's `extensions/` directory.

Your module's `package.json` is automatically updated with the dependency.

## Step 4: Deploy to PostgreSQL

Deploy to a new database (pgpm will create it for you):

```bash
pgpm deploy --database quickstart_dev --createdb --yes
```

> **Note:** Make sure Docker Desktop is running before deploying.

pgpm deploys the UUID module to your database. You'll see output like:

```sh
[cli] INFO: Selected package: demo
[deploy] SUCCESS: 🚀 Starting deployment to database quickstart_dev...
[deploy] INFO: 📥 Installing external extension: citext
[deploy] INFO: 📥 Installing external extension: pgcrypto
[deploy] INFO: 📥 Installing external extension: plpgsql
[deploy] INFO: 📥 Installing external extension: uuid-ossp
[deploy] INFO: 📂 Deploying local module: launchql-verify
[deploy] INFO: 📂 Deploying local module: launchql-types
[deploy] INFO: 📂 Deploying local module: launchql-faker
[deploy] INFO: 📂 Deploying local module: demo
[migrate] INFO: Checking pgpm migration schema...
[migrate] SUCCESS: Migration schema found and ready
[deploy] SUCCESS: ✅ Deployment complete for demo.
[cli] SUCCESS: Deployment complete.
[pg-cache] SUCCESS: pg.Pool quickstart_dev ended.
```

## Step 5: Verify It Works

Test the deployed faker schema and its tables and functions:

Query the faker.cities table to see sample city data:

```bash
psql -d quickstart_dev -c "SELECT * from faker.cities LIMIT 1"
```

You should see a row:

```text
                  id                  |   city   | state |           zips            |   lat   |   lng
--------------------------------------+----------+-------+---------------------------+---------+----------
 e36c5cc7-eb79-42be-8a11-5bcd535c8147 | New York | NY    | {11226,11225,11224,11222} | 40.6943 | -73.9249
(1 row)
```

Test the `faker.business()` function to generate a random business name:

```bash
 psql -d quickstart_dev -c "SELECT faker.business()"
```


```text
  business
------------
 Brand Fund
(1 row)
```

## What Just Happened?

In under 2 minutes, you:

1. **Created a workspace** - A modular project structure for database packages
2. **Initialized a module** - Your database package
3. **Installed a dependency** - A pre-built database module from npm
4. **Deployed to PostgreSQL** - With automatic dependency resolution
5. **Verified functionality** - UUID generation working instantly

This workflow demonstrates the core philosophy of modular databases: database development should be as modular and productive as frontend development. You didn't write SQL, configure migrations, or manually track dependencies. pgpm handled the infrastructure.

## Understanding the Module System

The `@pgpm/faker` module you installed is a real npm package containing:
- SQL migration scripts
- Dependency declarations
- Version information

When you ran `pgpm install`, pgpm:
1. Downloaded the package from npm
2. Extracted the database module
3. Placed it in `extensions/@pgpm/faker`
4. Updated your module's dependencies

When you ran `pgpm deploy`, pgpm:
1. Resolved the dependency graph
2. Deployed dependencies first
3. Deployed your module
4. Tracked everything in the database

## Exploring What Was Deployed

Check the migration tracking:

```bash
pgpm migrate status --database quickstart_dev
```

You'll see all deployed modules and changes.

## Rolling Back (Optional)

If you want to revert everything:

```bash
pgpm revert --database quickstart_dev
```

pgpm runs the revert scripts in reverse order, cleanly removing all changes.

## What's Next

You've experienced the install-and-deploy workflow for modular databases, but the real power comes when you start authoring your own database changes. In the next course, you'll learn how to:
- Create custom database schemas
- Add migrations with deploy/revert/verify scripts
- Manage dependencies between changes
- Build reusable database modules

## Key Takeaways

- **Database modules are npm packages** - Install database code like frontend dependencies
- **Automatic dependency resolution** - pgpm deploys in the correct order
- **Migration tracking built-in** - Every deployment is tracked and reversible
- **Zero configuration** - No build tools, no manual migration management
- **Fast feedback loops** - From install to deployed database in seconds

The workflow you just experienced—from zero to deployed database in 2 minutes—demonstrates the power of modular databases. This same pattern scales from simple utilities to complex multi-module applications.

Ready to start building your own modules? Check out the "Modular PostgreSQL Development with Database Packages" course to learn how to author database changes.
