Using MuleSoft Object Store for Caching: What Persistent Really Means

Object Store in MuleSoft is a great option when you need lightweight key-value storage for caching, rate limiting, deduplication, or managing temporary state. But here’s the thing: the way Object Store behaves, especially when persistent="true", depends entirely on your deployment model.

This post unpacks how to properly choose and use the proper Object Store for caching in your apps, and what to expect when deploying to CloudHub, RTF, or on-prem.

What is the Object Store?

MuleSoft has different types of Object Stores, and it can be confusing to understand which should be used for different use-cases.

Anypoint Object Store V2 (OSv2)

Object Store V2 is the latest version of CloudHub Object Store. This is a Cloud Service that is external to the Mule Application. It is only used by CloudHub deployed applications.

Mule Object Store

Mule Object Store is the original on-premise based Object Store that is part of Mule Runtime. Different to the above, this one is fully customisable to user preferences, can be “in-memory” for fast performance, or “persistent” on disk for reliability and is not a Cloud service.

Object Store Connector

The same Mule Object Store Connector can be used for the two object stores and is the recommended method to write and read key:values to Object Stores. You configure the Object Store Connector with the following key config options:

<os:object-store name="myCache" persistent="true" maxEntries="1000" entryTtl="300000" />

Let’s break down persistent=true 👇

What Does persistent="true" Actually Do?

In persistent mode, Mule attempts to persist data to disk or external backing store.

In non-persistent mode, data is stored in memory only, lost on redeploy/restart.

BUT… the real behavior depends on where you’re deploying.

Deployment Models and What persistent="true" Really Means

☁️ CloudHub (2.0)

• Uses Object Store v2 behind the scenes.
• persistent="true" stores data in the Object Store v2 service, backed by durable cloud storage (AWS Dynamo DB).
• Data persists across restarts, redeploys, and even horizontal scaling (replicas).
• No local file system access. Persistence is managed by MuleSoft.

Source: https://docs.mulesoft.com/object-store/

Best case for using Object Store as a distributed, resilient cache.

🏗️ Runtime Fabric (RTF)

The Mule Object Store is supported in Runtime Fabric, however CloudHub Object Store v1 and Anypoint Object Store v2 are not supported.

However, RTF does support the use of a Persistence Gateway to enable persistent object storage. This feature is available in RTF version 1.9.0 or later. The Persistence Gateway allows Mule applications to use the Object Store v2 REST API via the Object Store Connector, enabling persistent storage backed by an external PostgreSQL database.

Key considerations:

• Persistence Gateway Configuration: To utilize persistent object storage in RTF, you must configure the Persistence Gateway with a compatible PostgreSQL database. Ensure that the database is set up correctly and that the necessary Kubernetes custom resources are created to connect the cluster to your persistence data store. MuleSoft Documentation
• Data Retention: The Persistence Gateway stores data for a maximum TTL (Time To Live) of 30 days. After this period, data will be automatically cleaned up.
• Application Configuration: When deploying applications to RTF, you can select the “Use Persistent Object Storage” option in Runtime Manager to enable persistent storage via the configured Persistence Gateway.

Important: Without the Persistence Gateway configured, the persistent="true" setting will not provide true persistence in RTF. Therefore, it's crucial to set up the Persistence Gateway correctly to achieve the desired persistent caching behavior.

🖥️ On-Premises (Standalone Mule)

• Default behavior is Mule Object Store unless configured otherwise.
• persistent="true" will write data to the local file system (e.g., under .mule/ directory).
• Data survives restarts of the Mule runtime but:
• Not shared across clustered nodes.
• Lost if you redeploy or clean up the app folder.

OK for local development or single-node setups. Not recommended for shared cache in multi-node or clustered environments.

Pro Tips for Using Object Store as Cache

1. Set TTLs (entryTtl): Avoid stale data and memory bloat.
2. Use maxEntries: Prevent unbounded growth.
3. Externalize Object Store logic: Wrap access in a flow or reusable module.
4. Use CloudHub with OSv2 for production: Best reliability and scaling.
5. Use persistent mode for cold restarts, not long-term storage.

Test It Before You Trust It

• In CloudHub, restart the app and validate the cache still works.
• In RTF or on-prem, simulate restarts or redeploys to test data persistence.
• Watch out for Object Store v2 quotas (based on your MuleSoft plan).

Summary

The way Object Store behaves, especially when persistent="true",depends entirely on your deployment model.

Source: https%3A%2F%2Fdocs.mulesoft.com%2Fruntime-manager%2Fdeployment-strategies

Final Thoughts

Using Object Store as a cache in MuleSoft is simple, but context is everything. What works great on CloudHub might fail silently on-prem if you’re expecting shared persistence. Understand your deployment architecture before relying on Object Store for anything beyond basic caching.

Thanks to Germán Corbetta for his valuable insights and support during the troubleshooting of this topic on a real-world project.

References

The Different Types of Object Stores Explained

Using ObjectStoreV2

Deployment Strategies

Object Store Feature Support in MuleSoft Runtime Fabric

Configuring Persistence Gateway with Runtime Fabric