In MongoDB, what does cacheSizeGB control, and how big is the WiredTiger cache if you leave it unset?
answer
- a ceiling on one memory area
- whole instance, not per database
- subtract one gigabyte, then halve
- a 256 MB floor
basics
~10 scacheSizeGB sets the maximum size of WiredTiger's internal cache. Left unset, mongod uses the larger of 256 MB and half of (RAM minus 1 GB), so a 64 GB host gets about 31.5 GB.
solid answer
~40 s`storage.wiredTiger.engineConfig.cacheSizeGB`, or `--wiredTigerCacheSizeGB` on the command line, caps the internal cache where WiredTiger keeps collection and index pages in memory. There is one such cache per `mongod`, not one per database. Unset, `mongod` computes the size at startup as the larger of 256 MB and `0.5 * (RAM - 1 GB)`: 1.5 GB on a 4 GB host, about 31.5 GB on a 64 GB host. People say "half of RAM", and the option's own help text does too, but the code subtracts the gigabyte first. The setting is not a limit on all of `mongod`'s memory: connections and index builds sit outside it, and the operating system uses free RAM as filesystem cache. You can confirm the effective value in `serverStatus` under `wiredTiger.cache`, field `maximum bytes configured`.
code
yaml · 4 linesstorage:
wiredTiger:
engineConfig:
cacheSizeGB: 16go deeper
Recall the option's job and the shape of the default: subtract 1 GB, halve it, never below 256 MB. Work the 64 GB example aloud.
Explain that the setting bounds one area of memory only, and name what sits outside it: index builds, connections and the operating system's filesystem cache.
Show you verify rather than assume: read the configured maximum back from serverStatus, and treat a surprising number as a sign that the server sees different memory than you think.
Frame the default as a sound assumption about one mongod per machine, and treat any departure from it as a decision somebody should own and write down.
## What the setting controls `storage.wiredTiger.engineConfig.cacheSizeGB` (on the command line, `--wiredTigerCacheSizeGB`) is a `mongod` option that sets the **maximum size of WiredTiger's internal cache**. WiredTiger is MongoDB's storage engine. Its internal cache is the memory where it keeps copies of recently used collection and index pages, so that it can serve them without going back to storage. Three properties of that cache come straight from the manual and surprise people who expect finer control: - **One cache per `mongod`.** WiredTiger allocates it to the entire instance, not per database or per collection. - **No split between reads and writes.** No portion is reserved for one or the other. - **No pinning.** You cannot pin documents into the cache. ## The default, as the code computes it When neither cache option is set, `WiredTigerUtil::getMainCacheSizeMB` (MongoDB 9.0.4) computes the size at startup: ```plaintext cacheSizeMB = max((memSizeMB - 1024) * 0.5, 256) ``` The result is rounded down to a whole number of megabytes. | RAM the server sees | Default cache | Why | |---|---|---| | 1 GB | 256 MB | the formula gives 0, so the floor applies | | 1.5 GB | 256 MB | the formula and the floor meet exactly here | | 2 GB | 512 MB | `(2048 - 1024) * 0.5` | | 4 GB | 1.5 GB | the manual's worked example | | 16 GB | 7.5 GB | `(16384 - 1024) * 0.5` | | 64 GB | 31.5 GB | `(65536 - 1024) * 0.5` = 32256 MB | Two details make this worth reading in the code rather than repeating from memory: - The option's help text says the cache "defaults to 1/2 of physical RAM". That is loose: on any host above the floor, the real value is 512 MB less than half. - `memSizeMB` is the RAM the server believes it has. The manual says the `hostInfo.system.memLimitMB` value, not the total system memory, is what the calculation uses, which matters inside a container. ## What the setting does not cover **`cacheSizeGB` is not a limit on `mongod`'s memory.** It bounds one area. Memory outside it includes: - connection and operation memory; - index builds, which the manual states are separate, with their own `maxIndexBuildMemoryUsageMegabytes` limit; - a separate **spill instance**, when one is present, which has its own small cache: `spillWiredTigerCacheSizePercentage` defaults to 2.5% of system memory, bounded by 100 MB and 1000 MB; - the **filesystem cache**, which belongs to the operating system rather than to `mongod` and uses whatever RAM is free. The RAM the default leaves over is therefore not wasted. The operating system uses it to keep data files in memory, and a read that misses the internal cache can often be served from there without touching the disk. It is also **a ceiling, not a reservation**. WiredTiger reads pages into the cache on demand, so a freshly started `mongod` holds little, and `bytes currently in the cache` grows towards the configured maximum as the workload touches data. A low figure right after a restart says nothing about whether the size is right. ## Setting it and checking it 1. **Leave the default unless you have a reason.** The manual's guidance is to avoid raising the cache above its default value. 2. **Lower it when something else needs the RAM**, such as a second process on the host. The default assumes one `mongod` per machine and knows nothing about your neighbours. 3. **Stay inside the valid range.** The option's validator accepts 0.25 to 10000. The manual prints the lower bound as 0.256 GB; the code's floor is 256 MB, which is 0.25 GB in 1024-based units. 4. **Restart and verify.** It is a startup option. Read the effective value back from `serverStatus`. A value above 80% of the RAM the server sees is not rejected: `mongod` starts and logs a startup warning saying the cache is more than 80% of available RAM. ```javascript db.serverStatus().wiredTiger.cache["maximum bytes configured"] ``` The field is in bytes. On a 64 GB host running the default it reads about 31.5 GB, and a value that surprises you is usually the first clue that the server is seeing a different amount of memory from the one you assumed.
- Can the WiredTiger cache size be changed without restarting mongod?`cacheSizeGB` is read at startup, so the supported route is a restart, usually rolling through a replica set. WiredTiger itself can reconfigure `cache_size` on a live connection, and `mongod` exposes that through the `wiredTigerEngineRuntimeConfig` parameter, but the manual warns against changing it unless MongoDB engineers direct you to.
- Why does the default subtract 1 GB before halving rather than simply taking half of RAM?The code comment states the rule, a minimum of 256 MB and otherwise 50% of available memory over 1 GB, without giving a reason. The practical effect is that small hosts keep proportionally more for everything else: a 2 GB host gives the cache a quarter of its RAM, not half. On big hosts the difference is only 512 MB.
- The default WiredTiger cache is exactly half of physical RAM on every host.
- cacheSizeGB caps all the memory a mongod process can use.
- Each database on a mongod gets its own slice of the WiredTiger cache.
- RAM left over beyond the default cache simply sits idle.
- Setting cacheSizeGB above 80% of RAM makes mongod refuse to start.