1.Dd January 24, 2024 2.Dt SQLITE_DBSTATUS_LOOKASIDE_USED 3 3.Os 4.Sh NAME 5.Nm SQLITE_DBSTATUS_LOOKASIDE_USED , 6.Nm SQLITE_DBSTATUS_CACHE_USED , 7.Nm SQLITE_DBSTATUS_SCHEMA_USED , 8.Nm SQLITE_DBSTATUS_STMT_USED , 9.Nm SQLITE_DBSTATUS_LOOKASIDE_HIT , 10.Nm SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE , 11.Nm SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL , 12.Nm SQLITE_DBSTATUS_CACHE_HIT , 13.Nm SQLITE_DBSTATUS_CACHE_MISS , 14.Nm SQLITE_DBSTATUS_CACHE_WRITE , 15.Nm SQLITE_DBSTATUS_DEFERRED_FKS , 16.Nm SQLITE_DBSTATUS_CACHE_USED_SHARED , 17.Nm SQLITE_DBSTATUS_CACHE_SPILL , 18.Nm SQLITE_DBSTATUS_MAX 19.Nd status parameters for database connections 20.Sh SYNOPSIS 21.In sqlite3.h 22.Fd #define SQLITE_DBSTATUS_LOOKASIDE_USED 23.Fd #define SQLITE_DBSTATUS_CACHE_USED 24.Fd #define SQLITE_DBSTATUS_SCHEMA_USED 25.Fd #define SQLITE_DBSTATUS_STMT_USED 26.Fd #define SQLITE_DBSTATUS_LOOKASIDE_HIT 27.Fd #define SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE 28.Fd #define SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL 29.Fd #define SQLITE_DBSTATUS_CACHE_HIT 30.Fd #define SQLITE_DBSTATUS_CACHE_MISS 31.Fd #define SQLITE_DBSTATUS_CACHE_WRITE 32.Fd #define SQLITE_DBSTATUS_DEFERRED_FKS 33.Fd #define SQLITE_DBSTATUS_CACHE_USED_SHARED 34.Fd #define SQLITE_DBSTATUS_CACHE_SPILL 35.Fd #define SQLITE_DBSTATUS_MAX 36.Sh DESCRIPTION 37These constants are the available integer "verbs" that can be passed 38as the second argument to the 39.Fn sqlite3_db_status 40interface. 41.Pp 42New verbs may be added in future releases of SQLite. 43Existing verbs might be discontinued. 44Applications should check the return code from 45.Fn sqlite3_db_status 46to make sure that the call worked. 47The 48.Fn sqlite3_db_status 49interface will return a non-zero error code if a discontinued or unsupported 50verb is invoked. 51.Bl -tag -width Ds 52.It SQLITE_DBSTATUS_LOOKASIDE_USED 53This parameter returns the number of lookaside memory slots currently 54checked out. 55.It SQLITE_DBSTATUS_LOOKASIDE_HIT 56This parameter returns the number of malloc attempts that were satisfied 57using lookaside memory. 58Only the high-water value is meaningful; the current value is always 59zero. 60.It SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE 61This parameter returns the number malloc attempts that might have been 62satisfied using lookaside memory but failed due to the amount of memory 63requested being larger than the lookaside slot size. 64Only the high-water value is meaningful; the current value is always 65zero. 66.It SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL 67This parameter returns the number malloc attempts that might have been 68satisfied using lookaside memory but failed due to all lookaside memory 69already being in use. 70Only the high-water value is meaningful; the current value is always 71zero. 72.It SQLITE_DBSTATUS_CACHE_USED 73This parameter returns the approximate number of bytes of heap memory 74used by all pager caches associated with the database connection. 75The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 760. 77.It SQLITE_DBSTATUS_CACHE_USED_SHARED 78This parameter is similar to DBSTATUS_CACHE_USED, except that if a 79pager cache is shared between two or more connections the bytes of 80heap memory used by that pager cache is divided evenly between the 81attached connections. 82In other words, if none of the pager caches associated with the database 83connection are shared, this request returns the same value as DBSTATUS_CACHE_USED. 84Or, if one or more or the pager caches are shared, the value returned 85by this call will be smaller than that returned by DBSTATUS_CACHE_USED. 86The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED_SHARED 87is always 0. 88.It SQLITE_DBSTATUS_SCHEMA_USED 89This parameter returns the approximate number of bytes of heap memory 90used to store the schema for all databases associated with the connection 91- main, temp, and any ATTACH-ed databases. 92The full amount of memory used by the schemas is reported, even if 93the schema memory is shared with other database connections due to 94shared cache mode being enabled. 95The highwater mark associated with SQLITE_DBSTATUS_SCHEMA_USED is always 960. 97.It SQLITE_DBSTATUS_STMT_USED 98This parameter returns the approximate number of bytes of heap and 99lookaside memory used by all prepared statements associated with the 100database connection. 101The highwater mark associated with SQLITE_DBSTATUS_STMT_USED is always 1020. 103.It SQLITE_DBSTATUS_CACHE_HIT 104This parameter returns the number of pager cache hits that have occurred. 105The highwater mark associated with SQLITE_DBSTATUS_CACHE_HIT is always 1060. 107.It SQLITE_DBSTATUS_CACHE_MISS 108This parameter returns the number of pager cache misses that have occurred. 109The highwater mark associated with SQLITE_DBSTATUS_CACHE_MISS is always 1100. 111.It SQLITE_DBSTATUS_CACHE_WRITE 112This parameter returns the number of dirty cache entries that have 113been written to disk. 114Specifically, the number of pages written to the wal file in wal mode 115databases, or the number of pages written to the database file in rollback 116mode databases. 117Any pages written as part of transaction rollback or database recovery 118operations are not included. 119If an IO or other error occurs while writing a page to disk, the effect 120on subsequent SQLITE_DBSTATUS_CACHE_WRITE requests is undefined. 121The highwater mark associated with SQLITE_DBSTATUS_CACHE_WRITE is always 1220. 123.It SQLITE_DBSTATUS_CACHE_SPILL 124This parameter returns the number of dirty cache entries that have 125been written to disk in the middle of a transaction due to the page 126cache overflowing. 127Transactions are more efficient if they are written to disk all at 128once. 129When pages spill mid-transaction, that introduces additional overhead. 130This parameter can be used help identify inefficiencies that can be 131resolved by increasing the cache size. 132.It SQLITE_DBSTATUS_DEFERRED_FKS 133This parameter returns zero for the current value if and only if all 134foreign key constraints (deferred or immediate) have been resolved. 135The highwater mark is always 0. 136.El 137.Pp 138.Sh IMPLEMENTATION NOTES 139These declarations were extracted from the 140interface documentation at line 8652. 141.Bd -literal 142#define SQLITE_DBSTATUS_LOOKASIDE_USED 0 143#define SQLITE_DBSTATUS_CACHE_USED 1 144#define SQLITE_DBSTATUS_SCHEMA_USED 2 145#define SQLITE_DBSTATUS_STMT_USED 3 146#define SQLITE_DBSTATUS_LOOKASIDE_HIT 4 147#define SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE 5 148#define SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL 6 149#define SQLITE_DBSTATUS_CACHE_HIT 7 150#define SQLITE_DBSTATUS_CACHE_MISS 8 151#define SQLITE_DBSTATUS_CACHE_WRITE 9 152#define SQLITE_DBSTATUS_DEFERRED_FKS 10 153#define SQLITE_DBSTATUS_CACHE_USED_SHARED 11 154#define SQLITE_DBSTATUS_CACHE_SPILL 12 155#define SQLITE_DBSTATUS_MAX 12 /* Largest defined DBSTATUS */ 156.Ed 157.Sh SEE ALSO 158.Xr sqlite3_db_status 3 159