Cada worktree tiene su propia base de datos

Ahora hago casi todo mi trabajo en worktrees de git. Tanto el desarrollo con agentes como el desarrollo normal de funciones los hago en un worktree, para que lo que esté haciendo quede aislado del resto de frentes. Me gusta este flujo porque puedo estar con algo, dejarlo y ponerme con otra cosa sin pisar lo que tengo abierto en la habitación de al lado.

Quién iba a decir que los worktrees (una función que llevo una década ignorando en git help) acabarían siendo la tecnología estrella de 2026.

Si no sabes qué son los worktrees, puedes leerlo aquí.

Hay un problema. Los worktrees clonan tu código. No clonan nada que no esté en git, y hay dos cosas así que necesitas: tus archivos ignorados y una base de datos. Así que cada worktree que creas se conecta, tan contento, al mismo Postgres local. En cuanto una rama ejecuta una migración, cambia el esquema del que dependen las otras tres, y adiós a mi aislamiento perfecto.

Así que escribí una pequeña herramienta para arreglarlo: wtdb.

Mi configuración es así:

main-repo/: siempre siguiendo origin/main, con las migraciones ejecutadas tras cada pull. La copia limpia de referencia.
main-repo-worktree-feat-blah-blah/: un worktree de una rama de función con su propia base de datos, más la caché y los node_modules copiados del repo principal.
main-repo-worktree-feat-foo-bar/: otro worktree de una rama de función con su propia base de datos, más la caché y los node_modules copiados del repo principal.

Cuando añado un worktree, wtdb se engancha al post-checkout de git y hace las tres tareas aburridas que nadie configura a mano:

Clona la base de datos. Usa CREATE DATABASE ... TEMPLATE de Postgres, así que es una copia casi instantánea de tus datos de desarrollo, no un volcado y restauración durante los que te da tiempo a hacer un café.
Copia tu archivo env y reescribe la URL de la base de datos para que apunte a la copia nueva.
Copia los archivos ignorados que de verdad necesitas. Es decir, node_modules y compañía, con clones copy-on-write, así que no gastan espacio en disco.

Ahora puedo lanzar un servidor de desarrollo contra cualquier worktree y dejar que un agente ejecute las migraciones y los cambios de esquema que le apetezcan en su propio entorno aislado.

Empezar son una instalación y tres comandos:

# Always check the source code of a new tool before installing it.
# I know this is a bad practice. I will make this available on homebrew soon. Maybe.
curl -fsSL https://raw.githubusercontent.com/willhackett/wtdb/main/install.sh | sh

wtdb init      # writes a starter .wtdb.json
wtdb install   # installs the post-checkout hook
wtdb sync      # provision the current worktree by hand

La configuración es mínima. Es un archivo .wtdb.json en la raíz de tu repo.

{
  "envFile": ".dev.vars",
  "dbEnvVar": "DATABASE_URL",
  "pathsToCopy": ["node_modules", ".next"]
}

pathsToCopy es todo lo ignorado que tu worktree necesita para funcionar. .next aquí da por hecho que usas Next.js, cámbialo por tu propia caché de compilación.

También hay wtdb status para ver qué worktree es dueño de qué base de datos, y wtdb prune para borrar las huérfanas cuando eliminas un worktree. Me gustaría que git añadiera algún tipo de hooks para worktrees y así no necesitar wtdb prune.

Ahora mismo solo hay un adaptador de Postgres, porque es lo que uso. La capa de base de datos es una interfaz sencilla (Copy y Drop), así que si usas otra cosa, añadir un adaptador lleva unos minutos. Los PR son bienvenidos.

Github: willhackett/wtdb.