hyperbranch

Database branches for Cloudflare Worker Previews.

hyperbranch is a lightweight CLI intended to run as a Workers Builds Preview command. It creates a database branch for the Git branch, connects it through a dedicated Hyperdrive configuration, injects that binding into the Worker Preview, and then runs wrangler preview.

PlanetScale Postgres is the first provider. The provider boundary is intentionally small so Neon, Supabase, and other branching databases can follow.

Experimental: this creates billable database and Hyperdrive resources. Use a test database first and configure cleanup before relying on it.

Why this exists

Worker Previews automatically isolate Durable Objects and Containers. Cloudflare's resource matrix says Hyperdrive configurations must be created manually, and true isolation requires a separate Hyperdrive config pointing at a separate database or schema. Preview deletion does not delete either resource.

This project fills that lifecycle gap. It does not replace Worker Previews: it prepares the database binding and delegates deployment to wrangler preview.

How it works

git branch
  -> PlanetScale Postgres branch
  -> managed PlanetScale Hyperdrive config
  -> previews.hyperdrive binding
  -> wrangler preview

Repeated deployments are idempotent. Names are derived from WORKERS_CI_BRANCH, which Workers Builds provides automatically. Every normalized name includes a hash of the original Git ref so similar branch names cannot share resources. A stable Git branch therefore keeps the same database branch, Hyperdrive config, and Preview URL.

Prerequisites

• Node.js 22 or newer
• Wrangler 4.135.0 or newer
• A Cloudflare account linked to PlanetScale in the Hyperdrive dashboard
• An existing PlanetScale Postgres database
• A Wrangler JSON or JSONC configuration file

The initial release does not support wrangler.toml.

Install

Until the package is published, install it from GitHub in your Worker project:

npm install --save-dev github:ygwyg/hyperbranch

Configure

Create hyperbranch.config.json beside your Wrangler configuration:

{
  "$schema": "./node_modules/hyperbranch/hyperbranch.schema.json",
  "provider": {
    "type": "planetscale-postgres",
    "organization": "your-planetscale-org",
    "database": "your-database",
    "branchPrefix": "hyperbranch",
    "parentBranch": "main",
    "migrationCommand": "npm run db:migrate"
  },
  "hyperdrive": {
    "binding": "DATABASE",
    "caching": false
  },
  "wrangler": {
    "config": "wrangler.jsonc"
  }
}

PlanetScale Postgres creates empty development branches. When migrationCommand is set, hyperbranch creates a short-lived branch-scoped admin role, exposes its connection as DATABASE_URL, runs the command, and deletes the role. HYPERBRANCH_BRANCH is also available to the command.

Add these secrets to Worker > Settings > Build > Environment variables:

CLOUDFLARE_ACCOUNT_ID
CLOUDFLARE_API_TOKEN
PLANETSCALE_SERVICE_TOKEN_ID
PLANETSCALE_SERVICE_TOKEN

The Cloudflare token needs Workers Scripts: Edit and Hyperdrive: Write.

The PlanetScale service token needs these database permissions:

read_branch
create_branch
delete_branch
create_branch_password
delete_branch_password

The last two permissions create and remove the temporary Postgres migration role. They retain the historical password wording in PlanetScale's permission model.

Workers Builds

Enable Preview Builds and set the Preview command to:

npx hyperbranch deploy

The command:

1. Creates or reuses the PlanetScale branch.
2. Waits until it is ready.
3. Runs the optional migration command.
4. Creates or reuses the managed PlanetScale Hyperdrive configuration.
5. Writes an ignored temporary Wrangler JSONC file containing the Preview binding.
6. Runs the project's pinned wrangler preview binary.
7. Removes the temporary file.

Production bindings are not modified.

Cleanup

Cleanup is explicit because Workers Builds does not currently document a branch-deletion command, and wrangler preview delete does not cascade into Hyperdrive or PlanetScale.

npx hyperbranch delete --name feature-branch

The command attempts all three operations, even if one fails:

1. Delete the Worker Preview.
2. Delete its Hyperdrive configuration.
3. Delete its PlanetScale branch.

A minimal GitHub workflow can invoke only this teardown when a pull request closes. Deployment remains entirely in Workers Builds.

name: Delete preview database

on:
  pull_request:
    types: [closed]

jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npx hyperbranch delete --name "$HEAD_REF"
        env:
          HEAD_REF: ${{ github.event.pull_request.head.ref }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          PLANETSCALE_SERVICE_TOKEN_ID: ${{ secrets.PLANETSCALE_SERVICE_TOKEN_ID }}
          PLANETSCALE_SERVICE_TOKEN: ${{ secrets.PLANETSCALE_SERVICE_TOKEN }}

Local use

Outside Workers Builds, the CLI falls back to the current Git branch:

npx hyperbranch deploy
npx hyperbranch delete

Override it explicitly with --name.

Current constraints

• PlanetScale Postgres only
• Wrangler JSON/JSONC only
• Hyperdrive currently limits configured databases to 10 on Free and 25 on Paid accounts
• No automatic cleanup event from Workers Builds
• Cloudflare and PlanetScale accounts must already be linked for managed credentials

Provider roadmap

Providers own only three operations:

interface DatabaseProvider {
  ensureBranch(name: string): Promise<DatabaseBranch>;
  migrate(name: string, command: string): Promise<void>;
  deleteBranch(name: string): Promise<void>;
}

Planned adapters:

• Neon branches
• Supabase branches
• PlanetScale Vitess/MySQL
• Generic Postgres schemas or databases

Development

npm install
npm run check
npm run build