Storage

By default responses live in a SQLite file in your project, written through Node's built-in node:sqlite — no database server, no native addon. Set a connection string and they go to Postgres instead. Everything goes through one interface, StorageAdapter, so the handler doesn't care where the data lives.

Which database

Every open-form command and the Next.js route pick the first of:

1. OPEN_FORM_DATABASE_URL: Postgres.
2. storage.url in open-form.config.ts: Postgres. Read it from process.env; never write it into the file.
3. OPEN_FORM_DB, then storage.path, then .open-form/open-form.db: SQLite.

open-form db status shows which one is in use.

Where the data lives

.open-form/
├── open-form.db      responses, form versions, rate limits, Studio overrides, signed-out sessions
├── open-form.db-wal
├── open-form.db-shm
└── secret            signs timing tokens, Studio sessions and visitor hashes

The database path is, in order: OPEN_FORM_DB, then storage.path in open-form.config.ts, then .open-form/open-form.db. Relative paths resolve from the project root. open-form dev and open-form start on the same machine share the file.

The generated secret is written next to the database, so a database on a volume (OPEN_FORM_DB=/data/open-form.db) keeps its secret there too, in /data/secret. OPEN_FORM_SECRET replaces the file, and keeps the secret out of copies of the volume. Up to 0.1.1 the secret always stayed in .open-form/secret; when the database lives elsewhere and that file is still there, the first start after upgrading copies it next to the database, so Studio sessions, open form pages and uniqueBy: 'device' keep working.

Protection on disk

• The .open-form/ folder is 0700; the database, its -wal and -shm files, and secret are 0600 — readable by the owner only. The database is created that way, and the database files and secret are re-tightened every time they're opened.
• PRAGMA secure_delete is on, and the write-ahead log is truncated after a delete, so a response deleted in Studio is overwritten rather than left in free pages. Postgres keeps deleted rows until VACUUM; see Deleting responses.
• The dev server refuses to serve the database files, other *.db / *.sqlite files, .env*, keys and exported responses, so they can't be fetched around Studio's sign-in.
• Responses search skips a stored answer it can't read rather than failing.

Tables

Migrations run in order when the database opens. Every response records the schema version it was submitted under, so Responses and exports keep columns for fields you've since removed.

Postgres

The same tables in their own open_form schema, with answers stored as json. Studio's filters and column sorts run the same JavaScript as on SQLite, over the form's responses read from the database, so both agree on every result; search, paging without a filter, and counts run in SQL. Each response to a form takes a lock on that form's row in form_counters, so maxResponses and uniqueBy hold across servers. See Postgres for setup, encryption and permissions.

import { createPostgresStorage } from '@open-form-build/core/postgres';

const storage = await createPostgresStorage({ url: process.env.OPEN_FORM_DATABASE_URL });

createSqliteStorage

import { createSqliteStorage } from '@open-form-build/core/sqlite';

const storage = await createSqliteStorage({ path: '.open-form/open-form.db' });

It takes { path } — a file, or ':memory:' — creates missing folders, applies migrations and resolves to a StorageAdapter. Pass it to createOpenFormHandler or createOpenFormRoute({ storage }).

createMemoryStorage

import { createMemoryStorage } from '@open-form-build/core/server';

const storage = createMemoryStorage();

An in-memory adapter for tests and throwaway previews. Data disappears with the process.

StorageAdapter

Every method is async, so remote databases can implement it; the SQLite adapter simply resolves right away. Import the type from @open-form-build/core/server, along with the ones its methods use: StoredSubmission, CreateSubmissionInput, CreateSubmissionResult, ListSubmissionsOptions, SubmissionPage, FormVersionRecord, FormOverrides, StoredOverrides, ResponseFilter and ResponseSort.

An adapter that can't run Studio's filters inside its database can read a form's responses and hand them to pageSubmissions(rows, opts) from @open-form-build/core/server, which applies filter, sort, order, limit and offset exactly as the built-in adapters do. Search is left to the adapter.

open-form start uses SQLite or Postgres. For anything else, implement StorageAdapter and pass it where you build the handler yourself — with createOpenFormHandler, or createOpenFormRoute in Next.js.