|
| 1 | +--- |
| 2 | +title: Cache |
| 3 | +description: Configuration for internal and output caching. |
| 4 | +--- |
| 5 | + |
| 6 | +:partial{content="config-env-vars"} |
| 7 | + |
| 8 | +Directus has a built-in data-caching option. Enabling this will cache the output of requests (based on the current user |
| 9 | +and exact query parameters used) into configured cache storage location. This drastically improves API performance, as |
| 10 | +subsequent requests are served straight from this cache. Enabling cache will also make Directus return accurate |
| 11 | +cache-control headers. Depending on your setup, this will further improve performance by caching the request in |
| 12 | +middleman servers (like CDNs) and even the browser. |
| 13 | + |
| 14 | +::callout{icon="material-symbols:info-outline"} |
| 15 | +**Internal Caching** |
| 16 | +In addition to data-caching, Directus also does some internal caching. Note `CACHE_SCHEMA` which is enabled by default. |
| 17 | +This speed up the overall performance of Directus, as we don't want to introspect the whole database on every request. |
| 18 | +:: |
| 19 | + |
| 20 | +::callout{icon="material-symbols:info-outline"} |
| 21 | +**Assets Cache** |
| 22 | +`Cache-Control` and `Last-Modified` headers for the `/assets` endpoint are separate from the regular data-cache. |
| 23 | +`Last-Modified` comes from `modified_on` DB field. This is useful as it's often possible to cache assets for far longer |
| 24 | +than you would cache database content. To learn more, see [Files](/configuration/files). |
| 25 | +:: |
| 26 | + |
| 27 | +| Variable | Description | Default Value | |
| 28 | +| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | |
| 29 | +| `CACHE_ENABLED` | Whether or not data caching is enabled. | `false` | |
| 30 | +| `CACHE_TTL`<sup>[1]</sup> | How long the data cache is persisted. | `5m` | |
| 31 | +| `CACHE_CONTROL_S_MAXAGE` | Whether to not to add the `s-maxage` expiration flag. Set to a number for a custom value. | `0` | |
| 32 | +| `CACHE_AUTO_PURGE`<sup>[2]</sup> | Automatically purge the data cache on actions that manipulate the data. | `false` | |
| 33 | +| `CACHE_AUTO_PURGE_IGNORE_LIST`<sup>[3]</sup> | List of collections that prevent cache purging when `CACHE_AUTO_PURGE` is enabled. | `directus_activity,directus_presets` | |
| 34 | +| `CACHE_SYSTEM_TTL`<sup>[4]</sup> | How long `CACHE_SCHEMA` is persisted. | -- | |
| 35 | +| `CACHE_SCHEMA`<sup>[4]</sup> | Whether or not the database schema is cached. One of `false`, `true` | `true` | |
| 36 | +| `CACHE_SCHEMA_MAX_ITERATIONS`<sup>[4]</sup> | Safe value to limit max iterations on get schema cache. This value should only be adjusted for high scaling applications. | `100` | |
| 37 | +| `CACHE_SCHEMA_SYNC_TIMEOUT` | How long to wait for other containers to message before trying again | `10000` | |
| 38 | +| `CACHE_SCHEMA_FREEZE_ENABLED` | Whether or not to freeze the schema to improve memory efficiency | false | |
| 39 | +| `CACHE_NAMESPACE` | How to scope the cache data. | `system-cache` | |
| 40 | +| `CACHE_STORE`<sup>[5]</sup> | Where to store the cache data. Either `memory`, `redis`. | `memory` | |
| 41 | +| `CACHE_STATUS_HEADER` | If set, returns the cache status in the configured header. One of `HIT`, `MISS`. | -- | |
| 42 | +| `CACHE_VALUE_MAX_SIZE` | Maximum size of values that will be cached. Accepts number of bytes, or human readable string. Use `false` for no limit | false | |
| 43 | +| `CACHE_SKIP_ALLOWED` | Whether requests can use the Cache-Control header with `no-store` to skip data caching. | false | |
| 44 | +| `CACHE_HEALTHCHECK_THRESHOLD` | Healthcheck timeout threshold in ms. | `150` | |
| 45 | + |
| 46 | +<sup>[1]</sup> `CACHE_TTL` Based on your project's needs, you might be able to aggressively cache your data, only |
| 47 | +requiring new data to be fetched every hour or so. This allows you to squeeze the most performance out of your Directus |
| 48 | +instance. This can be incredibly useful for applications where you have a lot of (public) read-access and where updates |
| 49 | +aren't real-time (for example a website). `CACHE_TTL` uses [`ms`](https://www.npmjs.com/package/ms) to parse the value, |
| 50 | +so you configure it using human readable values (like `2 days`, `7 hrs`, `5m`). |
| 51 | + |
| 52 | +<sup>[2]</sup> `CACHE_AUTO_PURGE` allows you to keep the Directus API real-time, while still getting the performance |
| 53 | +benefits on quick subsequent reads. |
| 54 | + |
| 55 | +<sup>[3]</sup> The cache has to be manually cleared when requiring to access updated results for collections in |
| 56 | +`CACHE_AUTO_PURGE_IGNORE_LIST`. |
| 57 | + |
| 58 | +<sup>[4]</sup> Not affected by the `CACHE_ENABLED` value. |
| 59 | + |
| 60 | +<sup>[5]</sup> `CACHE_STORE` For larger projects, you most likely don't want to rely on local memory for caching. |
| 61 | +Instead, you can use the above `CACHE_STORE` environment variable to use `redis` as the cache store. |
0 commit comments