Speeding up per-worktree infrastructure initialization
With agents speeding up every aspect of software delivery, new bottlenecks are always popping up. The latest one for me has been worktree initialization. With multiple agents running in parallel, beyond requiring their own checked out codebase, they also require dedicated infrastructure so that test data isn’t muddied, ports don’t conflict, etc. That was solved using dedicated infrastructure in Docker for each worktree, and then the next problem became initializing that infrastructure.
Let’s take the database for instance. I have 584 migrations there and running them takes about 3 minutes, so every git worktree add ... takes at least three minutes, which is unbearable to me. To deal with this specific problem, I introduced the idea of a template database, which on a new worktree is copied instead of the migrations run again on the worktree.
The main idea is to use the CREATE DATABASE ... TEMPLATE command, which creates a database as a file-level copy of another: CREATE DATABASE tm_foo TEMPLATE ticketmaester_template;
This way you run the 584 migrations once into a pristine template DB which no process connects to. The copy takes about 0.2s. Isolation is by database name inside the existing two containers, so no new ports or containers need to be fired up per worktree.
The template has to be up to date so all worktrees get the latest schema. So the template only tracks main, never a feature branch. Any migration on the template is run from the main worktree’s checkout.
So there are two layers:
template = main's schemaworktree DB = copy of template + this branch's own migrations
After the copy, the worktree runs a normal mix ecto.migrate from its own checkout, which picks up whatever migrations that branch has added. When the branch merges, its migrations reach main and the template picks them up the next time a worktree gets created.
So an out-of-date template is harmless. Since every worktree migrates after the copy, any migrations the template is missing run then.
To ensure the template is always up to date, every time it’s built I stamp it with a hash of all the migration files on main. When a new worktree is created, the script recomputes the hash and compares:
- Hashes match: copy right away.
- New migrations on main: run just those on the template, re-stamp, then copy.
- An existing migration was edited: rebuild the template from scratch.
All of this runs from a post-checkout git hook, so git worktree add is the only command anyone (human or agent) has to run. On the first checkout in a new worktree, the hook:
- Copies
.envand.env.testfrom the main worktree. - Clones
deps,_buildandnode_modulesfrom the main worktree using copy-on-write (cp -con macOS), so nothing is downloaded or recompiled from scratch (another huge time saver as you avoidnpm i). - Creates the worktree’s dev and test databases from the templates.
- Rewrites the database names in the copied
.envfiles to point at them.
The database name is derived from the worktree’s path, something like tm_rapid_river_3f9a2b1c: the folder name plus a short hash of the full path. After copying the env files, the script rewrites DB_NAME (and the other database keys my app uses) in .env and .env.test to that name. Since the app already reads its database config from the environment, nothing in the code had to change. The worktree just boots against its own database.
A single setup.sh --destroy drops both databases and removes the worktree.
In summary, creating a worktree went from three minutes of migrations to a copy that runs in under a second, with each agent getting its own data to work with with no fear of collissions.
The pattern works on most slow setup steps. Do the expensive work once, keep the result somewhere it can be copied cheaply. I’ve since used the same trick to give each CI test partition its own database. All three scripts are in this gist if you want to adapt them.