# Add a SQLite Database to a Reflex App

Yes. An agent moves your Reflex app's in-memory state into a SQLModel table in SQLite, loads it on page load, adds a browser test and opens a PR linked to the issue.

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

## What the agent does

The agent reads the app before touching its state. In an app like the `todo` example in reflex-dev/reflex-examples, `todo/todo/todo.py` keeps everything in a `State` class: `items` is a plain `list[str]` seeded with three strings, `add_item` takes the form's `dict[str, str]` and appends `new_item`, and `finish_item` pops by value. The UI is `rx.foreach(State.items, ...)` over `rx.list_item` rows with an `rx.icon_button` whose `on_click` calls `finish_item(item)`, and an `rx.form` with `on_submit=State.add_item` and `reset_on_submit=True`. `app.add_page(index, title="Todo App")` registers the one page with no `on_load`. `rxconfig.py` sets `app_name="todo"`, `env=rx.Env.DEV` and the `RadixThemesPlugin`, with no `db_url`; `requirements.txt` says `reflex>=0.9.2`. Every item vanishes when the backend restarts, and two browsers see two different lists.

The Reflex database documentation is clear about which API to use: `rx.Model` and `rx.session()` are deprecated as of 0.9.2 and scheduled for removal in 1.0, and new apps should use SQLModel directly with their own engine and sessions. So the agent adds `todo/todo/db.py` with a `Todo(SQLModel, table=True)` class, an `id: int | None = Field(default=None, primary_key=True)`, a `text: str` field, and `engine = create_engine("sqlite:///todo.db")`, calling `SQLModel.metadata.create_all(engine)` once at import, the pattern the documentation gives for a first table and a local file. `requirements.txt` becomes `reflex[db]>=0.9.2`, because the `db` extra is what pulls in `sqlmodel`, `alembic` and the `greenlet` build SQLAlchemy needs. `todo.db` and its journal join `todo/.gitignore`.

The state changes shape but not the UI's contract. `items` becomes a list of rows with `id` and `text`; a `load_items` event handler opens `Session(engine)`, runs `select(Todo).order_by(Todo.id)` and copies the rows into state; `add_item` inserts a `Todo` and reloads; `finish_item` takes the row's `id`, deletes it and reloads, replacing the pop-by-value that would remove the wrong row when two items share a text. `app.add_page(index, title="Todo App", on_load=State.load_items)` fills the list when the page opens, so each browser reads the same table. `todo_item` renders `item.text` and passes `item.id` to the button, which is the only change the components see. Every session is short-lived, opened inside the handler and closed by the `with` block, as the documentation asks.

The repository already shows how an example proves itself: `counter/tests/test_counter.py` starts the app with `reflex.testing.AppHarness.create(root=...)`, drives a browser through `harness.frontend()` and polls with `poll_for_content`, and `counter/requirements-dev.txt` lists `pytest`, `selenium`, `pytest-asyncio`, `playwright`, `pytest-playwright`, `uvicorn` and `psutil`. The `app_harness.yml` workflow finds every example directory that contains a `tests` folder and fails if it lacks a `requirements-dev.txt`. The agent adds `todo/tests/test_todo.py` on that pattern: it types an item into the form, submits, checks the row appears, restarts the harness against the same `todo.db` and checks the row is still there, then finishes it and checks it is gone. Adding the `tests` directory and `requirements-dev.txt` enrols `todo` in that matrix with no workflow change. In its sandbox the agent runs `reflex init`, `reflex run` and the test headless, and reads the SQLite file with `sqlite3 todo.db .schema` to confirm the table.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Persist this Reflex app's todo items in a SQLite database instead of in-memory state. Read rxconfig.py, requirements.txt, the app module and the tests and requirements-dev.txt of any sibling example that already has them first. Use SQLModel directly with create_engine and Session rather than rx.Model, which the Reflex docs deprecate from 0.9.2: add a Todo table with an integer primary key and a text field, create the tables with SQLModel.metadata.create_all on a sqlite file, and ignore that file in git. Change requirements.txt to the reflex[db] extra. Replace the list of strings with rows loaded in an on_load event handler, insert on add, delete by id on finish, and keep the components the same apart from reading the row's text and id. Add a tests directory with an AppHarness test on the pattern the repository already uses that adds an item, restarts the app against the same database, checks the item is still listed and then finishes it, plus a requirements-dev.txt. Run reflex init, the app and the test in the sandbox, read the schema with sqlite3, and open a pull request that links the issue and lists the commands and their 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 changes `todo/todo/todo.py`, `todo/requirements.txt` and `todo/.gitignore`, and adds `todo/todo/db.py`, `todo/tests/test_todo.py` and `todo/requirements-dev.txt`. Its description shows the `.schema` output for the `todo` table, the test run's output, and a before-and-after of the state class, and explains the two decisions it made: SQLModel over the deprecated `rx.Model`, and `create_all` for a first table with a note that schema changes after this one belong in Alembic migrations, which the `db` extra also installs.

A reviewer checks that the database path suits where the app runs, since `sqlite:///todo.db` is relative to the working directory and a deployed app may want an absolute path or a `db_url` from the environment, and that the restart step in the test is the proof they wanted. The `app_harness.yml` run on the pull request executes the new test on the next push because the matrix discovers the `tests` directory, so the check appears on the pull request without a workflow change.

## Run it on every Linear issue labelled persistence

A team that triages in Linear adds an automation to the Project with a `linear` trigger on `linear.issue.labeled`, the label `persistence` and `plan` mode, so the agent reads the issue and the app and posts the table, the handlers it would change and the test it would add as a comment on the issue. Only a change made by a member of the Rush org fires it, and the comment is the whole result: an automation's runs are read-only and push nothing.

When the plan is agreed, a handler on the team's own server starts the run that pushes: it sends this body with the Linear issue URL added to `resources`, which puts the issue text in front of the agent through the team's Linear connection, and a `request_id` that is a UUID v5 of the issue id, so a redelivered event returns the run already started rather than a second pull request.

## Why run it on Rush?

Moving state into a database is a change to every handler that touches it, and the mistakes are quiet: a row that is deleted by text instead of id, a session held open across an event, a list that is loaded once at import and never again. The agent reads the Reflex documentation's current advice, writes the handlers against it, and proves the result the way the repository already proves its examples, with a browser test that restarts the app and finds the data still there, run in its own sandbox with the commands and output kept in the run's record.

It also fits the repository's conventions rather than inventing new ones: the `tests` directory and `requirements-dev.txt` are what the existing CI matrix looks for, so the new test runs on the pull request without anyone editing a workflow. Several apps with the same in-memory pattern get several pull requests, each reading its own state class and config.

## Frequently asked questions

### Why not rx.Model and rx.session?

Because the Reflex database documentation marks both as deprecated from 0.9.2 and scheduled for removal in 1.0.0, and the app's own requirement is `reflex>=0.9.2`. SQLModel's `create_engine` and `Session` are what the documentation recommends for new apps, and the same state patterns apply.

### Will it work with PostgreSQL later?

Yes. The engine URL is the only SQLite-specific line; the documentation lists MySQL, PostgreSQL, SQL Server and SQLite as supported through SQLAlchemy dialects, each needing its driver installed. The pull request reads the URL from an environment variable with the SQLite file as the default, so a deployment points it elsewhere without a code change.

### Where do migrations come in?

`create_all` creates the table the first time and never alters it, which the documentation says is fine for a first local table. The `reflex[db]` extra installs Alembic, and the pull request notes that the next schema change should be a migration rather than a second `create_all`.

### Does the test need a real browser?

Yes. `AppHarness` starts the backend and frontend and drives a browser, the same way `counter/tests/test_counter.py` does, and the repository's workflow installs a Chromium for the browser tests. The agent runs it headless in its sandbox, and the pull request's own CI run repeats it.

### Why does the item list reload after every change?

So the state is always what the table holds. Each handler opens a short session, writes, commits and reads the rows back, which keeps two browsers on the same list and avoids holding ORM objects past the session that created them, which the documentation warns against.

## More Reflex jobs

- [Write Integration Tests for a Reflex App](https://getrush.ai/run/write-integration-tests/reflex/)
- [Write Pytest Tests for a Reflex App](https://getrush.ai/run/write-pytest-tests/reflex/)
- [Run a Long Task in the Background in a Reflex App](https://getrush.ai/run/add-background-tasks/reflex/)

## More jobs like this: Turn a Linear label into a PR

- [Add Server-Side Rendering to a Lit Component](https://getrush.ai/run/add-ssr/lit/)
- [Add a Staging Overlay with Kustomize from a Linear Issue](https://getrush.ai/run/add-staging-overlay/kustomize/)
- [Persist Redux Toolkit State Across Page Reloads](https://getrush.ai/run/add-state-persistence/redux-toolkit/)

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