Skip to main content

​
Database Branches

Each isolated session can get its own branched PostgreSQL 16 container, built from a base image of your real database. Agents run migrations, mutate rows, and generally break things — against a disposable copy that is deleted when the session closes. Session isolation itself is covered in Security & Isolation.
PostgreSQL only for now — MySQL and other engines are not supported.

​
Requirements

  • Docker running locally
  • A PostgreSQL 16 engine
  • No port planning by hand — branch containers bind to 127.0.0.1 on an auto-assigned port

​
Building a base image

In Project Settings → Database:
  1. Enable database isolation
  2. Provide the connection string to your real database
  3. Choose a snapshot method
The build flow: Tempest spins up a staging container, runs initdb, imports the snapshot, prewarms with ANALYZE and CHECKPOINT, writes a tuned postgresql.auto.conf (fsync=off, wal_level=minimal, shared_buffers=256MB), and commits the result as an image named tempest-db-base-<project>-<uuid>.
The tuning trades durability for speed (fsync=off) on purpose — branches are disposable, so there is nothing worth crash-recovering.

​
Branching per session

When an isolated session starts, Tempest branches the base image into a container named tempest-<branch>. The host port is auto-assigned in the range 15432–65000 and bound to 127.0.0.1. Readiness is confirmed with pg_isready before anything proceeds.

​
Env delivery

The branch is wired into the session automatically: DATABASE_URL plus PGHOST, PGPORT, PGUSER, and PGDATABASE are written into the session’s live shell before the agent starts.

​
Lifecycle

  • The branch container is deleted when the session closes.
  • An orphan sweep runs on app startup and reaps anything left behind.
  • The registry of images and branches lives at ~/.tempest/dbiso.db.

​
The DB Clones panel

The right sidebar’s bottom tabs include a DB Clones panel listing the active clones with their name, port, and creation time.

​
Tauri commands

The Rust backend exposes: db_check_docker, db_check_ready, db_build, db_list_branches, db_sweep_orphans.