Skip to content

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.

Verified against CLI v0.58.3.

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.name (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.name defaults to {template}_{worktree}. Tokens: {template}, {worktree} (sanitized directory name), {project}.

.treeline.yml
database:
  adapter: postgresql
  template: myapp_development
  name: "{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 current allocation's database after confirmation. In the main worktree, that is the template itself. The drop, reset, and restore prompts identify the target; check its database name, host, port, and user before confirming.

$ 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.

Updating the template

gtl db template update fetches merge_target from origin and runs commands.migrate in a temporary detached checkout. If no merge target is configured, Treeline uses origin/HEAD when available, otherwise main. Git 2.29+ is required. Existing checkout branches and worktree databases stay unchanged.

Map the variable your migration command reads to {database}, {database.name}, or {database_1} in env. For this operation, those tokens resolve to the root template. For example:

.treeline.yml
database:
  template: myapp_development
  sync_on_create: true
commands:
  migrate: bundle install && bin/rails db:migrate
env:
  DATABASE_URL: "postgresql://localhost/{database}"

Configured copy_files and the root repo's env seed prepare the checkout. Normal setup commands and hooks do not run. Dependencies must already be available or be prepared by commands.migrate. Unbound DATABASE_URL values in common dotenv files and auxiliary database URLs without explicit migration targets are rejected; a shadow database must be separate from the template.

Enable database.sync_on_create to refresh before fresh clones. Without a primary database env mapping, automatic sync warns and uses the existing template; manual updates and --strict setup fail. To update an existing worktree database afterward, run gtl db reset there, replacing its data with a fresh clone.

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

See also