DEV Community: Fabien B.

Build an Electron app with local data storage — no SQLite bindings, no server

Fabien B. — Wed, 10 Jun 2026 22:36:47 +0000

If you've shipped an Electron app that persists structured data, you've probably hit the wall at some point. You need something more than a flat JSON file, but a full database server is absurd for a desktop app. So you reach for better-sqlite3 — and then spend the next hour fighting native bindings.

The Electron storage problem

Electron bundles its own version of Node.js. That version almost never matches the one on your machine. Native Node modules — the ones that compile C++ bindings — need to be recompiled specifically for the Electron runtime, using electron-rebuild or equivalent tooling.

In practice this means:

Every Electron update potentially breaks your native dependencies
CI pipelines need platform-specific build steps for Windows, macOS and Linux
Code signing and notarization on macOS gets complicated by native binaries
End users on some machines encounter install failures you can't reproduce locally

better-sqlite3 is an excellent library. But it is a native module, and native modules in Electron are a tax you pay forever.

The alternatives people reach for have their own problems. lowdb and lokijs keep everything in memory and flush to disk — fine for small datasets, but you lose durability on crash and memory usage grows with your data. nedb hasn't been maintained in years. A remote database is obviously wrong for a local desktop app.

What you actually need

For most Electron apps, the storage requirements are modest but specific:

Structured documents, not just key-value pairs
Queries that go beyond "give me everything"
Writes that survive a crash
Zero native binaries — pure JavaScript, works everywhere Electron runs
No server process running alongside your app

That's exactly the gap pocket-db is designed to fill. It's a single-file embedded document store — the SQLite model applied to JSON documents, with a MongoDB-style API. Pure TypeScript, shipped as both ESM and CommonJS. No native bindings. No optional dependencies.

Building the example app

Let's build a small note-taking app: create, list, search and delete notes. Simple enough to follow in full, realistic enough to show the pattern.

Setup

We'll use electron-vite, which scaffolds the src/main / src/preload / src/renderer layout used below, with TypeScript and React ready to go:

npm create @quick-start/electron@latest my-notes -- --template react-ts
cd my-notes
npm install @axfab/pocket-db

No electron-rebuild. No postinstall scripts. That's the point.

Initialising the database

In Electron, database access belongs in the main process. You have access to the filesystem there, and it keeps your renderer process clean. Use app.getPath('userData') — Electron's standard location for app data, persisted across updates.

One thing to know: Electron creates the userData directory lazily, so on a first launch it may not exist yet — and open() does not create parent directories. Create it before opening:

// src/main/db.ts
import { app } from 'electron'
import { open } from '@axfab/pocket-db'
import { mkdirSync } from 'node:fs'
import path from 'node:path'

const dataDir = app.getPath('userData')
mkdirSync(dataDir, { recursive: true }) // may not exist on first launch

export const db = open({ path: path.join(dataDir, 'notes.pdb') })
export const notes = db.collection('notes')

One file, one call. The database is created if it doesn't exist. No migrations, no schema definition.

Exposing database operations via IPC

Electron's security model means the renderer can't touch Node APIs directly. You expose operations through IPC handlers in the main process and call them via contextBridge in the preload script.

Search deserves a moment of care: the search term comes from user input, and $regex compiles it as a regular expression. A term containing ( or [ would throw, and a raw pattern is case-sensitive. Escape the input and pass $options: 'i':

// src/main/index.ts
import { app, BrowserWindow, ipcMain } from 'electron'
import { db, notes } from './db'

/** Escapes regex metacharacters so user input is matched literally. */
const escapeRegex = (term: string) =>
  term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')

ipcMain.handle('notes:create', (_event, title: string, body: string) => {
  return notes.insertOne({ title, body, createdAt: Date.now() })
})

ipcMain.handle('notes:list', () => {
  return notes.find().sort({ createdAt: -1 }).toArray()
})

ipcMain.handle('notes:search', (_event, term: string) => {
  const pattern = escapeRegex(term)
  return notes.find({
    $or: [
      { title: { $regex: pattern, $options: 'i' } },
      { body:  { $regex: pattern, $options: 'i' } }
    ]
  }).toArray()
})

ipcMain.handle('notes:delete', (_event, id: string) => {
  return notes.deleteOne(id)
})

app.on('before-quit', () => db.close())

// src/preload/index.ts
// Note: keep the preload compiled to CommonJS (electron-vite's default) —
// sandboxed renderers don't load ESM preload scripts.
import { contextBridge, ipcRenderer } from 'electron'

contextBridge.exposeInMainWorld('notes', {
  create:  (title: string, body: string) => ipcRenderer.invoke('notes:create', title, body),
  list:    ()           => ipcRenderer.invoke('notes:list'),
  search:  (term: string) => ipcRenderer.invoke('notes:search', term),
  delete:  (id: string) => ipcRenderer.invoke('notes:delete', id),
})

Using it in the renderer

From the renderer, the API is just async function calls:

// src/renderer/src/App.tsx
const handleCreate = async () => {
  await window.notes.create(title, body)
  setNotes(await window.notes.list())
}

const handleSearch = async (term: string) => {
  const results = await window.notes.search(term)
  setNotes(results)
}

const handleDelete = async (id: string) => {
  await window.notes.delete(id)
  setNotes(await window.notes.list())
}

No database logic in the renderer. No connection strings. No async initialisation to wait for. The main process owns the database, the renderer just calls handlers.

Where indexes help — and where they don't

Two things to know about pocket-db's query planner in V1: $regex is never index-assisted (it's always evaluated against the documents), and $or queries bypass index planning entirely. So the regex search above is a full collection scan — perfectly fine for a notes app, but don't expect an index to speed it up.

Indexes shine on equality and range lookups. Say notes belong to notebooks:

// run once at startup, safe to call repeatedly
notes.createIndex('notebook', { type: 'string' })

Now a query like notes.find({ notebook: 'work' }) reads only the matching documents instead of scanning the collection — the planner picks the index up automatically, no change needed in your query code. The same goes for a number index on createdAt if you query by date range.

Periodic compaction

The append-only log accumulates dead records as notes are edited and deleted. Schedule compaction when the app is idle:

app.on('browser-window-blur', () => {
  db.compact()
})

compact() is fast and synchronous — it rewrites the file in a single forward pass. Calling it when the window loses focus means it runs during natural pauses without affecting responsiveness.

Packaging and distribution

This is where the native module problem usually surfaces. With pocket-db, there's nothing to rebuild. The electron-vite scaffold already wires up electron-builder; its config just works as-is:

# electron-builder.yml (generated by the scaffold)
mac:
  target: dmg
win:
  target: nsis
linux:
  target: AppImage

No electron-rebuild in your build pipeline. No platform-specific post-install hooks. The same config builds cleanly on all three platforms.

If you're using GitHub Actions to build releases:

# .github/workflows/release.yml
- name: Build
  run: npm run build && npx electron-builder
  # No electron-rebuild step needed

One fewer thing to maintain.

What about data migration?

pocket-db is schemaless — documents in the same collection can have different shapes. That means additive changes (adding a new field) require nothing: new documents have the field, old ones don't, and $exists lets you query for either.

For breaking changes, a one-time migration on startup is straightforward. Keep a version marker in a metadata collection — and remember that on a fresh database the marker doesn't exist yet:

const schema = db.collection('_meta')
const marker = schema.findOne({ key: 'version' })
const version = typeof marker?.value === 'number' ? marker.value : 0

if (version < 2) {
  // run migration
  notes.updateMany({}, { $set: { archived: false } })

  if (marker) {
    schema.replaceOne(marker._id as string, { key: 'version', value: 2 })
  } else {
    schema.insertOne({ key: 'version', value: 2 })
  }
}

Note the replaceOne(marker._id, …) call: the first argument is the document id. (Passing a full document as the only argument is a separate overload that replaces that document by itself — not what you want here.)

No migration framework needed for most desktop app scenarios.

The trade-offs to know

pocket-db is designed for single-process use. An Electron app fits that model perfectly — the main process is the only writer, and that's exactly the intended use case.

It is not the right choice if your Electron app spawns multiple Node worker processes that all need to write to the same database simultaneously. It is also not the right choice if you're storing hundreds of thousands of documents and need complex aggregation — at that scale, an actual database server starts making sense even in a desktop context.

For the common case — a desktop app storing user data, preferences, history, cached API responses, local task lists — it fits well.

Getting started

npm install @axfab/pocket-db

Full documentation at pocket-db.axfab.net. Source and issues at github.com/axfab/pocket-db. The complete example app from this article is in the repository of exemple, tests included.

If you've been putting up with native binding headaches in Electron, give it a try and let me know how it goes.

pocket-db is MIT licensed.

pocket-db vs lowdb vs LokiJS: an honest embedded database benchmark

Fabien B. — Sun, 31 May 2026 18:02:52 +0000

If you've ever built a CLI tool, an Electron app, or a local-first prototype in Node.js, you've faced the same question: where do I store structured data without spinning up a server?

The usual suspects are well known — lowdb, LokiJS, nedb, better-sqlite3. I recently built pocket-db, a new embedded document store for Node.js.

I wanted a database solution that offered me:

a single-file database
no native compilation
Mongo-like API
easy embedding in CLI or Electron apps

I wanted to know honestly where it stands. So I ran a benchmark across 10 common operations on a collection of 1,000 documents.
Here's what I found — not shying away from the unflattering parts.

The contenders

pocket-db — append-only single-file document store, MongoDB-like API, indexes in memory
sqlite (in-memory) — better-sqlite3 with an in-memory database, the fastest SQLite configuration
sqlite (file) — better-sqlite3 persisted to disk, the most common SQLite setup
json-file — full JSON file read/write on every operation
lowdb — JSON-based, keeps everything in memory and flushes to disk on write
lokijs — in-memory document store, optional persistence

All tests run on Apple M-series hardware. Results are in ops/sec — so higher is better.

The results

Operation                  pocket-db  sqlite (mem)  sqlite (file)  json-file      lowdb     lokijs
─────────────────────────────────────────────────────────────────────────────────────────────────
insertOne                    198,177     226,278 *         4,421      3,893      2,256      1,004
insertMany (100)               2,345       2,963 *           402        788        628        264
findById                     142,776   1,064,774         248,942  12,532,585 * 321,548  4,061,606
findAll                           96         361             361    115,774    870,822 *     1,179
findByName (scan)                 97         536             524     19,579     24,235 *     8,222
findByRole (index)               277         884             887     18,527     21,796 *     3,215
updateOne                     97,889     423,072 *         2,675        784        566        188
deleteOne                    454,402     465,026 *         5,551        924        663        220
countAll                      12,038   2,233,389         285,285  42,553,191 * 34,914,251 37,348,273
sortByScore (desc)                91         293             293      4,947      5,099 *     1,123
─────────────────────────────────────────────────────────────────────────────────────────────────
All values in ops/sec. * = fastest for this operation.

Before you ask: json-file wins read benchmarks because the entire dataset is already loaded in memory during the benchmark.

Why pocket-db writes so fast

The short answer: every write is a single sequential append to the end of the file. No B-tree rebalancing. No page allocation. No full-file reserialisation.

When you call insertOne, updateOne or deleteOne, pocket-db appends one record to the log and updates the in-memory index pointer. That's it. An update doesn't touch the old record — it writes a replacement which is enough to marks the previous offset as dead. A delete appends a tombstone. This is why deleteOne reaches 454,000 ops/sec, only marginally behind SQLite in-memory.

There's a second reason the numbers look good today: no fsync wait. Writes land in the OS page cache and return immediately. This is fast, but it's a trade-off — a hard crash before the OS flushes to disk can lose the last few writes. Pocket-db is perfectly capable to recover from incomplete operations, so consistency is never compromised. For the target use cases (CLI tools, desktop apps, local prototypes), this is an acceptable trade-off. For anything requiring strict durability guarantees, it's something to be aware of.

Why reads are slower — and what's being done about it

This is the honest part of the benchmark.

pocket-db keeps only indexes in memory, not documents. Every findOne and every cursor step seeks to the document's byte offset in the file and reads from disk. Every result then goes through JSON parsing. This is the fundamental cost of the current design — and it shows clearly in the numbers.

In-memory stores like lowdb and LokiJS serve reads directly from JavaScript objects: no I/O, no parsing. That's why findById on a json-file store reaches 12 million ops/sec while pocket-db sits at 142,000.

Keeping indexes in memory was a necessary first compromise. Without them, reads would require a full file scan for every query — completely unusable in practice. Indexes bring findById to a competitive level for real-world access patterns where you're not reading the same hot document in a tight loop. But the gap on read-heavy workloads is real, and it needs to be closed.

The roadmap for the next version is to address this directly. The first candidate is a document cache: keep recently accessed documents in memory and avoid redundant disk reads for hot-document workloads. This alone should close most of the gap for typical usage patterns. The second candidate is a binary document format to replace JSON serialisation — parsing structured binary is significantly faster than JSON.parse for complex documents. A third option under consideration is memory-mapped I/O with pagination, which would allow the OS to manage the hot-document cache at a lower level.

The memory footprint is also something to watch. Indexes in memory work well at the scales pocket-db is designed for — thousands to low hundreds of thousands of documents. As collections grow, that in-memory index cost grows with them. Load testing at larger scales is to be considered before locked of the architecture.

Reading the numbers in context

The benchmark is deliberately narrow: 1,000 documents, ten operations, one process. That's a fair representation of the workloads pocket-db is built for — a CLI tool tracking state, an Electron app storing user data, a local server caching API responses.

At that scale, the practical difference between 97 and 870,000 read ops/sec is manageable. A CLI command doesn't loop through findByName a million times. But it does insert records frequently, update state on every run, and occasionally compact. For that profile, pocket-db's write throughput is genuinely competitive.

Where the numbers are a real concern is if you're considering pocket-db for a workload that's read-heavy by nature — serving requests in a tight loop, scanning large collections on every query. For those cases today, a pure in-memory store is the honest recommendation.

Where things stand

pocket-db is a young project. These benchmark results are encouraging for what it's designed to do: fast, durable writes in a single-file embedded store with a familiar API. The write story is solid. The read story needs work, and the work ahead is well defined.

The next performance chapter — document cache, binary format, larger-scale index testing — will determine whether pocket-db can compete across the full spectrum of embedded workloads. That's the honest assessment at this first version.

If you want to run the benchmarks yourself:

git clone https://github.com/axfab/pocket-db
npm install
npm run bench

And if a single-file, zero-dependency document store with a MongoDB-style API sounds like what your next project needs:

npm install @axfab/pocket-db

@axfab/pocket-db is MIT licensed. Contributions, issue reports, and benchmark challenges welcome.