Persistence

Pinorama Server stores logs in-memory using Orama. Persistence saves the database to disk and restores it on startup, so logs survive server restarts.

How It Works

1. On startup — If the configured dbPath file exists, the database is restored from it. Otherwise, a fresh database is created.
2. On shutdown — When the server closes gracefully (app.close()), the database is automatically saved to dbPath via the Fastify onClose hook. Call it from your signal handler so Ctrl+C saves too; Pinorama Studio does this for its embedded server.
3. On demand — Trigger a save at any time via the POST /persist endpoint.
4. Auto-save — When autoSaveInterval is configured, the database is saved periodically at the specified interval.

Configuration

Pass persistence options when registering the Pinorama Server plugin:

import Fastify from "fastify"
import pinoramaServer from "pinorama-server"

const app = Fastify()

app.register(pinoramaServer, {
  dbPath: "./data/logs.msp",
  dbFormat: "binary",
  introspection: { /* ... */ }
})

Option	Type	Default	Description
dbPath	string	undefined	File path for saving/restoring the database
dbFormat	"json" | "dpack" | "binary"	"binary"	Serialization format
autoSaveInterval	number	undefined	Auto-save interval in ms

WARNING

If dbPath is not set, the database is purely in-memory and all data is lost when the server stops.

Auto-Save

When both dbPath and autoSaveInterval are configured, Pinorama Server automatically persists the database at the specified interval. This protects against data loss from unexpected crashes.

app.register(pinoramaServer, {
  dbPath: "./data/logs.msp",
  autoSaveInterval: 60_000 // save every 60 seconds
})

The auto-save timer is automatically cleared when the server shuts down. If an auto-save fails, the error is logged but the server continues running.

Formats

Pinorama supports three persistence formats provided by @orama/plugin-data-persistence:

Format	Description
json	Human-readable JSON. Good for debugging and small datasets.
dpack	MessagePack-based binary format. More compact than JSON.
binary	Raw binary format. Most compact, best for large datasets. Default.

Recommended Setup

Start with basic persistence and add auto-save for crash protection:

app.register(pinoramaServer, {
  dbPath: "./data/logs.msp",
  dbFormat: "binary",
  autoSaveInterval: 60_000,             
  introspection: { /* ... */ }
})

Manual Persist

Trigger a manual save via the REST API:

curl -X POST http://localhost:3000/persist \
  -H "x-pinorama-admin-secret: my-secret"

Returns 204 No Content on success. Requires authentication if adminSecret is configured.

Pinorama Studio

When using Pinorama Studio with piped input, the embedded server keeps logs in memory and discards them on exit. Pass --server-db-path to persist them: the file is restored on startup and saved on Ctrl+C.

node app.js | pinorama --open --server-db-path ./my-logs.msp