Docs/Platform/Persistence & Retention

Persistence & Retention

Embedded SQLite durability, message retention, maintenance, and backup.

Incoming HL7 messages are persisted before processing. FireSonic uses SQLite as the default embedded persistence layer to provide local durability, restart recovery, and operational simplicity without requiring an external database server.

Persistence model

The persistence layer sits between message intake and asynchronous processing. Persisting first reduces the risk of message loss during application restarts, processing failures, or downstream FHIR outages.

HL7 receivedAccepted from MLLP

PersistedStored locally

ProcessedStatus tracked

RetainedHistory & recovery

PurgedBy retention policy

Persistence responsibilities

Durable message storage.
Processing state tracking and message history.
Restart recovery and retry workflows.
Operational diagnostics.

Storage requirements

The SQLite database should remain on local storage attached to the same system where FireSonic runs.

Local disk required

Do not place db.path on NFS, SMB, NAS-mounted shares, shared drives, or other remote/network filesystems.

For production deployments, use a server-grade SSD with power-loss protection (PLP), sufficient write endurance (DWPD/TBW), and hardware error-correction capabilities.

db.path=./data/fs.db

Payload protection

HL7 payloads can be compressed before encryption and persistence. Compression reduces database and backup size, while the configured encryption key protects persisted healthcare data at rest.

payload.compression.enabled=true
payload.crypto.keys.k1.password=${FS_PAYLOAD_KEY}

Critical

Losing payload.crypto.keys.k1.password makes encrypted persisted payloads unrecoverable. Store the secret securely and include it in your disaster-recovery plan.

Default retention

Retention is status-aware. Successfully processed or intentionally filtered messages are normally needed for a shorter operational window, while failed and rejected messages are retained longer because they are important for troubleshooting and recovery.

Message status	Default retention	Reason
PROCESSED	7 days	Recent operational history after successful delivery.
FILTERED	3 days	Short history for intentionally ignored messages.
REJECTED, DELIVERY_FAILED, PROCESSING_FAILED	30 days	Longer window for investigation, correction, and retry.

retention.processed.days=7
retention.filtered.days=3
retention.failed.days=30
retention.purge.interval.minutes=60

The maintenance service periodically removes expired records according to these values. Configure retention according to expected message volume, troubleshooting requirements, and available disk capacity.

Backup

FireSonic includes scheduled SQLite backup support. Backups are created using the database backup/compact mechanism rather than a raw copy of the live database file.

Property / capability	Default	Purpose
`backup.enabled`	`false`	Enable scheduled database backups.
`backup.interval.hours`	`24`	Interval between backup runs.
`backup.directory`	`./backup`	Local directory where backup files are written.
`backup.retention.count`	`7`	Number of local backup files to retain.
`backup.compress`	`true`	GZIP-compress backup files.
`backup.external.directory`	empty	Copy backups to an external mounted destination such as a mounted disk, NAS, NFS share, or SMB share.

Storage and operational guidance

Keep the live SQLite database on local server storage.
Use server-grade SSD storage for production workloads.
Configure a strong payload encryption secret and back it up securely.
Keep retention periods appropriate for message volume and available disk capacity.
Enable scheduled backups and verify that backup files are usable.
For commercial deployments, use an external backup destination when a second storage location is required.
Monitor database growth, backup growth, and retention behavior over time.