Caching

ThingsBoard Edge caches frequently accessed data — device credentials, entity profiles, attributes, and active sessions — to avoid a database query on every incoming message. Because Edge validates device credentials on every MQTT publish or HTTP POST, the cache is the primary factor in per-message throughput.

Set the cache backend with the CACHE_TYPE environment variable:

With Caffeine, the cache lives in the JVM heap of the Edge process. Because Edge typically runs on hardware with limited RAM — 512 MB to 4 GB — size each cache namespace conservatively. Every entry stays in memory until it expires or is evicted by the LRU policy.

ThingsBoard Edge maintains separate cache namespaces, each with its own TTL and size limit.

The Attributes and TS latest caches have the largest default size (100,000 entries) because dashboards and rule chains read these values on every refresh. Disable them with CACHE_ATTRIBUTES_ENABLED=false and CACHE_TS_LATEST_ENABLED=false if you need to reclaim heap memory, at the cost of more frequent PostgreSQL reads.

Every cache namespace exposes two environment variables:

• CACHE_SPECS_{NAME}_TTL — time-to-live in minutes. An entry is evicted from cache this many minutes after it was written.
• CACHE_SPECS_{NAME}_MAX_SIZE — maximum entry count. When full, the least-recently-used entry is evicted.

For example, to double the device credentials cache capacity:

CACHE_SPECS_DEVICE_CREDENTIALS_TTL=1440
CACHE_SPECS_DEVICE_CREDENTIALS_MAX_SIZE=20000

Sizing guidance for Edge hardware:

• Set MAX_SIZE for device credentials and sessions to at least the total number of devices connected to this Edge instance.
• On hardware with under 1 GB RAM, reduce the Attributes and TS latest max sizes from 100,000 to 10,000–20,000 to limit heap pressure.
• Monitor the cache hit ratio in Edge logs. A hit ratio below 90% on the credentials or sessions cache means entries are being evicted before they can be reused — increase the cache size or reduce the number of active devices per Edge instance.

When CACHE_TYPE=redis, configure the connection to your Redis or Valkey server.

Redis Sentinel provides automatic failover. Edge connects to the sentinel nodes, which direct it to the current master.