Impose A Limit On Heap Size

sqlite3_int64 sqlite3_soft_heap_limit64(sqlite3_int64 N);
sqlite3_int64 sqlite3_hard_heap_limit64(sqlite3_int64 N);

These interfaces impose limits on the amount of heap memory that will be by all database connections within a single process.

The sqlite3_soft_heap_limit64() interface sets and/or queries the soft limit on the amount of heap memory that may be allocated by SQLite. SQLite strives to keep heap memory utilization below the soft heap limit by reducing the number of pages held in the page cache as heap memory usages approaches the limit. The soft heap limit is "soft" because even though SQLite strives to stay below the limit, it will exceed the limit rather than generate an SQLITE_NOMEM error. In other words, the soft heap limit is advisory only.

The sqlite3_hard_heap_limit64(N) interface sets a hard upper bound of N bytes on the amount of memory that will be allocated. The sqlite3_hard_heap_limit64(N) interface is similar to sqlite3_soft_heap_limit64(N) except that memory allocations will fail when the hard heap limit is reached.

The return value from both sqlite3_soft_heap_limit64() and sqlite3_hard_heap_limit64() is the size of the heap limit prior to the call, or negative in the case of an error. If the argument N is negative then no change is made to the heap limit. Hence, the current size of heap limits can be determined by invoking sqlite3_soft_heap_limit64(-1) or sqlite3_hard_heap_limit(-1).

Setting the heap limits to zero disables the heap limiter mechanism.

The soft heap limit may not be greater than the hard heap limit. If the hard heap limit is enabled and if sqlite3_soft_heap_limit(N) is invoked with a value of N that is greater than the hard heap limit, the the soft heap limit is set to the value of the hard heap limit. The soft heap limit is automatically enabled whenever the hard heap limit is enabled. When sqlite3_hard_heap_limit64(N) is invoked and the soft heap limit is outside the range of 1..N, then the soft heap limit is set to N. Invoking sqlite3_soft_heap_limit64(0) when the hard heap limit is enabled makes the soft heap limit equal to the hard heap limit.

The memory allocation limits can also be adjusted using PRAGMA soft_heap_limit and PRAGMA hard_heap_limit.

The heap limits are not enforced in the current implementation if one or more of following conditions are true:

• The limit value is set to zero.
• Memory accounting is disabled using a combination of the sqlite3_config(SQLITE_CONFIG_MEMSTATUS,...) start-time option and the SQLITE_DEFAULT_MEMSTATUS compile-time option.
• An alternative page cache implementation is specified using sqlite3_config(SQLITE_CONFIG_PCACHE2,...).
• The page cache allocates from its own memory pool supplied by sqlite3_config(SQLITE_CONFIG_PAGECACHE,...) rather than from the heap.

The circumstances under which SQLite will enforce the heap limits may changes in future releases of SQLite.

See also lists of Objects, Constants, and Functions.