A database for each lane
The API of myapp is about to keep data in Postgres. One Postgres container serves both lanes with a database for each, so a migration you try on the feature branch runs against that branch’s database and leaves the main branch’s alone.
One container serves every lane
Section titled “One container serves every lane”Postgres runs from a Compose file next to the project file. devlanes starts the containers a project lists under infra before anything else in a lane, and waits until their healthcheck passes.
services: postgres: image: postgres:17.6-alpine environment: POSTGRES_PASSWORD: postgres ports: ["127.0.0.1::5432"] volumes: [pgdata:/var/lib/postgresql/data] healthcheck: test: ["CMD-SHELL", "pg_isready -U postgres"] interval: 2s retries: 30
volumes: pgdata:The port mapping leaves the host port to Docker, and devlanes reads back the one Docker chose. The lanes share the container, so it keeps running while you stop them.
Each lane computes the name of its database
Section titled “Each lane computes the name of its database”You add these lines to the project file on the main branch. Under infra they name the Compose file and its project.
lanes: vars: db_name: myapp_${{ lane.name }}
infra: compose: docker-compose.yml project_name: myapp setup: database: | docker compose exec -T postgres psql -U postgres -v ON_ERROR_STOP=1 <<'SQL' SELECT 'CREATE DATABASE ${{ lane.db_name }}' WHERE NOT EXISTS (SELECT FROM pg_database WHERE datname = '${{ lane.db_name }}')\gexec SQL teardown: database: docker compose exec -T postgres dropdb -U postgres --if-exists --force ${{ lane.db_name }}
global_env: DATABASE_URL: postgres://postgres:postgres@127.0.0.1:${{ infra.postgres.port }}/${{ lane.db_name }}
tasks: migrate: run: docker compose exec -T postgres psql -U postgres -d ${{ lane.db_name }} -v ON_ERROR_STOP=1 -c "CREATE TABLE IF NOT EXISTS notes (id serial PRIMARY KEY, body text NOT NULL)" when: lane.startlanesWhich worktrees get a lane, how many ports each lane reserves, and values computed per lane (lane.<name>).
lanes.varsValues computed for each lane and read as ${{ lane.<name> }}, such as a database name, vhost, bucket or Redis index per lane. Build names from ${{ lane.name }}, which is main in lane 0 and lane<N> in lane N whatever the branch, and numbers from ${{ lane.index }}. A var named domain replaces the default lane domain, and one named port fixes where the lane's port block starts. ${{ domain('pages') }} gives a name a site of its own in each lane, such as pages2.localhost in lane 2. Cannot be combined with matrix.
lanes.vars.<name>Values computed for each lane and read as ${{ lane.<name> }}, such as a database name, vhost, bucket or Redis index per lane. Build names from ${{ lane.name }}, which is main in lane 0 and lane<N> in lane N whatever the branch, and numbers from ${{ lane.index }}. A var named domain replaces the default lane domain, and one named port fixes where the lane's port block starts. ${{ domain('pages') }} gives a name a site of its own in each lane, such as pages2.localhost in lane 2. Cannot be combined with matrix.
infraContainers the lanes depend on (databases, brokers, object stores), started and waited on before setup, tasks and services, plus the commands that create and remove each lane's data in them.
Config referenceinfra.composeCompose file, or a list of files merged like repeated -f, relative to the project. Its services are shared by every lane unless listed in per_lane; the shared project runs from the primary worktree with the .env next to the project file there as --env-file.
infra.project_nameName of the shared Compose project, fixed so docker compose -p <name> reaches the same containers outside devlanes. Defaults to the name Compose picks itself.
infra.setupNamed commands that prepare each lane's data, such as creating its database in a shared Postgres. They run once per lane after the containers are ready, all at the same time, and are recorded as done so later starts skip them; a failure stops the start unless the entry sets ignore_errors.
infra.setup.<name>Command that prepares (setup) or removes (teardown) a lane's data: a command string or list, or a mapping with run and options such as container, ignore_errors and timeout. Task steps can run it as infra.setup.<name> or infra.teardown.<name>.
infra.teardownNamed commands that remove a lane's data when the lane is cleaned (devlanes lane clean), one after another; never on stop. A failure is reported and the cleanup goes on.
infra.teardown.<name>Command that prepares (setup) or removes (teardown) a lane's data: a command string or list, or a mapping with run and options such as container, ignore_errors and timeout. Task steps can run it as infra.setup.<name> or infra.teardown.<name>.
global_envVariables for every service and task of the lane, above devlanes' own variables (PORT, DEVLANES_*) and below each unit's env and the profile's env. Use it for values many units share, such as a database URL built from ${{ infra.postgres.port }}. An entry without a value, such as one that reads a container a profile with infra: false left stopped, fails every service and task of the lane, so a value only some services need belongs in their env. devlanes exec leaves such an entry out and names it. Never set PORT here: it would replace every service's own port.
global_env.<name>Variables for every service and task of the lane, above devlanes' own variables (PORT, DEVLANES_*) and below each unit's env and the profile's env. Use it for values many units share, such as a database URL built from ${{ infra.postgres.port }}. An entry without a value, such as one that reads a container a profile with infra: false left stopped, fails every service and task of the lane, so a value only some services need belongs in their env. devlanes exec leaves such an entry out and names it. Never set PORT here: it would replace every service's own port.
tasksOne-shot commands such as installs, migrations and seeds, run by hand with devlanes run <name> or automatically at a lane event set with when. Tasks of the same event run in declaration order.
tasks.<name>A one-shot command, run by hand with devlanes run <name> or automatically at a lane event set with when. Anything that ends by itself belongs here, not in services, where an exit counts as a failure.
tasks.<name>.runCommand to run: a string runs through /bin/sh -c (pipes and multi-line scripts work), a list runs the program directly with those arguments. Use exactly one of run, run_script or steps. In a list, an item that is one ${{ }} expression giving a number or true/false becomes its text, such as --port followed by ${{ self.port }}.
tasks.<name>.whenLane event that runs this task automatically. Without it the task runs only by hand with devlanes run <name> or as a step of another task.
Each lane computes lane.db_name from its own name: myapp_main in lane 0 and myapp_lane1 in lane 1. global_env gives every service and task of the lane a database URL built from that name and the port Docker chose.
Setup creates the database once, the migration runs at each start
Section titled “Setup creates the database once, the migration runs at each start”Put a step in setup when it prepares data inside a container and a clean should undo it, such as a database, and make it a lane.create task when it prepares the worktree itself, such as its packages.
| Kind | For | Runs | Runs again | Undone by | In myapp |
|---|---|---|---|---|---|
| Setup entry | Data inside the containers | At the lane’s first start, after the containers | When its entry changes | Its teardown, at a clean | database |
lane. task | The worktree | At each start of a stopped lane until it succeeds | When its entry changes | Nothing | install |
lane. task | Work due at each start | At each start of a stopped lane | At every such start | Nothing | migrate |
Both lanes are stopped, and you merge main into the checkout branch. Then you start each lane.
$ devlanes start --no-ui$ devlanes start --no-uiEach start brings up Postgres if it is not running yet, runs the lane’s setup, which creates its database, then the migration, then the services; the install already succeeded in both lanes. A later start of a stopped lane skips setup and runs the migration again, so the migration is written to skip what already exists.
Each lane connects to its own database
Section titled “Each lane connects to its own database”$ devlanes env show apiThe API of lane 1 gets a DATABASE_URL ending in myapp_lane1; the API of lane 0 gets myapp_main in the same container.
A stopped lane keeps its database. devlanes lane clean deletes a lane and runs its teardown, so cleaning lane 1 drops myapp_lane1 while lane 0 keeps myapp_main.
Both lanes keep running, each on its own database, so when the API breaks on the feature branch in When a service fails, the main branch goes on as it was.