Postgres Branching for GitHub Actions (Create, Reset, Delete Preview DBs)

Project Goal

Postgres Branching aims to replicate Neon-style branching workflows on standard PostgreSQL, mainly for QA and preview environments in GitHub pull requests.

This project is vibe coded: it started as fast AI-assisted development, then was hardened through real CI feedback, unit tests, and integration tests.

---

What It Does

This action automates preview database lifecycle with 3 actions:

• create -> Create a preview DB from a parent/source DB
• reset -> Rebuild a preview DB from the parent/source DB
• delete -> Remove a preview DB when no longer needed

In short: Neon-like DB branching behavior for regular PostgreSQL, designed for GitHub workflows.

---

GitHub Actions Examples

1. Create Preview DB

- name: Create preview database
  uses: Eiley2/postgres-branching/create@v1
  with:
    branch_name: pr_${{ github.event.number }}
    parent_branch: app_main
    pg_host: ${{ secrets.PGHOST }}
    pg_port: ${{ secrets.PGPORT }}
    pg_user: ${{ secrets.PGUSER }}
    pg_password: ${{ secrets.PGPASSWORD }}
    pg_database: postgres
    clone_strategy: auto

2. Reset Preview DB

- name: Reset preview database
  uses: Eiley2/postgres-branching/reset@v1
  with:
    branch_name: pr_${{ github.event.number }}
    parent_branch: app_main
    pg_host: ${{ secrets.PGHOST }}
    pg_port: ${{ secrets.PGPORT }}
    pg_user: ${{ secrets.PGUSER }}
    pg_password: ${{ secrets.PGPASSWORD }}
    pg_database: postgres
    clone_strategy: auto

3. Delete Preview DB

- name: Delete preview database
  uses: Eiley2/postgres-branching/delete@v1
  with:
    branch_name: pr_${{ github.event.number }}
    pg_host: ${{ secrets.PGHOST }}
    pg_port: ${{ secrets.PGPORT }}
    pg_user: ${{ secrets.PGUSER }}
    pg_password: ${{ secrets.PGPASSWORD }}
    pg_database: postgres

---

Full PR Workflow Example

name: Preview Database Lifecycle

on:
  pull_request:
    types: [opened, synchronize, reopened, closed]

jobs:
  preview-db:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Create preview DB on open/update
        if: github.event.action != 'closed'
        uses: Eiley2/postgres-branching/create@v1
        with:
          branch_name: pr_${{ github.event.number }}
          parent_branch: app_main
          pg_host: ${{ secrets.PGHOST }}
          pg_port: ${{ secrets.PGPORT }}
          pg_user: ${{ secrets.PGUSER }}
          pg_password: ${{ secrets.PGPASSWORD }}

      - name: Delete preview DB on close
        if: github.event.action == 'closed'
        uses: Eiley2/postgres-branching/delete@v1
        with:
          branch_name: pr_${{ github.event.number }}
          pg_host: ${{ secrets.PGHOST }}
          pg_port: ${{ secrets.PGPORT }}
          pg_user: ${{ secrets.PGUSER }}
          pg_password: ${{ secrets.PGPASSWORD }}

---

Required GitHub Secrets

• PGHOST
• PGPORT
• PGUSER
• PGPASSWORD