Switching stacks

dqx switch ddev      # or docker, lerd, herd

The project's repository does not notice. What changes is what dqx generates and where it runs commands; what the project declares stays the declaration.

What actually happens

1. It asks whether the target can do the job. A project serving several sites from one checkout cannot run on a backend that registers one directory as one project, and dqx refuses with the reason rather than producing something half-working.
2. The old backend's files stop being generated and the new backend's are written.
3. The application's .env is rewired. This is the part that used to break quietly: a .env pointing at db is right on compose and resolves nowhere on a backend that has no such host, and the symptom is a 500 deep inside the application rather than anything about configuration.
4. Leftovers are reported, not silently deleted. A .ddev/ directory belonging to the backend you just left is yours to remove.

Before you switch

dqx doctor

Fix what it reports first. Switching a project that is already unhappy makes it hard to tell which problem is which.

Take a snapshot if the database matters:

dqx snapshot

Backends do not share databases. A switch leaves the old one behind on the old backend, and dqx restore is how it gets to the new one.

What each switch costs

to	you gain	you pay
docker	complete isolation, several sites per project, the same behaviour everywhere	bind-mount file speed on macOS, and Docker Desktop's memory
ddev	much faster file access	one registration per directory, and its own sync to keep healthy
lerd	no virtual machine on Linux	the smallest community of the four when something is strange
herd	native speed	the host's PHP for every project, and Pro for databases and mail

Ports: why only one backend runs at a time

Ports 80 and 443 have one owner per machine, and every backend wants them. That makes them the reason you cannot have a DDEV project and a docker project serving at the same moment — not a limitation of dqx, but of the ports.

dqx kill --dry-run     # what would stop, and nothing else
dqx kill               # frees 80 and 443, whichever backend held them
dqx kill --all         # that, and the runtimes too, giving their memory back

Moving between two projects on different backends is therefore dqx kill in one and dqx up in the other. Within one backend nothing needs freeing: docker's shared router serves every project at once.

Switching back

The same command. Nothing about the declaration changed, so there is nothing to undo — which is the point of keeping the description separate from the thing that runs it.