Skip to content

Use cases

Database per branch, no shared state

Two worktrees. Same myapp_dev database. One runs a migration, the other’s schema breaks. Treeline can give every worktree its own database — cloned from a template in seconds, seeded from hooks, or copied as a SQLite file. Database isolation is opt-in: omit the database block entirely if your project doesn’t need it.

Option A: Clone from a template (PostgreSQL)

PostgreSQL’s createdb --template copies the full schema and data from an existing database without running migrations or seeds. If your template database is ready to go, a new worktree gets a complete database in seconds — even if your seed file takes 20 minutes.

Keep the template schema current with gtl db template update, or enable database.sync_on_create. Treeline fetches the remote merge target and runs your migration command in a temporary detached checkout, targeting the root template. Existing checkout branches and worktree databases stay unchanged. Requires Git 2.29+, a primary database env mapping, and a migration command that prepares its dependencies. See template update requirements.

.treeline.yml
project: myapp

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

env:
  PORT: "{port}"
  DATABASE_URL: "postgresql://localhost:5432/{database}"
what happens

$ gtl new feature-auth

Creating worktree feature-auth

Allocated port 3012

Cloned database myapp_development_feature_auth

Wrote .env.local

==> https://myapp-feature-auth.prt.dev

The {database} token in the env block resolves to the cloned database name. The name field controls the naming: myapp_development_feature_auth in this example. Cloning reads from the template; template updates and commands run against the main worktree can modify it.

Managing worktree databases

# Print the worktree’s database name

$ gtl db name

myapp_development_feature_auth

# Drop and re-clone from the template

$ gtl db reset

# Clone from a different source instead

$ gtl db reset --from staging_snapshot

# Restore from a pg_dump file (auto-detects format)

$ gtl db restore dump.sql

# Clean up when done

$ gtl release --drop-db

Option B: Seed with setup commands (no template)

If your team prefers running migrations + seeds on every new worktree instead of maintaining a template, skip the database block and use commands.setup to create the database from scratch.

.treeline.yml
project: myapp

env:
  PORT: "{port}"
  DATABASE_URL: "postgresql://localhost/myapp_dev_{worktree}"

commands:
  setup:
    - bin/rails db:create
    - bin/rails db:schema:load
    - bin/rails db:seed

This approach trades setup speed for simplicity — no template to maintain, every worktree starts from the current schema. If your seed file is slow (10+ minutes), consider Option A instead. If it’s fast or you’re using a framework like Prisma that handles migrations differently, this may be all you need.

You can also combine the two: clone from a template for the schema, then run lightweight data patches in commands.setup.

Option C: SQLite (file copy)

SQLite databases are files. Treeline clones by copying the file to the worktree directory. No server, no createdb.

.treeline.yml
project: myapp

database:
  adapter: sqlite
  template: db/development.sqlite3

Option D: Auxiliary databases (database.extra)

Some apps need more than one database per worktree, such as a primary Postgres database and a separate queue database. database.extra allocates names for these auxiliary databases. Each named entry is a string pattern; your framework or commands.setup creates the databases.

.treeline.yml
project: myapp

database:
  adapter: postgresql
  template: myapp_development

  extra:
    queue: "{database.name}_queue"

env:
  DATABASE_URL: "postgresql://localhost/{database}"
  QUEUE_DATABASE_URL: "postgresql://localhost/{database.extra.queue}"

Treeline clones only the primary database and tracks the auxiliary names for cleanup. Reference extra databases in env using the dotted token {database.extra.queue} — replace queue with the key name. All extra databases are released with gtl release --drop-db. Auxiliary databases use the project's database adapter and connection settings.

Port-dependent data

If your database stores URLs that include the port — OAuth redirect URIs, webhook endpoints, asset URLs — the cloned data will have stale values pointing to the template’s port. Use commands.setup to patch them after cloning:

.treeline.yml
commands:
  setup:
    - psql $DATABASE_URL -c "UPDATE settings SET base_url = 'http://localhost:$PORT'"

Setup commands run after the env file is written, so $PORT and $DATABASE_URL are already available.

When to use which

Approach Speed Best when
Clone from template Seconds Seed is slow, team maintains a clean template database
Seed with setup commands Varies Seed is fast, or team uses migrations (Prisma, Knex) instead of templates
SQLite file copy Instant App uses SQLite — no server needed
No database config — App doesn’t use a local database, or databases are managed externally

Read next

All use cases