Running a database migration safely means proving the service still works before and after the change. With Claude Code, you can orchestrate the whole flow: spin up the container, run unit tests, plan the migration, and verify everything end to end without leaving the terminal.

How do you start the backend service locally before migrating?

Before touching any migration, you need the service alive. Inside the backend folder, the Makefile already ships the commands you need to build, start and inspect the container.

• make build downloads every package required by the service and builds the Docker image.
• make start boots the API container so it can receive requests.
• make logs confirms the service started correctly and surfaces runtime errors.

Once the container is up, open localhost:8000 in the browser. If you see an API response, the service is healthy and ready for the next step.

How do I know the API is running? Check make logs for a clean startup, then hit localhost:8000. A JSON response from the API confirms the container is serving traffic.

How do you add a test command to the Makefile with Claude Code?

The original Makefile had no command to run Pytest inside the container. Instead of writing it manually, you can hand the file to Claude Code as context and ask it to add a new test target that executes Pytest inside the API container.

Claude Code reads the existing patterns, proposes a new test command, and once you approve it, the command lands in the Makefile. From a fresh terminal session inside backend, make test triggers the full test suite.

If the tests fail on the first run, the usual culprits are missing dependencies. In this case, httpx and pytest-asyncio had to be added as optional dependencies and rebuilt with uv so the suite could execute.

How do you plan a migration safely with Claude Code plan mode?

With the service green, the next move is the database phase of the implementation plan. The trick is to reference the spec file (01-backend) from the correct working directory. If you are inside backend, Claude Code will not find a spec located one level up, so step out before invoking it.

A useful shortcut is Bash mode, activated by typing ! inside Claude Code. It lets you run shell commands that Claude keeps as execution context. When permissions block a directory change, the cleanest fix is to exit Claude Code, move manually, and start the session again.

What execution modes does Claude Code offer?

Switching modes with Shift+Tab changes how aggressively Claude acts on your behalf.

• Auto-accept mode: every edit and command is approved by default.
• Plan mode: Claude designs the full plan before executing anything.
• Default mode: Claude asks for confirmation before each step.

For a migration, plan mode is the safest choice. Claude inspects the running containers, identifies the current Alembic revision, recognizes the migration pattern, and outputs a concrete plan: create the new migration file, run it with the make command, and verify the result in Postgres.

What is plan mode in Claude Code? It is an execution mode where Claude analyzes the repo, gathers context, and presents a step by step plan without applying changes until you approve it.

How does Claude Code execute and verify the database migration?

Once you accept the plan, Claude Code runs each step. The first time it triggers a docker compose command it asks for permission. You can grant it once for the folder so it stops asking for that specific tool.

The migration created the course_rating table in Postgres with the constraints and indexes defined in the spec, ran the Alembic migration through the make command, and validated the schema directly in the database.

To close the loop on the implementation plan, select the relevant block in your editor and use Command+Option+K to send those exact lines as context to Claude Code. Ask it to mark the finished tasks as completed, and the checklist updates itself.

How do you confirm the service still works after the migration?

Running make test again is the baseline check, but Claude Code suggested going further by hitting the health endpoint and other main endpoints with curl. Allowing it to run curl and python3 gives you a lightweight integration test on top of the unit tests.

The final report from Claude Code covered three signals:

• Unit tests passing inside the API container.
• Container status active and serving requests.
• Main endpoints responding with the expected payloads.

With those three green checks, phase one of the backend plan is officially done and certified by Claude Code itself. The next challenge is phase two: building the SQLAlchemy models with the same workflow. Drop your approach and the blockers you hit in the comments.