Docs / Database

Database management

Git Treeline can clone a template database for each worktree so branches stay isolated. This page covers naming, PostgreSQL and SQLite behavior, the gtl db commands, and cleanup.

How database allocation works

Database cloning runs only when database.template is set in .treeline.yml. The main repository worktree uses the template database itself (no derived name). Additional worktrees get a new database whose name is built from database.pattern (default {template}_{worktree}), so names look like myapp_development_feature_auth.

If the registry already has an allocation for this worktree path, that allocation is reused and the clone step is skipped. Setup still runs commands.setup and refreshes env files.

Configuration

database.adapter is postgresql by default; set sqlite for file-based databases.

database.template is required for cloning: a PostgreSQL database name to pass to createdb --template, or a path to the SQLite file to copy (resolved relative to the main repo for worktrees).

database.pattern defaults to {template}_{worktree}. Tokens: {template}, {worktree} (sanitized directory name), {project}.

.treeline.yml

database:
  adapter: postgresql
  template: myapp_development
  pattern: "{template}_{worktree}"

`gtl db` commands

gtl db name prints the allocated database name for the current worktree. Add --json for structured output.

$ gtl db name

gtl db reset drops the worktree database and re-clones from database.template. Use --from <name> to clone from a different source.

$ gtl db reset

$ gtl db reset --from myapp_staging

gtl db restore <dumpfile> drops the database, recreates it, and loads a dump. Format is detected (custom pg_dump or plain SQL).

$ gtl db restore ./backup.dump

gtl db drop removes the worktree database only (it does not delete the template).

$ gtl db drop

PostgreSQL workflow

Maintain a template database with schema and seed data. Point database.template at it. On gtl new or gtl setup, Treeline clones it for the worktree. Run migrations and further setup in commands.setup. Use gtl db reset when you need a clean copy from the template.

SQLite workflow

Set database.adapter: sqlite and database.template to the path of a SQLite file in the main repo. Treeline copies that file into each worktree; paths differ from PostgreSQL (per-worktree file under the worktree directory). Use gtl db reset to re-copy from the template file.

Port-dependent data

If rows in the database store URLs with embedded ports (OAuth redirects, webhooks), those values must be updated when the allocated port changes. Run fixups from commands.setup with $PORT in the environment. See the Hooks guide for the full pattern.

Cleanup

gtl release --drop-db frees the worktree allocation and drops the cloned database. gtl prune --drop-db can drop databases for merged or stale worktrees depending on the flags you pass.

$ gtl release --drop-db

$ gtl prune --drop-db