# Add Database Migrations to a Slim 4 App

Yes. An agent adds Phinx migrations and a seed to a Slim 4 app, swaps the in-memory user repository for a PDO one behind the same interface, tests it and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-database-migrations/slim/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the app wires its container before touching persistence, because the whole point is to keep the domain interface and swap what stands behind it. In an app laid out like slimphp/Slim-Skeleton, `composer.json` requires `slim/slim` `^4.12`, `slim/psr7` `^1.6`, `php-di/php-di` `^6.4` and `monolog/monolog` `^2.9` on `php` `^7.4 || ^8.0`, with `phpunit/phpunit` `^9.6.17`, `phpstan/phpstan` `^1.10` and `squizlabs/php_codesniffer` `^3.9` in `require-dev`, and scripts `start` (`php -S localhost:8080 -t public`) and `test` (`phpunit`). `public/index.php` builds a PHP-DI container from `app/settings.php`, `app/dependencies.php` and `app/repositories.php`, and `app/repositories.php` is one line of substance: it autowires `App\Domain\User\UserRepository` to `InMemoryUserRepository`. That class in `src/Infrastructure/Persistence/User/` holds five hard-coded `User` objects keyed by id and implements the two methods the interface in `src/Domain/User/UserRepository.php` declares, `findAll()` and `findUserOfId(int $id)`, throwing `UserNotFoundException` for a missing id. `User` itself has a nullable `id`, `username`, `firstName` and `lastName`, lowercases the username and capitalises the names in its constructor, and serialises to JSON. `app/routes.php` exposes `GET /users` and `GET /users/{id}` through `ListUsersAction` and `ViewUserAction`. There is no database, no PDO service and no `db` setting anywhere.

Phinx is the migration tool the agent adds, and its current release requires PHP `8.1` or later, `cakephp/database` and `symfony/console`. That collides with the `^7.4 || ^8.0` floor and with the `tests.yml` matrix, which runs PHP `7.4`, `8.0`, `8.1` and `8.2` and runs `phpcs` and `phpstan` on `8.1`. The agent raises `php` to `^8.1` in `composer.json`, drops `7.4` and `8.0` from the matrix, and says in the pull request that both are past their end of life and that a team that must keep them can pin an older Phinx instead. It then adds `robmorgan/phinx` to `require`, a `phinx.php` at the root with `development`, `testing` and `production` environments read from `DB_ADAPTER`, `DB_NAME`, `DB_HOST`, `DB_USER` and `DB_PASS`, SQLite under `var/` as the default so `composer start` works with nothing installed, and `db/migrations` and `db/seeds` as the paths.

The first migration, `db/migrations/<timestamp>_create_users_table.php`, creates `users` with an auto-increment `id`, `username` as a unique string, `first_name` and `last_name`, and timestamps, matching the four fields `User` carries. `db/seeds/UserSeeder.php` inserts the same five people `InMemoryUserRepository` hard-codes, so `GET /users` returns what it returned before. `src/Infrastructure/Persistence/User/PdoUserRepository.php` implements `UserRepository` over a `PDO` instance with prepared statements, maps rows to `User` and throws `UserNotFoundException` the way the in-memory class does. `app/settings.php` gains a `db` block, `app/dependencies.php` a `PDO::class` definition built from it with `ERRMODE_EXCEPTION`, and `app/repositories.php` points the interface at the new class; the in-memory class stays in the tree for tests that want it. `composer.json` gets `migrate` and `seed` scripts that call `vendor/bin/phinx`, and `.gitignore` gets the SQLite file under `var/`.

The existing action tests under `tests/Application/Actions/User` replace the repository through the container with a Prophecy double, so they keep passing untouched. The agent adds `tests/Infrastructure/Persistence/User/PdoUserRepositoryTest.php`, which opens an in-memory SQLite `PDO`, runs the migration through Phinx's `TextWrapper` against the `testing` environment, inserts two rows and asserts `findAll()` and `findUserOfId()` return `User` objects with the capitalised names and that a missing id throws. It runs `vendor/bin/phpunit`, `vendor/bin/phpstan` at the level `phpstan.neon.dist` sets and `vendor/bin/phpcs` in its sandbox, then `composer migrate`, `composer seed`, `composer start` and `curl localhost:8080/users` to show the seeded list, with `phinx status` printed once before and once after the migration.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add database migrations to this Slim 4 app with Phinx and move users out of memory. Read composer.json, public/index.php, app/settings.php, app/dependencies.php, app/repositories.php, app/routes.php, src/Domain/User and src/Infrastructure/Persistence/User, tests/TestCase.php, the action tests, phpunit.xml, phpstan.neon.dist, phpcs.xml, .gitignore, docker-compose.yml and .github/workflows/tests.yml first. Phinx needs PHP 8.1, so raise the composer php floor, trim the CI matrix and explain why. Add phinx.php with development, testing and production environments from environment variables and SQLite under var as the default, a users migration matching the User entity, a seeder with the five existing users, a PdoUserRepository behind the existing interface, a PDO definition in dependencies, a db block in settings, migrate and seed composer scripts, and the SQLite file in .gitignore. Keep the in-memory repository in the tree. Add a repository test that migrates an in-memory SQLite database through Phinx's TextWrapper. Run phpunit, phpstan, phpcs, the migration, the seed and a curl of /users, and open a pull request with the output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request adds `phinx.php`, `db/migrations/<timestamp>_create_users_table.php`, `db/seeds/UserSeeder.php`, `src/Infrastructure/Persistence/User/PdoUserRepository.php` and `tests/Infrastructure/Persistence/User/PdoUserRepositoryTest.php`, and changes `composer.json`, `composer.lock`, `app/settings.php`, `app/dependencies.php`, `app/repositories.php`, `.gitignore` and `.github/workflows/tests.yml`. Its description pastes `phinx status` before and after `composer migrate`, the `phpunit`, `phpstan` and `phpcs` results, and the `curl localhost:8080/users` body showing the five seeded users.

The `Tests` workflow runs on the trimmed matrix on the pull request, so the reviewer sees the suite and the static analysis pass on PHP 8.1 and 8.2. The run's record keeps every command, including the migration against the SQLite file and the test's migration against an in-memory database, so a reviewer can tell the two apart.

Before merging, a reviewer chooses the production adapter and credentials for `phinx.php`, decides whether migrations run from a deploy step or by hand, and whether the Docker Compose service should gain a database container. The actions, routes and the `User` entity are unchanged.

## Run it on every Slim service still reading from memory

A team with several Slim services starts one run per repository from its own server: a `POST /o/{org}/sessions` each, with the repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own `app/repositories.php`, so a service that already uses PDO gets Phinx added around its existing schema with a baseline migration, and one on Doctrine gets the migrations proposed through Doctrine's own tool instead.

After that, a Linear issue labelled `schema` in the Project can start a run through an automation with a `linear` trigger and the prompt "write the Phinx migration this issue describes, update the repository and its test, run phpunit and open a pull request"; the trigger adds the issue after the prompt, and the run reads it through the Linear connection. Each schema change then arrives as a reviewable migration rather than a hand-run script.

## Why run it on Rush?

Moving a skeleton off its in-memory repository is a cross-cutting change: a migration tool with a PHP floor the project does not meet, a container definition that has to exist before the repository does, and a test suite that mocks the interface and must keep passing. The agent reads the real container wiring, notices the PHP floor before `composer require` fails in CI, and runs the migration, the seed and the HTTP request in its sandbox before the pull request exists.

Every command stays with the run, from `phinx status` to the `curl`, and the pull request quotes them. A handful of Slim services get the same treatment at once, each on its own machine with its own output and pull request.

## Frequently asked questions

### Why does the pull request raise the PHP version?

Because the current Phinx release requires PHP 8.1 and the skeleton allows 7.4 and 8.0, which are past end of life. The agent raises the `php` floor and removes those two from the CI matrix, and says so in the pull request. A team that cannot move can pin an older Phinx release; the pull request names the constraint to change.

### Do the existing tests still pass?

Yes. The action tests in `tests/Application/Actions/User` build the app through `TestCase::getAppInstance` and replace `UserRepository` in the container with a Prophecy double, so they never touch PDO. The new repository test is the only one that migrates a database, and it uses an in-memory SQLite connection.

### Why keep the in-memory repository?

It costs nothing, it is useful for tests and local experiments, and removing it is an unrelated decision. `app/repositories.php` now points the interface at `PdoUserRepository`; switching back is one line.

### Which database does this use in production?

Whichever `phinx.php` reads from `DB_ADAPTER` and the related variables; SQLite under `var/` is only the default so `composer start` works out of the box. Phinx supports MySQL, PostgreSQL, SQLite and SQL Server, and the `PdoUserRepository` uses standard prepared statements, so the choice is configuration, not code.

## More Slim jobs

- [Add a Dockerfile to a Slim 4 App](https://getrush.ai/run/add-dockerfile/slim/)
- [Add a Health Check Endpoint to a Slim 4 App](https://getrush.ai/run/add-health-checks/slim/)
- [Add Input Validation to a Slim 4 API](https://getrush.ai/run/add-input-validation/slim/)

## The same job on other stacks

- [Replace TypeORM synchronize with Migrations](https://getrush.ai/run/add-database-migrations/typeorm/)
- [Add Database Migrations to an Actix Web App](https://getrush.ai/run/add-database-migrations/actix/)
- [Add Alembic Migrations to an aiohttp App](https://getrush.ai/run/add-database-migrations/aiohttp/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
