Caching

ThingsBoard caches frequently accessed data — device credentials, entity profiles, attributes, sessions — to avoid hitting the database on every message. Since the platform validates device credentials on every incoming telemetry message, the cache is critical for throughput: without it, every MQTT publish or HTTP POST triggers a database query.

Set the cache backend with the CACHE_TYPE environment variable:

With Caffeine, each node maintains its own independent cache. Cache invalidations are broadcast between cluster nodes via the message queue, but there’s a brief window where different nodes may serve stale data. Redis eliminates this issue — all nodes read from the same shared store.

ThingsBoard maintains separate cache namespaces, each with its own TTL and size limit. The most performance-critical caches are listed first:

The Attributes and TS Latest caches have the largest default size (100,000 entries) because dashboards and rule chains query these values constantly. Enable or disable them independently with CACHE_ATTRIBUTES_ENABLED and CACHE_TS_LATEST_ENABLED (both true by default).

Every cache namespace has two environment variables:

• CACHE_SPECS_{NAME}_TTL — time-to-live in minutes (how long an entry stays in cache after being written)
• CACHE_SPECS_{NAME}_MAX_SIZE — maximum number of entries (evicts least-recently-used when full)

For example, to adjust the device credentials cache:

CACHE_SPECS_DEVICE_CREDENTIALS_TTL=2880
CACHE_SPECS_DEVICE_CREDENTIALS_MAX_SIZE=50000

Sizing rules of thumb:

• Set MAX_SIZE to at least the number of active entities of that type. For device credentials, this should be ≥ total device count.
• TTL of 1440 minutes (24 hours) works for most deployments. Reduce TTL if you frequently update device credentials or profiles and need changes to take effect faster.
• Monitor cache hit ratios in logs. Low hit ratios on the credentials or sessions cache mean the cache is too small and entities are being evicted before they’re accessed again.

When using CACHE_TYPE=redis, configure the Redis connection based on your deployment topology:

A single Redis instance. Suitable for development and small production setups.

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

Redis Cluster shards data across multiple nodes. Use for large deployments where a single Redis instance cannot hold the entire cache.

All modes support SSL/TLS via TB_REDIS_SSL_ENABLED=true and optional client certificate authentication.

ThingsBoard uses a connection pool to manage Redis connections efficiently. The pool is configured per ThingsBoard node:

For the complete list of cache and Redis environment variables, see Configuration Reference.