GitHub - elitan/velo: Postgres with instant branching

npm install -g @elitan/velo

# Create project with PostgreSQL 17 (auto-creates demo/main branch)
$ velo project create demo

Creating project demo...
  ▸ Detect ZFS pool                         0.0s
  ▸ Validate permissions                    0.0s
  ▸ Create dataset demo-main                0.0s
  ▸ Mount dataset                           0.0s
  ▸ PostgreSQL ready                        6.2s

Connection ready:
  postgresql://postgres:***@localhost:32835/postgres

# Add data to main branch
$ psql -h localhost -p 32835 -U postgres << EOF
CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT);
INSERT INTO users (name) VALUES ('Alice'), ('Bob'), ('Charlie');
SELECT * FROM users;
EOF

 id |  name
----+---------
  1 | Alice
  2 | Bob
  3 | Charlie
(3 rows)

# Create branch in 0.1s (copies entire database via ZFS snapshot)
$ velo branch create demo/dev

Creating demo/dev from demo/main...
  ▸ Checkpoint                              0.1s
  ▸ Snapshot 2025-10-09T18-40-21            0.0s
  ▸ Clone dataset                           0.0s
  ▸ Mount dataset                           0.0s
  ▸ PostgreSQL ready                        6.3s

Connection ready:
  postgresql://postgres:***@localhost:32836/postgres

# Check status - two isolated databases running
$ velo status

Velo Status

ZFS Pool
┌──────┬────────┬─────────┬─────────────────┬─────────┐
│ Pool │ Health │ Size    │ Used            │ Free    │
├──────┼────────┼─────────┼─────────────────┼─────────┤
│ tank │ ONLINE │ 9.50 GB │ 22.41 MB (0.2%) │ 9.48 GB │
└──────┴────────┴─────────┴─────────────────┴─────────┘

Projects (1)
┌───┬───────────────┬───────────────┬────────────────────┬───────────┬─────────────────────┐
│   │ Name          │ Type          │ Image              │ Branches  │ Created             │
├───┼───────────────┼───────────────┼────────────────────┼───────────┼─────────────────────┤
│ ● │ demo          │ project       │ postgres:17-alpine │ 2         │ 2025-10-09 18:40:21 │
├───┼───────────────┼───────────────┼────────────────────┼───────────┼─────────────────────┤
│ ● │   ↳ demo/main │ running | 13s │ Port 32835         │ 9.25 MB   │ 2025-10-09 18:40:21 │
├───┼───────────────┼───────────────┼────────────────────┼───────────┼─────────────────────┤
│ ● │   ↳ demo/dev  │ running | 6s  │ Port 32836         │ 127.50 KB │ 2025-10-09 18:40:28 │
└───┴───────────────┴───────────────┴────────────────────┴───────────┴─────────────────────┘

# Make changes in dev branch
$ psql -h localhost -p 32836 -U postgres << EOF
INSERT INTO users (name) VALUES ('Dave'), ('Eve');
DELETE FROM users WHERE name = 'Bob';
SELECT * FROM users;
EOF

 id |  name
----+---------
  1 | Alice
  3 | Charlie
  4 | Dave
  5 | Eve
(4 rows)

# Compare both branches - complete isolation
$ psql -h localhost -p 32835 -U postgres -c "SELECT * FROM users;"  # Main
$ psql -h localhost -p 32836 -U postgres -c "SELECT * FROM users;"  # Dev

--- Main branch (Port 32835) ---
 id |  name
----+---------
  1 | Alice
  2 | Bob      ← Still here
  3 | Charlie
(3 rows)

--- Dev branch (Port 32836) ---
 id |  name
----+---------
  1 | Alice
  3 | Charlie  ← Bob deleted
  4 | Dave     ← New rows
  5 | Eve
(4 rows)

# Reset dev back to main's current state
$ velo branch reset demo/dev

Resetting demo/dev to demo/main...
  ▸ Stop container                          0.2s
  ▸ Checkpoint demo/main                    0.1s
  ▸ Create snapshot                         0.0s
  ▸ Destroy old dataset                     0.1s
  ▸ Clone new snapshot                      0.0s
  ▸ Mount dataset                           0.0s
  ▸ Start container                         6.2s
  ▸ PostgreSQL ready                        0.0s

# Dev now matches main (Bob is back, Dave/Eve gone)
$ psql -h localhost -p 32836 -U postgres -c "SELECT * FROM users;"

 id |  name
----+---------
  1 | Alice
  2 | Bob      ← Back from main
  3 | Charlie
(3 rows)

sudo apt install zfsutils-linux
curl -fsSL https://get.docker.com | sh
curl -fsSL https://bun.sh/install | bash

npm install -g @elitan/velo

git clone https://github.com/elitan/velo.git && cd velo
bun install && bun run build
sudo cp dist/velo /usr/local/bin/

# 1. Create ZFS pool (if you don't have one)
zpool list  # Check existing pools
# For testing: sudo truncate -s 10G /tmp/zfs-pool.img && sudo zpool create tank /tmp/zfs-pool.img
# For production: sudo zpool create tank /dev/sdb

# 2. Run velo setup (grants permissions, configures Docker)
sudo velo setup

# 3. Log out and log back in (required for group membership to take effect)

# 4. Verify setup and start using Velo:
velo doctor              # Check if everything is configured correctly
velo project create myapp