# Migrate a Strapi App From SQLite to PostgreSQL

Yes. An agent adds the pg driver, moves the content with strapi export and import onto a real PostgreSQL, compares the API on both and opens a PR.

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

## What the agent does

The agent reads the database config first, because in many Strapi projects half the work is already there. In an app like strapi/LaunchPad, `strapi/config/database.ts` picks a client from `DATABASE_CLIENT`, defaulting to `sqlite`, and already has a `postgres` branch: `DATABASE_URL` or host, port, name, user and password, an SSL block switched by `DATABASE_SSL`, a schema that defaults to `public`, and a pool of 2 to 10 connections. What is missing is everything around it. `package.json` lists `better-sqlite3` and no `pg`, `.env.example` has no `DATABASE_` line at all, and the README never mentions Postgres.

It records the starting point on SQLite. After installing and building, it imports the demo data with the repository's `seed` script, starts the server and saves the JSON answers for every content type under `strapi/src/api` in both locales. Then it writes an export with `strapi export --no-encrypt`, the same command the root `export` script wraps, and keeps the summary of entities, assets and links that the command prints. Those two things, the answers and the counts, are what the PostgreSQL side has to reproduce.

Then it stands up the target. The sandbox has no database server and no Docker, so the agent installs PostgreSQL with `apt-get`, starts it, and creates a role and a database. It adds `pg` to `strapi/package.json`, sets `DATABASE_CLIENT=postgres` and the connection variables in `.env`, rebuilds and starts Strapi once so it creates its tables in the empty database, and runs `strapi import` with the export file. It reads the import's summary against the export's, restarts, repeats every request and diffs the answers. It also reads the tables back with `psql` to confirm the content landed in the configured schema.

The last part is what the tooling does not carry, and the agent writes it down instead of discovering it at deploy. An export holds content, media and configuration; it does not hold admin users or API tokens, so the new database needs a first admin and any token your front ends send has to be created again. Uploaded files live under `public/uploads` or with your upload provider, not in the database. And SQLite stays the default for local work unless you say otherwise: the agent leaves `better-sqlite3` in place and documents the three variables that switch a machine to PostgreSQL.

## Start it with one API call

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

```json
{
  "agent": "codex",
  "input": "Move the Strapi backend in strapi/ from SQLite to PostgreSQL and open a pull request. Read AGENTS.md, README.md, the root package.json scripts, strapi/package.json, strapi/.env.example, strapi/.gitignore and every file under strapi/config first, and list what the postgres branch of config/database.ts already reads and what is missing around it. Docker is not available: install PostgreSQL from system packages, start it, and create a role and a database for Strapi. Baseline on SQLite: enable Corepack, yarn install at the root and in strapi/, copy .env.example to .env, yarn build, import the demo data with the seed script, start the server and save the JSON answers of GET /api/<plural> for every content type in locales en and fr. Export with strapi export --no-encrypt and keep its summary table. Then add pg to strapi/package.json, set DATABASE_CLIENT=postgres and the connection variables in .env, rebuild, start once against the empty database so the schema is created, stop, run strapi import with the export file, and compare its summary with the export's. Start again, repeat every request and diff against the baseline; explain any difference. Check the tables with psql. Keep SQLite as the default client and keep better-sqlite3. Add the DATABASE_ variables to .env.example, commented, with one line each on DATABASE_SSL and DATABASE_SSL_REJECT_UNAUTHORIZED for hosted databases, and add a short Postgres section to the README with the export and import steps. Search the front-end folders for content API filters and report any whose matching is case-sensitive on PostgreSQL and was not on SQLite, without editing them. Do not commit .env, the export file or any database file. In the pull request include both summary tables, the request comparison, and a cutover checklist: export, create the admin user, recreate API tokens, move uploads.",
  "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 is small on purpose: `pg` in `strapi/package.json` with its lockfile entry, the `DATABASE_` block in `.env.example`, and a README section. `config/database.ts` usually needs no edit, and the description says so with the lines it relies on. The evidence is in the description: the export's summary table beside the import's, and one row per request showing that the answer from PostgreSQL matches the one from SQLite, or which field differs and why.

The cutover checklist is the part a person acts on. It gives the commands in order for a real environment: take an export from the running SQLite instance, deploy with the three variables set, let the first start create the schema, import, create the admin user, recreate each API token and update the front ends that hold one, and copy `public/uploads` if media is on local disk. It names the two SSL variables the config reads, since a hosted PostgreSQL usually needs `DATABASE_SSL=true`.

A reviewer checks that no secret, `.env` or export archive is in the diff, that SQLite is still what a fresh clone gets, and that the filter report matches how the front ends query. In this project they look pages and products up with `$eq` on `slug`, which behaves the same on both databases. An app that searches with `$contains` should read that section closely, because SQLite matches such a filter without regard to case and PostgreSQL does not.

## Run it on every Strapi project still on SQLite

This is a job to start from your editor and come back to. With Rush connected as an MCP server, `claude mcp add --transport http rush https://api.phoenix.so/mcp` plus your API key in an `Authorization` header, your local agent calls `create_session` with this page's body and gets the session back at once. `wait_for_sessions` then checks on it for up to 50 seconds per call. The PostgreSQL server, the export and both sets of answers live in the run's sandbox, so nothing is installed on your machine and your local `.tmp/data.db` is never touched.

An agency with several Strapi backends sends the body once per repository to `POST /o/{org}/sessions`, each with a `request_id` that is a UUID v5 of the repository's full name and the word postgres, so a retried script returns the runs it already started. A key runs four at a time by default and the rest wait as `queued`. If a run's comparison shows a difference you want handled, a follow-up message wakes that run's sandbox with both databases still in place.

## Why run it on Rush?

Changing the client is one environment variable. Knowing that the content survived is the work, and it needs both databases side by side: the same requests against each, the same counts from export and import, and a look inside the new tables. On a laptop that means installing a PostgreSQL you may not want, keeping two Strapi configurations straight and remembering which terminal is which. It tends to get done once, by eye, on the day of the cutover.

The agent does it as a rehearsal, in a sandbox that starts empty and is thrown away. It installs the server, runs the export and import the way production will, and keeps every command and its output in the session's transcript. The pull request then arrives with a comparison you can read and a checklist built from what actually happened, including the things an export leaves behind. When the real cutover comes, the steps have already been run once from a clean machine.

## Frequently asked questions

### Does it copy the SQLite file's rows straight into PostgreSQL?

No. It uses Strapi's own `strapi export` and `strapi import`, which move content, relations, media and configuration through Strapi and let the new database's schema be created by Strapi itself. A row-level copy with a generic tool has to get column types, link tables and sequences right by hand, and Strapi's layout for components and dynamic zones makes that easy to get wrong.

### What is not carried over by an export?

Admin users and API tokens. After the import, the new database has your content and no one who can sign in to the admin panel, so the first start asks you to create an admin, and every API token has to be generated again. The pull request's checklist lists both, and says whether any front end in the repository sends a token.

### Will local development still use SQLite?

Yes, unless the prompt says to switch. The config's default client stays `sqlite` and `better-sqlite3` stays installed, so a fresh clone runs with no database server. Setting `DATABASE_CLIENT=postgres` and a connection in `.env` moves one machine over. If you want Postgres everywhere, ask for it and the agent changes the default and removes the SQLite driver.

### Our Postgres host requires SSL. Is that handled?

The existing config already reads `DATABASE_SSL` and, when it is true, `DATABASE_SSL_REJECT_UNAUTHORIZED` along with optional key, certificate and CA variables. The agent documents them in `.env.example`. It tests against a local PostgreSQL without SSL in its sandbox, so the SSL path is described from the config and not exercised by the run.

### Can it run the import against our real database?

It should not, and this request gives it no credentials for one. `strapi import` replaces what is in the target, so the real cutover is a step a person runs with a backup in hand. The run proves the procedure on disposable databases and hands you the commands.

## More Strapi jobs

- [Upgrade Strapi to the Latest Version](https://getrush.ai/run/upgrade-strapi/strapi/)
- [Write API Tests for a Strapi App](https://getrush.ai/run/write-api-tests/strapi/)
- [Set Up GitHub Actions CI for a Strapi App](https://getrush.ai/run/add-github-actions-ci/strapi/)

## The same job on other stacks

- [Migrate a Drizzle Schema from SQLite to PostgreSQL](https://getrush.ai/run/migrate-sqlite-to-postgres/drizzle/)
- [Migrate an Echo and GORM API From SQLite to Postgres](https://getrush.ai/run/migrate-sqlite-to-postgres/echo/)
- [Migrate a Feathers App From SQLite to Postgres](https://getrush.ai/run/migrate-sqlite-to-postgres/feathers/)

## 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/)
