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


> **Previously:** In [Seeding Supabase Test Databases](./seeding-supabase-test-databases), we learned efficient strategies for seeding test data. Now let's automate our tests with GitHub Actions.

Running tests locally is essential during development, but you need continuous integration to ensure code quality as your team grows. GitHub Actions provides a free CI/CD platform that can run your Supabase tests on every commit and pull request.

In this lesson, you'll set up a GitHub Actions workflow to automatically test your Supabase database with every code change.

## Prerequisites

See [Prerequisites](/learn/quickstart/prerequisites). Requires: Complete [Seeding Supabase Test Databases](./seeding-supabase-test-databases).

## Why Run Tests for Supabase in CI?

Without automated testing, developers often write code directly against production Supabase instances—a risky practice that can lead to data loss or downtime.

Continuous Integration provides a safe alternative:

- **Automated testing** on every commit and pull request
- **Consistent environment** eliminates "works on my machine" issues
- **Avoid production testing** - catch issues before they affect live data
- **Team confidence** in merging changes without breaking tests
- **Early detection** of schema changes and RLS policy issues

## Create GitHub Actions Workflow

This workflow uses the official [Supabase GitHub Actions](https://supabase.com/docs/guides/functions/examples/github-actions) to set up the Supabase CLI in your CI environment.

Create `.github/workflows/test.yml` in your repository:

```yaml
name: Supabase tests
on:
  push:
  pull_request:
    types: [opened, synchronized, reopened]
  workflow_dispatch:

jobs:
  test:
    runs-on: ubuntu-latest
    continue-on-error: true
    strategy:
      fail-fast: false
      matrix:
        package:
          - my-supabase-app

    env:
      PGHOST: 127.0.0.1
      PGPORT: 54322
      PGUSER: supabase_admin
      PGPASSWORD: postgres
      DATABASE_URL: "postgresql://postgres:postgres@127.0.0.1:54322/postgres"

    steps:
      - name: Configure Git (for tests)
        run: |
          git config --global user.name "CI Test User"
          git config --global user.email "ci@example.com"

      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Supabase CLI
        uses: supabase/setup-cli@v1
        with:
          version: latest

      - name: Initialize Supabase (if needed)
        run: test -d supabase || supabase init

      - name: Start Supabase stack
        run: supabase start

      - name: Show Supabase status
        run: supabase status

      - name: Install Postgres client
        run: |
          sudo apt-get update
          sudo apt-get install -y postgresql-client

      - name: Wait for Postgres
        run: |
          for i in {1..60}; do
            if pg_isready -h 127.0.0.1 -p 54322 -U postgres; then
              exit 0
            fi
            sleep 2
          done
          echo "postgres not ready in time"
          docker ps
          supabase status
          exit 1

      - name: Enable corepack and pnpm
        run: |
          corepack enable
          corepack prepare pnpm@9 --activate
          pnpm -v
          node -v

      - name: Install
        run: pnpm install

      - name: Install pgpm CLI globally
        run: npm install -g pgpm

      - name: Build
        run: pnpm -r build

      - name: Seed pg and app_user
        run: |
          # bootstrap admin user NOT REQUIRED FOR supabase
          # pgpm admin-users bootstrap --yes
          # optional, but added to avoid concurrent attempts to add user
          pgpm admin-users add --test --yes

      - name: Test ${{ matrix.package }}
        run: cd ./packages/${{ matrix.package }} && pnpm test
```

## Real-World Example

Want to see Supabase tests running in production CI? Check out the [supabase-test-suite](https://github.com/constructive-io/supabase-test-suite) repository—a comprehensive example with working GitHub Actions workflows.

## Key Takeaways

- **GitHub Actions** provides free CI/CD for public repositories
- **Supabase CLI** can start a local instance in CI environments
- **Official Supabase Actions** simplify setup and configuration
- **Real examples** like supabase-test-suite demonstrate production patterns

You've automated your Supabase tests with GitHub Actions. Every commit and pull request now runs your full test suite, giving you confidence in your database changes. 