Backup & Restore

Fluent OSS supports snapshot-based backup and restore. The snapshot format is JSON and is compatible across deployment tracks, so you can move data between OSS instances, import from Hosted, or back up before upgrades.

Export a Snapshot

Default SQLite Backend

npm run oss:export:snapshot -- --out "./tmp/fluent-oss-snapshot.json"

Postgres + S3 Backend

npm run oss:export:snapshot -- --backend postgres-s3 \
  --out "./tmp/fluent-oss-postgres-s3-snapshot.json"

From Fluent Hosted

Export your data from the hosted service:

npm run export:snapshot:hosted -- --database fluent-hosted \
  --out "./tmp/fluent-cloud-snapshot.json"

Import a Snapshot

Into Default SQLite Backend

npm run oss:import:snapshot -- --file "./tmp/fluent-oss-snapshot.json"

Import into a specific root:

npm run oss:import:snapshot -- --root "./tmp/fluent-restore" \
  --file "./tmp/fluent-oss-snapshot.json"

Into Postgres + S3 Backend

npm run oss:import:snapshot -- --backend postgres-s3 \
  --file "./tmp/fluent-oss-postgres-s3-snapshot.json"

From Hosted into OSS

npm run oss:import:snapshot -- --file "./tmp/fluent-cloud-snapshot.json"

The snapshot format is aligned between Hosted and OSS, so the same JSON artifact works for all import paths.

What Is Included

The snapshot contains:

• All relational rows (profiles, domains, plans, recipes, items, workouts, metrics, etc.)
• Artifact metadata (references to photos and files)

What Is Not Included

• Artifact binary bytes are not embedded in the snapshot JSON
• Moving binary content between storage backends remains an operator workflow

Common Scenarios

Back Up Before Upgrading

npm run oss:export:snapshot -- --out "./tmp/fluent-backup-$(date +%Y%m%d).json"
git pull
docker compose --env-file .env.oss up --build

Restore to a New Host

On the old host:

npm run oss:export:snapshot -- --out "./tmp/fluent-snapshot.json"

Copy the snapshot file to the new host, then:

npm run oss:import:snapshot -- --file "./tmp/fluent-snapshot.json"
npm run oss:start -- --host 127.0.0.1 --port 8788

Migrate from Hosted to Self-Host

# Export from hosted
npm run export:snapshot:hosted -- --database fluent-hosted \
  --out "./tmp/fluent-cloud-snapshot.json"

# Import into OSS
npm run oss:import:snapshot -- --file "./tmp/fluent-cloud-snapshot.json"

# Start OSS
npm run oss:start -- --host 127.0.0.1 --port 8788

Migrate Between Storage Backends

Export from SQLite:

npm run oss:export:snapshot -- --out "./tmp/fluent-migrate.json"

Import into Postgres + S3:

npm run oss:import:snapshot -- --backend postgres-s3 \
  --file "./tmp/fluent-migrate.json"

TIP

Relational rows and artifact metadata move cleanly between backends. Artifact bytes themselves need to be migrated separately if you are changing storage backends.