Features

If your data fits in RAM, you can write your system as a pure Clojure function, without any database complexity. It will be much simpler, cleaner and orders of magnitude faster.

Prevayler takes care of persistence.

Usage

• Get enough RAM to hold all your data.
• Implement the business logic of your system as a pure event handling function. Keep any I/O logic (accessing some web service, for example) separate.
• Guarantee persistence by applying all events to you system through Prevayler, like this:

(defn my-system [state event]            
  ...)                                   ; Any function returning a pair [new-state event-result].

(with-open [p1 (prevayler! my-system)]
  (assert (= @p1 {}))                    ; The default initial state is an empty map.
  (handle! p1 event1)                    ; Your events can be any Clojure value or Serializable object.
  (handle! p1 event2)
  (assert (= @p1 new-state)))            ; Your system state with the events applied.

(with-open [p2 (prevayler! my-system)]   ; Next time you run,
  (assert (= @p2 new-state)))            ; the state is recovered, even if there was a system crash.

What it Does

Prevayler-clj implements the system prevalence pattern: it keeps a snapshot of your business system state followed by a journal of events. On startup or crash recovery it reads the last state and reapplies all events since: your system is restored to where it was.

Shortcomings

• RAM: Requires enough RAM to hold all the data in your system.
• Start-up time: Entire system is read into RAM.

Files

Prevayler's default file name is journal but you can pass in your own file. Prevayler-clj will create and write to it like this:

journal

Contains the state at the moment your system was last started, followed by all events since. Serialization is done using Nippy.

journal.backup

On startup, the journal is renamed to journal.backup and a new journal file is created. This new journal will only be consistent after the system state has been written to it so when journal.backup exists, it takes precedence over journal.

journal.backup-[timestamp]

After a new consistent journal is written, journal.backup is renamed with a timestamp appendix. You can keep these old versions elsewhere if you like. Prevayler no longer uses them.

S3 Storage [EXPERIMENTAL]

You can also tell Prevayler to store the journal and its backups in an S3 bucket. You can use the prevayler-s3/prevayler! function instead. This function takes a handler and a map of parameters. They are as follows:

{
    :bucket "s3-bucket-name"
    :file "name-of-journal-file" ; (defaults to "journal")
    :initial-state some-value    ; (defaults to {})
    :debug? boolean              ; print debug output? (defaults to false)
    :dbg-out (fn [msg])          ; (defaults to fn that prints with date)
    :sleep-time some-int         ; time to sleep between S3 uploads 
                                 ; (in ms; defaults to 1000; minimum 0)
}

For example:

(s3/prevayler! handler :bucket "my-bucket")

Important notes -- S3 synchronization happens in a background thread, which could run up to 1 second behind. It is possible that, if your application shuts down unexpectedly right after a persistence change, you will lose data.

This can be tuned using the :sleep-time parameter, allowing you to trade off CPU usage for upload latency.

We're thinking about alternatives to this. Current thoughts: * Text-based transaction log that gets uploaded? Won't work so well for machines (like EC2 instances) that have no persistent disk. * A mode where we block writes inline? This is very slow (100-800 ms per transaction).

Transient Mode for Tests

The transient-prevayler! function returns a transient prevayler the you can use for fast testing.

Encryption At Rest

If you give the prevayler! function an encryption and decryption cipher (javax.crypto.Cipher, both already initialized), then the journal files will be encrypted and decrypted with the given ciphers.

---

"Simplicity is prerequisite for reliability." Dijkstra (1970)