Backup & Restore

Fluent's open-source runtime supports snapshot-based backup and restore. The snapshot format is JSON and is compatible across Fluent environments, so you can move data between self-hosted instances, import from early access, 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 Early Access

Export your data from the managed 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 Early Access Into A Self-Hosted Runtime

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

The snapshot format is aligned between early access and the open-source runtime, 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 Early Access To Self-Host

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

# Import into the open-source runtime
npm run oss:import:snapshot -- --file "./tmp/fluent-cloud-snapshot.json"

# Start the open-source runtime
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.