Share one database server between lanes
Use this when every lane needs a database and one server is enough: one Postgres runs for the whole project, and each lane gets a database of its own in it.
::example{slug="infra-postgres-shared"}
Add the server to a Compose file
Section titled “Add the server to a Compose file”Leave the host port to Docker; devlanes reads it back. The healthcheck lets devlanes wait until Postgres accepts connections.
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:Create a database per lane
Section titled “Create a database per lane”Every Compose service is shared by the lanes unless you list it under infra.per_lane. The lane variable names the database, setup creates it on the lane’s first start, and teardown drops it when you clean the lane.
lanes: vars: db_name: myapp_${{ lane.name }}
infra: compose: docker-compose.yml project_name: ${{ project.name }} 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 }}lanesWhich 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.
Lane 0 gets myapp_main and lane 1 myapp_lane1. To migrate at each start, add a task as in Run installs, migrations and seeds.
Start the lanes
Section titled “Start the lanes”Run the start in each worktree. The first one brings Postgres up, and each lane creates its own database.
$ devlanes startIf you stop or replace the container
Section titled “If you stop or replace the container”Stopping lanes leaves Postgres running. To stop it, or to bring it back after you removed it, for example to use a newly pulled image:
$ devlanes infra down --yes$ devlanes infra upDocker gives the container a new port when it comes back, so run a reload in each running lane to give its services the new address:
$ devlanes reloadIf each lane needs its own server
Section titled “If each lane needs its own server”Give each lane a container of its own: Give each lane its own container.