# Add a Local SQLite Database to an Electron App

Yes. An agent adds a SQLite database in the main process, exposes it to the renderer over typed IPC, tests it under Jest, and opens a pull request.

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

## What the agent does

The agent clones the repository into its own cloud sandbox and reads how the processes are wired before it writes a query. In electron-react-boilerplate/electron-react-boilerplate, `src/main/main.ts` creates the window with a preload at `../preload/preload.js`, registers one `ipcMain.on('ipc-example')` handler and starts the auto updater, `src/main/preload.ts` exposes `electron.ipcRenderer` with `sendMessage`, `on` and `once` over a `Channels` type that allows only `ipc-example`, and `src/renderer/App.tsx` renders a `Hello` route inside a `MemoryRouter`. `package.json` pins Electron ^44.4.0, `electron-vite` ^5, Vite 7, React 19, Jest 30 with `jsdom` and TypeScript 7, and its `postinstall` runs `electron-builder install-app-deps`; `release/app/package.json` has an empty `dependencies`, which the README says is where native modules belong, and `electron.vite.config.ts` marks everything listed there as external for the main and preload bundles.

That decides the storage choice. Electron 44 bundles Node 24, which ships the `node:sqlite` module, so the agent checks `process.versions.node` from the installed Electron and uses `DatabaseSync` from `node:sqlite` in the main process: no native module to rebuild for Electron's ABI, nothing to add to `release/app/package.json`, and the same module loads under the Node 24 that `devEngines` requires for Jest. It adds `src/main/db.ts`, which opens `app.db` under `app.getPath('userData')`, turns on WAL, and applies schema migrations keyed on the `user_version` pragma, with the first migration creating a `notes` table; `src/main/notes.ts` registers `ipcMain.handle` for `notes:list`, `notes:add` and `notes:delete` with prepared statements.

The preload grows an `invoke` wrapper and `Channels` widens to the three note channels, so the renderer calls `window.electron.ipcRenderer.invoke('notes:add', text)` with types that follow from `src/renderer/preload.d.ts`. A small `Notes` component on the home route lists and adds notes through those calls. The database opens in `app.whenReady()` before `createWindow`, and closes on `will-quit`, with `log` from `electron-log` recording the path and any migration it ran.

Tests follow the pattern in `src/__tests__/updates.test.ts`, which already runs with `/** @jest-environment node */` and `jest.mock('electron')`: a `db.test.ts` mocks `app.getPath` to a temporary directory, opens the database, runs the migrations twice to show they are idempotent, inserts and lists a note, and checks `user_version`. The agent runs the CI sequence from `test.yml`: `npm run package`, `npm run lint`, `npm exec tsc -- --noEmit`, `npm test`, and the Linux smoke test under `xvfb-run`, and opens a pull request.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add a local SQLite database to this Electron app. Read package.json, release/app/package.json, electron.vite.config.ts, every file under src/main and src/renderer, jest.config.js and .github/workflows/test.yml first, and check which Node version the installed Electron bundles. Prefer the node:sqlite module from that Node when it is available, otherwise use better-sqlite3 declared in release/app/package.json so it is rebuilt for Electron. Open the database under the app's userData path in the main process, apply versioned schema migrations, expose list, add and delete operations for a notes table through ipcMain.handle and a typed invoke in the preload, and show them on the home route. Add a Jest test in the node environment that runs the migrations against a temporary directory. Run the package, lint, type check, test and smoke-test steps CI runs, and open a pull request.",
  "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

What comes back is a pull request on its own branch. The diff adds `src/main/db.ts`, `src/main/notes.ts` and `src/__tests__/db.test.ts`, extends `src/main/preload.ts` and `src/renderer/preload.d.ts`, wires the handlers in `src/main/main.ts` and adds a `Notes` component to the renderer. `release/app/package.json` is unchanged when `node:sqlite` is used, and the description says which path the agent took and why.

The run's record keeps the `npm run package`, `lint`, `tsc` and `jest` output and the smoke test's result under `xvfb-run`, so a reviewer can see the main bundle build with the new module external and the migration test pass without rebuilding the app locally.

Before merging, a reviewer checks that the database path is right for each platform's `userData`, that the migration list only ever appends, and that every IPC handler validates its arguments, since the renderer is a web page and the main process should not trust it.

## Run it on every new Electron app

A team that ships several Electron apps from this boilerplate starts one run per repository with `POST /o/{org}/sessions`, this prompt and the repository in `resources`. Each run reads its own Electron version and decides between `node:sqlite` and a rebuilt native module on that basis, and each opens its own pull request.

A `request_id` in the body makes a retry safe, and the API key's webhook posts `run.completed` or `run.failed` with the `session_url` when each turn ends, so a script can collect the pull request links and the test output.

## Why run it on Rush?

Whether a storage module loads inside Electron, inside Jest and inside the packaged app are three different questions, and the boilerplate's `postinstall`, rebuild script and bundler externals all take part in the answer. The sandbox runs the whole CI sequence, including `electron-builder` packaging and the smoke start under a virtual display, and keeps the output, so the pull request shows the answer rather than asserting it.

The change crosses the main process, the preload boundary, the renderer and the tests. One run returns all of it with its log, and the same prompt runs against several Electron apps at once, each in its own sandbox with its own Electron version.

## Frequently asked questions

### Why node:sqlite instead of better-sqlite3?

Electron 44 bundles Node 24, and `node:sqlite` comes with it, so there is no native binary to rebuild for Electron's ABI and nothing to unpack from the asar. The agent checks the bundled Node version first; on an older Electron it falls back to `better-sqlite3` in `release/app/package.json`, where `electron-builder install-app-deps` rebuilds it.

### Can the renderer query the database directly?

No. The database stays in the main process, and the renderer reaches it only through the `invoke` calls the preload exposes, with `Channels` limiting the names. That keeps Node out of the web page, as the boilerplate's context isolation intends.

### How are schema changes handled later?

Migrations are an ordered list in `db.ts` applied when `user_version` is below their index, inside a transaction. Adding a column is one new entry; the test runs the list twice to prove it is safe to rerun.

### Where does the file live?

At `app.db` inside `app.getPath('userData')`, which is the per-user application directory on macOS, Windows and Linux. The path is logged through `electron-log` at startup so support can find it.

## More Electron jobs

- [Add Desktop Notifications to an Electron App](https://getrush.ai/run/add-notifications/electron/)
- [Add Persistent User Settings to an Electron App from a Linear Issue](https://getrush.ai/run/add-persistent-settings/electron/)
- [Add a Single-Instance Lock to an Electron App](https://getrush.ai/run/add-single-instance-lock/electron/)

## More jobs like this: Hand off a long task

- [Add Log Rotation to a Docker Compose Stack](https://getrush.ai/run/add-log-rotation/docker-compose/)
- [Add Log Rotation to a Winston Logger](https://getrush.ai/run/add-log-rotation/winston/)
- [Add Logging to a Tauri App with tauri-plugin-log](https://getrush.ai/run/add-logging/tauri/)

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