Skip to content

forkstack

Instant, isolated development environments using zero-copy database and storage forks.

forkstack is a pattern for creating fully isolated development environments in seconds. Each developer gets their own copy of your entire stack—database, object storage, and local state—without duplicating data or slowing down.

Why forkstack?

Traditional development environments share databases or require expensive duplication:

Approach Problem
Shared dev DB Developers step on each other's data
DB per developer Expensive, slow to provision, hard to keep in sync
Local-only Can't test with production-like data

forkstack gives you the best of all worlds:

  • Instant creation - New environments in seconds, not minutes
  • Zero cost - Fork-on-write means no data duplication charges
  • Full isolation - Each environment has its own DB, storage, and state
  • Production parity - Fork from production to test with real data
  • Easy cleanup - Delete environments instantly when done

How It Works

forkstack uses three key technologies:

  1. Database branching - Services like Turso, Neon, or PlanetScale that support instant branches
  2. Storage forking - Tigris bucket forks (or bucket-per-environment)
  3. Environment utilities - Central code that routes all operations to the current environment
make envs-new alice
# Creates in ~5 seconds:
# - Database branch (alice)
# - Storage bucket fork (myapp-alice)
# - Local state directory (myapp.alice.db/)
# - Environment config (.current-env = alice)

make envs-switch alice
make up
# Your app now reads/writes to alice's isolated environment

Architecture Overview

.current-env file (git-ignored)
    ↓
get_current_env() reads file
    ↓
get_database_url() → {project}-{env}.turso.io
get_bucket_name()  → {project}-bucket-{env}
get_local_path()   → {project}.{env}.db/
    ↓
All app code uses these utilities
    ↓
Perfect isolation per environment

Quick Start

1. Choose Your Stack

forkstack works with any combination of:

Databases (pick one):

Object Storage (pick one):

  • Tigris - S3-compatible with bucket forks (recommended)
  • AWS S3 - Bucket-per-environment
  • Cloudflare R2 - Bucket-per-environment

2. Copy Templates

cp templates/env_utils.py your-project/app/
cp templates/Makefile.envs your-project/Makefile  # Or append to existing
cp templates/envs.py your-project/scripts/

3. Configure

Update the templates with your project name:

# env_utils.py
PROJECT_NAME = "your-project"

def get_bucket_name():
    env = get_current_env()
    return f"{PROJECT_NAME}-bucket-{env}"

4. Use It

# Create new environment
make envs-new alice

# Switch to it
make envs-switch alice
make down && make up

# Work in isolation
# ... make changes, test, etc ...

# Delete when done
make envs-delete alice

Pattern Benefits

For Individual Developers

  • Test risky changes in isolation
  • Work on multiple features simultaneously
  • Fork from prod to debug with real data
  • Clean up experiments instantly

For Teams

  • No database conflicts between developers
  • Easy code review with deployable branches
  • Staging environments on-demand
  • Safe production debugging

For Organizations

  • Ephemeral preview environments
  • Cost-effective testing at scale
  • Compliance-friendly data isolation
  • Simplified environment management

Next Steps

License

Apache 2.0 - Use it however you want.