Persistence Mechanism

How the LocalStack persistence mechanism works and how you can configure it.

The persistence mechanism is essentially a “pause and resume” feature for your LocalStack application state. For instance, you may want to run consecutive integration tests where each test loads in a different context but depends on the state produced by a previous test. Commonly, you may simply have a local development server that relies on a non-ephemeral application state.

While the persistence mechanism covers most services, not all of them are supported yet. Please make sure to check the feature coverage page to see whether your desired services are covered.

In the past we supported a version of persistence – available in the Community version – based on a record-and-replay approach (basically, storing API calls and re-running them on restart), we discontinued this feature with 0.13.1. Therefore, please note that persistence in LocalStack, as currently intended, is a Pro only feature (more on that in the Technical Details section).

Please note that the coverage is only guaranteed for the Pro version, while the Community version attempts to restore the state on a best-effort basis using a record-and-replay approach (more on that in the Technical Details section).

To enable the persistence mechanism simply set the PERSISTENCE environment variable to 1.

  1.     ...
  2.     environment:
  3.       - LOCALSTACK_API_KEY=...
  4.       - PERSISTENCE=1
  5.     volumes:
  6.       - "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack"

Once the application has been set and configured properly, the /health endpoint of LocalStack will indicate whether the persistence mechanism has been initialized successfully.

  1. "features": {
  2.     "persistence": "initialized"
  3. }

Otherwise, the endpoint will inform you that the mechanism is disabled.

  1. "features": {
  2.     "persistence": "disabled"
  3. }

Technical Details

The persistence mechanism in LocalStack Pro is a sophisticated approach based on serialized state. Starting the Pro version of LocalStack will traverse the state directory root folder recursively and directly deserialize the file into the application state.

Typically, each service has one state file for each region.

Each serialization mechanism has its root folder. As of now, all supported services are serialized as pickle files. Particular services, in addition to their pickled files, can serialize additional artifacts. For instance, Kinesis persists some data in form of JSON while DynamoDB serializes a SQLite database. This is illustrated in the diagram below.

Structure of the state directory

Restoring the state – even for large projects – usually only takes a few milliseconds. Moreover, since the files store accurate snapshots of the application state, they can restore a state that is identical to the one before restarting the instance.

Last modified July 5, 2022: document new filesystem layout (#188) (111fa68a)