Skip to main content

NATS JetStream Persistence & Backup

Framework M uses NATS as its primary Event Bus. For production environments, it is essential to enable JetStream persistence to ensure messages are not lost during server restarts.

1. Enabling JetStream Persistence​

Ensure your NATS server configuration (typically nats.conf) includes the jetstream block.

jetstream {
    # Store data on disk
    store_dir = "/data/nats-jetstream"
    
    # Optional: Max memory and disk usage (adjust based on your server capacity)
    max_memory = 1G
    max_disk = 10G
}

In Kubernetes, use a PersistentVolumeClaim (PVC) to allow the store_dir to survive pod restarts.

2. Framework-M Configuration​

When using the Framework M NATS adapter, ensure the following environment variables are set to leverage JetStream:

EVENT_BUS_ADAPTER=framework_m_standard.adapters.event_bus.nats.NatsEventBus
NATS_URL=nats://nats:4222
NATS_JETSTREAM=True

3. Backing Up NATS State​

While NATS stores data on disk, standard filesystem-level backups might be inconsistent if the server is running.

3.1 JetStream Backup Utility​

NATS provides a built-in CLI for backing up streams.

  • Process: Periodically run the nats str backup command for each critical stream (e.g., DOC_EVENTS).
  • Automation: Use a CronJob to run the backup and push the resulting files to S3/GCS.
# Backup a specific stream
nats str backup DOC_EVENTS /backups/nats/doc_events_$(date +%F)

3.2 Restore Process​

Restoring a stream requires stopping the producer (the Framework M app) to ensure consistency.

# Restore a stream from backup
nats str restore /backups/nats/doc_events_2026-03-15

4. High Availability (Replication)​

For mission-critical deployments, configure NATS in a Cluster with a Replication Factor (R) of 3. This ensures that even if one NATS node fails, the JetStream data remains available and consistent across the remaining nodes.