Developer best practices: Storage
There are two forms of storage available to ICP canisters: heap memory and stable memory.
Heap memory is a canister's Wasm memory. This memory does not store data long-term. The heap memory is cleared each time a canister is upgraded. Heap memory is limited to 4GiB. It is used by default for data such as variable values, arguments passed to a canister, and the result of a method's execution.
Stable memory is a secondary storage type that is used to store data long-term. Stable memory data is persisted throughout the canister's lifetime, including canister upgrades. Stable memory is limited to 500GiB. To use stable memory, you must anticipate which data you want to persist across different canister processes and states.
| Memory feature | Heap memory | Stable memory |
|---|---|---|
| Storage capacity | 4GiB | 500GiB |
| Intended use | Small datasets, frequently accessed data, temporary data | Large datasets, infrequently accessed data, important data that must persist |
| Persistence | Does not persist across upgrades | Data is preserved and persists across upgrades |
| Performance | Fast read/write operations | Slightly decreased read/write operations |
Learn more about canister storage.
Storage best practices
Recommendation: Use stable memory directly.
It is recommended to use stable memory directly, such as through stable structures, for any data that is important. Linking data to your canister's Wasm binary and using pre/post upgrade hooks can be extremely risky. There are several areas for potential errors or bugs that can result in data loss.
Recommendation: Use heap memory for small datasets.
Heap data is better suited to be used for small data sets (under 4GiB) or data that is frequently accessed and not necessary for long-term persistence.
Recommendation: Use stable memory for large datasets.
Stable memory should be used for large data sets (more than 4GiB but less than 500GiB) or data that is infrequently accessed.
Ultimately, the form of memory you choose to utilize for your canister will depend on the most optimal workflow for your project.