Performance & Platform Cache

Platform Cache is a performance layer—not a source of truth

JSBC Labs6 October 20268 min read

Speed does not create authority

Platform Cache can reduce repeated SOQL, expensive calculations and remote lookups by keeping reusable values in memory across transactions. That is a meaningful architectural tool on Salesforce, where database, CPU and integration consumption are shared budgets. It can protect a busy dependency and improve response time without forcing every request to repeat the same work.

The JSBC Labs position is simple: cache is a performance copy, never the sole authority for a business fact. Salesforce describes cached data as non-durable and capable of being evicted when space is constrained. If a missing key changes an approval, loses an entitlement or forgets completed work, the design has confused acceleration with persistence.

Start with the access pattern

Do not begin by asking how much cache to allocate. Measure what is repeatedly accessed, how expensive the authoritative read is, how often the value changes and what stale data would cost. Good candidates are read far more often than they change: reference data, validated configuration, describe-like results or calculations whose inputs are stable for a known window.

Poor candidates include transaction status, financial balances, security decisions requiring current data, retry ownership and any value that must survive eviction. A frequently changing shared record can also create race conditions that make a cache slower to reason about than the original query. The cache decision should follow a workload profile and correctness tolerance, not a generic performance checklist.

Choose org or session scope deliberately

An org cache is shared across users in the org, which suits common reference values and results that are not user-specific. A session cache belongs to an individual user session and suits short-lived preferences or computations tied to that session. Choosing the wrong scope can either destroy reuse or expose one user's derived context to another.

State the scope in the design contract. For every key, document who may read it, which identity produced it and whether sharing or permission differences affect the value. Never place permission-filtered query results in an org-wide entry unless the cached representation is safe for every consumer. Performance optimisation does not suspend Salesforce's security model or your data-classification duties.

A cache miss is normal behaviour

Applications often implement the happy path—`get` returns a value—and treat a miss as an infrastructure failure. Salesforce guidance is explicit that cached data may be evicted and application code must handle the miss. Capacity may also differ across environments. A correct application must behave correctly when the cache is empty, cold or unavailable for the requested key.

Define the miss path first: read from the durable source, validate the result, place an appropriate representation in cache and return the same business outcome. Prevent a popular missing key from causing hundreds of simultaneous requests to stampede the underlying database or service. Where a fallback is expensive, coordinate population, apply bounded retries and degrade a non-critical feature rather than inventing data.

Invalidation is the actual design

Time to live is not an invalidation strategy by itself. A long expiry improves hit rate but lengthens the stale-data window; a short expiry reduces staleness but may return little benefit. Set expiry from business volatility and tolerance: ask how long the application may safely use the previous value after the source changes, then verify the workload still benefits.

For material changes, remove or replace affected keys through an explicit write path. Map every source mutation to the entries it invalidates, including aggregates and alternate lookup keys. If that dependency graph is unknowable, the cache model is too broad. Salesforce Well-Architected guidance specifically warns against caching without an invalidation strategy; naming a TTL does not resolve unknown dependencies.

Commit durable state before refreshing cache

Writing a new cache value inside the same transaction as database changes creates a subtle risk: the transaction can later roll back while the cache retains a value that never became authoritative. Salesforce engineering guidance recommends committing the database change, then clearing and refreshing the cached representation after commit where the pattern requires write-through behaviour.

Prefer invalidation over clever synchronisation when correctness matters. Removing a key lets the next reader rebuild from committed state and narrows the chance of two writers racing to publish different versions. Where asynchronous post-commit refresh is used, make it idempotent and preserve the ordinary miss fallback. The durable source must remain capable of repairing the cache without manual intervention.

Keys and payloads are architecture

A key such as `settings` or `accounts` has no useful boundary. Include the domain, schema version and dimensions that genuinely change the result—perhaps region, language or policy version—without embedding sensitive data. Versioned keys let a deployment introduce a new payload safely and retire the old representation after consumers have moved.

Keep payloads smaller than the authoritative model and store only what readers need. Large sObject graphs waste capacity, preserve fields longer than intended and couple consumers to database shape. Prefer a purpose-built, serialisable value with an explicit version. Validate data before caching it; a fast corrupt value merely spreads an error across more transactions.

Prevent stale security and privacy decisions

User access, consent, account status and fraud controls can change faster than a convenient cache window. Before caching any decision, classify the consequence of serving an older value. Low-risk presentation hints may tolerate staleness. Authorisation and regulated processing usually need a fresh evaluation or a deliberately short-lived, fail-closed representation tied to the correct principal.

Do not use obscurity of a key as protection. Limit cached content to the minimum data classification the scope permits, and avoid secrets or unnecessary personal information. Include security-change events in the invalidation design. Test with two users who have different sharing and permissions; a cache that makes the first user's result visible to the second is a data exposure, not a performance defect.

Measure benefit and correctness together

A high hit rate can still hide a bad cache. Track hits, misses, fallback duration, source-call reduction, payload size, population failures and invalidations. Pair these with correctness signals: stale-value incidents, version mismatches and outcomes rebuilt after a miss. Segment by key family so one popular entry does not disguise a wasteful or dangerous set of rarely reused values.

Use those measurements to allocate partitions and tune expiry rather than guessing. Salesforce provides separate org and session capacity within partitions, and its architecture guidance recommends matching TTL to volatility. Additional capacity cannot repair the wrong scope, poor keys or absent invalidation. Buy or allocate more only after evidence shows a valuable workload is being constrained by space.

Prove the empty-cache system first

Test with no entries, expired entries, invalid payload versions, concurrent misses and source failures. Confirm that durable state produces the same business answer with or without cache. Exercise updates followed immediately by reads, transaction rollback and permission changes. Performance tests should compare source load and latency at realistic concurrency, not only show that a single cached request is fast.

Roll out one measurable key family at a time with a rapid disable path. Platform Cache is valuable precisely because it can absorb repetitive work without redesigning the source of truth. Preserve that separation: durable systems own facts, services own validation and the cache owns temporary copies. When eviction is routine rather than catastrophic, the optimisation is finally safe enough to scale.