Documentation Source Text

Hex Artifact Content
Login

Artifact 4d88e885eb1f60190daaaf9d2d52f98a3454fc6fac1035c999f9d94a0f33b85c:


0000: 3c 74 69 74 6c 65 3e 54 68 65 20 53 51 4c 49 54  <title>The SQLIT
0010: 45 5f 4d 45 4d 53 54 41 54 20 56 69 72 74 75 61  E_MEMSTAT Virtua
0020: 6c 20 54 61 62 6c 65 3c 2f 74 69 74 6c 65 3e 0a  l Table</title>.
0030: 3c 74 63 6c 3e 68 64 5f 6b 65 79 77 6f 72 64 73  <tcl>hd_keywords
0040: 20 73 71 6c 69 74 65 5f 6d 65 6d 73 74 61 74 20   sqlite_memstat 
0050: 7b 53 51 4c 49 54 45 5f 4d 45 4d 53 54 41 54 20  {SQLITE_MEMSTAT 
0060: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 7d 20 5c  virtual table} \
0070: 0a 20 20 20 20 20 20 20 20 7b 74 68 65 20 53 51  .        {the SQ
0080: 4c 49 54 45 5f 4d 45 4d 53 54 41 54 20 65 78 74  LITE_MEMSTAT ext
0090: 65 6e 73 69 6f 6e 7d 3c 2f 74 63 6c 3e 0a 3c 66  ension}</tcl>.<f
00a0: 61 6e 63 79 5f 66 6f 72 6d 61 74 3e 0a 0a 3c 68  ancy_format>..<h
00b0: 31 3e 4f 76 65 72 76 69 65 77 3c 2f 68 31 3e 0a  1>Overview</h1>.
00c0: 0a 3c 70 3e 0a 54 68 65 20 53 51 4c 49 54 45 5f  .<p>.The SQLITE_
00d0: 4d 45 4d 53 54 41 54 20 65 78 74 65 6e 73 69 6f  MEMSTAT extensio
00e0: 6e 20 69 6d 70 6c 65 6d 65 6e 74 73 20 61 6e 20  n implements an 
00f0: 5b 65 70 6f 6e 79 6d 6f 75 73 2d 6f 6e 6c 79 20  [eponymous-only 
0100: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 74  virtual table] t
0110: 68 61 74 0a 70 72 6f 76 69 64 65 73 20 53 51 4c  hat.provides SQL
0120: 20 61 63 63 65 73 73 20 74 6f 20 74 68 65 20 5b   access to the [
0130: 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34  sqlite3_status64
0140: 28 29 5d 20 61 6e 64 0a 5b 73 71 6c 69 74 65 33  ()] and.[sqlite3
0150: 5f 64 62 5f 73 74 61 74 75 73 28 29 5d 20 69 6e  _db_status()] in
0160: 74 65 72 66 61 63 65 73 2e 0a 3c 2f 70 3e 0a 0a  terfaces..</p>..
0170: 3c 70 3e 0a 54 68 65 20 53 51 4c 49 54 45 5f 53  <p>.The SQLITE_S
0180: 54 4d 54 20 65 78 74 65 6e 73 69 6f 6e 20 63 61  TMT extension ca
0190: 6e 20 61 6c 73 6f 20 62 65 20 6c 6f 61 64 65 64  n also be loaded
01a0: 20 61 74 20 72 75 6e 2d 74 69 6d 65 0a 62 79 20   at run-time.by 
01b0: 63 6f 6d 70 69 6c 69 6e 67 20 74 68 65 20 65 78  compiling the ex
01c0: 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 61 20 73  tension into a s
01d0: 68 61 72 65 64 20 6c 69 62 72 61 72 79 20 6f 72  hared library or
01e0: 20 44 4c 4c 20 75 73 69 6e 67 20 74 68 65 20 73   DLL using the s
01f0: 6f 75 72 63 65 0a 63 6f 64 65 20 61 74 20 5b 68  ource.code at [h
0200: 74 74 70 73 3a 2f 2f 73 71 6c 69 74 65 2e 6f 72  ttps://sqlite.or
0210: 67 2f 73 72 63 2f 66 69 6c 65 2f 65 78 74 2f 6d  g/src/file/ext/m
0220: 69 73 63 2f 6d 65 6d 73 74 61 74 2e 63 5d 20 61  isc/memstat.c] a
0230: 6e 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 65  nd following the
0240: 0a 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 66 6f  .instructions fo
0250: 72 20 68 6f 77 20 74 6f 20 5b 63 6f 6d 70 69 6c  r how to [compil
0260: 65 20 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e  e loadable exten
0270: 73 69 6f 6e 73 5d 2e 0a 3c 2f 70 3e 0a 0a 3c 68  sions]..</p>..<h
0280: 31 3e 55 73 61 67 65 3c 2f 68 31 3e 0a 0a 3c 70  1>Usage</h1>..<p
0290: 3e 0a 54 68 65 20 53 51 4c 49 54 45 5f 4d 45 4d  >.The SQLITE_MEM
02a0: 53 54 41 54 20 76 69 72 74 75 61 6c 20 74 61 62  STAT virtual tab
02b0: 6c 65 20 69 73 20 61 20 72 65 61 64 2d 6f 6e 6c  le is a read-onl
02c0: 79 20 74 61 62 6c 65 20 74 68 61 74 20 63 61 6e  y table that can
02d0: 20 62 65 0a 71 75 65 72 69 65 64 20 74 6f 20 64   be.queried to d
02e0: 65 74 65 72 6d 69 6e 65 20 70 65 72 66 6f 72 6d  etermine perform
02f0: 61 6e 63 65 20 63 68 61 72 61 63 74 65 72 69 73  ance characteris
0300: 74 69 63 73 20 28 70 72 69 6d 61 72 69 6c 79 20  tics (primarily 
0310: 74 68 65 0a 61 6d 6f 75 6e 74 20 6f 66 20 6d 65  the.amount of me
0320: 6d 6f 72 79 20 62 65 69 6e 67 20 75 73 65 64 29  mory being used)
0330: 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   of the current 
0340: 69 6e 73 74 61 6e 63 65 20 6f 66 20 53 51 4c 69  instance of SQLi
0350: 74 65 2e 0a 54 68 65 20 53 51 4c 49 54 45 5f 4d  te..The SQLITE_M
0360: 45 4d 53 54 41 54 45 20 74 61 62 6c 65 20 69 73  EMSTATE table is
0370: 20 65 73 73 65 6e 74 69 61 6c 6c 79 20 61 20 77   essentially a w
0380: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 20 74 68  rapper around th
0390: 65 0a 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49  e.C-language API
03a0: 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75  s [sqlite3_statu
03b0: 73 36 34 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  s64()] and [sqli
03c0: 74 65 33 5f 64 62 5f 73 74 61 74 75 73 28 29 5d  te3_db_status()]
03d0: 2e 0a 49 66 20 74 68 65 20 0a 5b 68 74 74 70 73  ..If the .[https
03e0: 3a 2f 2f 73 71 6c 69 74 65 2e 6f 72 67 2f 73 72  ://sqlite.org/sr
03f0: 63 2f 66 69 6c 65 2f 65 78 74 2f 6d 69 73 63 2f  c/file/ext/misc/
0400: 6d 65 6d 73 74 61 74 2e 63 7c 6d 65 6d 73 74 61  memstat.c|memsta
0410: 74 2e 63 5d 20 73 6f 75 72 63 65 0a 66 69 6c 65  t.c] source.file
0420: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
0430: 68 20 74 68 65 20 2d 44 53 51 4c 49 54 45 5f 45  h the -DSQLITE_E
0440: 4e 41 42 4c 45 5f 5a 49 50 56 46 53 20 6f 70 74  NABLE_ZIPVFS opt
0450: 69 6f 6e 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ion, then SQLITE
0460: 5f 4d 45 4d 53 54 41 54 0a 77 69 6c 6c 20 61 6c  _MEMSTAT.will al
0470: 73 6f 20 64 6f 20 73 6f 6d 65 20 5b 73 71 6c 69  so do some [sqli
0480: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
0490: 7c 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 5d 20 63  |file-control] c
04a0: 61 6c 6c 73 20 74 6f 20 65 78 74 72 61 63 74 0a  alls to extract.
04b0: 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 69 6e 66  memory usage inf
04c0: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
04d0: 68 65 20 0a 5b 68 74 74 70 73 3a 2f 2f 77 77 77  he .[https://www
04e0: 2e 68 77 61 63 69 2e 63 6f 6d 2f 73 77 2f 73 71  .hwaci.com/sw/sq
04f0: 6c 69 74 65 2f 7a 69 70 76 66 73 2e 68 74 6d 6c  lite/zipvfs.html
0500: 20 7c 20 5a 49 50 56 46 53 5d 20 73 75 62 73 79   | ZIPVFS] subsy
0510: 73 74 65 6d 2c 20 0a 69 66 20 74 68 61 74 20 73  stem, .if that s
0520: 75 62 73 79 73 74 65 6d 20 61 73 20 62 65 65 6e  ubsystem as been
0530: 20 6c 69 63 65 6e 73 65 64 2c 20 69 6e 73 74 61   licensed, insta
0540: 6c 6c 65 64 2c 20 61 6e 64 20 69 73 20 69 6e 20  lled, and is in 
0550: 75 73 65 2e 0a 0a 3c 70 3e 0a 54 68 65 20 53 51  use...<p>.The SQ
0560: 4c 49 54 45 5f 4d 45 4d 53 54 41 54 20 74 61 62  LITE_MEMSTAT tab
0570: 6c 65 20 61 70 70 65 61 72 73 20 74 6f 20 68 61  le appears to ha
0580: 76 65 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ve the following
0590: 20 73 63 68 65 6d 61 3a 0a 0a 3c 63 6f 64 65 62   schema:..<codeb
05a0: 6c 6f 63 6b 3e 0a 43 52 45 41 54 45 20 54 41 42  lock>.CREATE TAB
05b0: 4c 45 20 73 71 6c 69 74 65 5f 6d 65 6d 73 74 61  LE sqlite_memsta
05c0: 74 28 0a 20 20 6e 61 6d 65 20 54 45 58 54 2c 0a  t(.  name TEXT,.
05d0: 20 20 73 63 68 65 6d 61 20 54 45 58 54 2c 0a 20    schema TEXT,. 
05e0: 20 76 61 6c 75 65 20 49 4e 54 2c 0a 20 20 68 69   value INT,.  hi
05f0: 77 74 72 20 49 4e 54 0a 29 3b 0a 3c 2f 63 6f 64  wtr INT.);.</cod
0600: 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 0a 45 61 63  eblock>..<p>.Eac
0610: 68 20 72 6f 77 20 6f 66 20 74 68 65 20 53 51 4c  h row of the SQL
0620: 49 54 45 5f 4d 45 4d 53 54 41 54 20 74 61 62 6c  ITE_MEMSTAT tabl
0630: 65 20 63 6f 72 72 65 73 70 6f 6e 64 73 20 74 6f  e corresponds to
0640: 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 20 74   a single call t
0650: 6f 0a 6f 6e 65 20 6f 66 20 74 68 65 20 5b 73 71  o.one of the [sq
0660: 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34 28 29  lite3_status64()
0670: 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 64 62  ] or [sqlite3_db
0680: 5f 73 74 61 74 75 73 28 29 5d 20 69 6e 74 65 72  _status()] inter
0690: 66 61 63 65 73 2e 0a 54 68 65 20 4e 41 4d 45 20  faces..The NAME 
06a0: 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 6f  column of the ro
06b0: 77 20 69 64 65 6e 74 69 66 69 65 73 20 77 68 69  w identifies whi
06c0: 63 68 20 22 76 65 72 62 22 20 77 61 73 20 70 61  ch "verb" was pa
06d0: 73 73 65 64 20 74 6f 20 74 68 6f 73 65 0a 69 6e  ssed to those.in
06e0: 74 65 72 66 61 63 65 73 2e 20 20 46 6f 72 20 65  terfaces.  For e
06f0: 78 61 6d 70 6c 65 2c 20 69 66 20 5b 73 71 6c 69  xample, if [sqli
0700: 74 65 33 5f 73 74 61 74 75 73 36 34 28 29 5d 20  te3_status64()] 
0710: 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 0a  is invoked with.
0720: 5b 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d  [SQLITE_STATUS_M
0730: 45 4d 4f 52 59 5f 55 53 45 44 5d 2c 20 74 68 65  EMORY_USED], the
0740: 6e 20 74 68 65 20 4e 41 4d 45 20 63 6f 6c 75 6d  n the NAME colum
0750: 6e 20 69 73 20 27 4d 45 4d 4f 52 59 5f 55 53 45  n is 'MEMORY_USE
0760: 44 27 2e 0a 4f 72 20 69 66 20 5b 73 71 6c 69 74  D'..Or if [sqlit
0770: 65 33 5f 64 62 5f 73 74 61 74 75 73 28 29 5d 20  e3_db_status()] 
0780: 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
0790: 5b 53 51 4c 49 54 45 5f 44 42 53 54 41 54 55 53  [SQLITE_DBSTATUS
07a0: 5f 43 41 43 48 45 5f 55 53 45 44 5d 2c 0a 74 68  _CACHE_USED],.th
07b0: 65 6e 20 74 68 65 20 4e 41 4d 45 20 63 6f 6c 75  en the NAME colu
07c0: 6d 6e 20 69 73 20 22 44 42 5f 43 41 43 48 45 5f  mn is "DB_CACHE_
07d0: 55 53 45 44 22 2e 0a 0a 3c 70 3e 0a 54 68 65 20  USED"...<p>.The 
07e0: 53 43 48 45 4d 41 20 63 6f 6c 75 6d 6e 20 69 73  SCHEMA column is
07f0: 20 4e 55 4c 4c 2c 20 65 78 63 65 70 74 20 66 6f   NULL, except fo
0800: 72 20 63 61 73 65 73 20 77 68 65 6e 20 74 68 65  r cases when the
0810: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
0820: 6f 6e 74 72 6f 6c 28 29 5d 0a 69 6e 74 65 72 66  ontrol()].interf
0830: 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69  ace is used to i
0840: 6e 74 65 72 72 6f 67 61 74 65 20 74 68 65 20 5a  nterrogate the Z
0850: 49 50 56 46 53 20 62 61 63 6b 65 6e 64 2e 20 20  IPVFS backend.  
0860: 41 73 20 74 68 69 73 20 6f 6e 6c 79 20 68 61 70  As this only hap
0870: 70 65 6e 73 0a 77 68 65 6e 20 74 68 65 20 6d 65  pens.when the me
0880: 6d 73 74 61 74 2e 63 20 6d 6f 64 75 6c 65 20 69  mstat.c module i
0890: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
08a0: 2d 44 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f  -DSQLITE_ENABLE_
08b0: 5a 49 50 56 46 53 20 61 6e 64 20 77 68 65 6e 0a  ZIPVFS and when.
08c0: 5b 68 74 74 70 73 3a 2f 2f 77 77 77 2e 68 77 61  [https://www.hwa
08d0: 63 69 2e 63 6f 6d 2f 73 77 2f 73 71 6c 69 74 65  ci.com/sw/sqlite
08e0: 2f 7a 69 70 76 66 73 2e 68 74 6d 6c 20 7c 20 5a  /zipvfs.html | Z
08f0: 49 50 56 46 53 5d 20 69 73 20 69 6e 20 75 73 65  IPVFS] is in use
0900: 2c 20 0a 53 43 48 45 4d 41 20 69 73 20 75 73 75  , .SCHEMA is usu
0910: 61 6c 6c 79 20 4e 55 4c 4c 2e 0a 0a 3c 70 3e 0a  ally NULL...<p>.
0920: 54 68 65 20 56 41 4c 55 45 20 61 6e 64 20 48 49  The VALUE and HI
0930: 57 54 52 20 63 6f 6c 75 6d 6e 73 20 72 65 70 6f  WTR columns repo
0940: 72 74 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  rt the current v
0950: 61 6c 75 65 20 6f 66 20 74 68 65 20 6d 65 61 73  alue of the meas
0960: 75 72 65 20 61 6e 64 0a 69 74 73 20 22 68 69 67  ure and.its "hig
0970: 68 2d 77 61 74 65 72 20 6d 61 72 6b 22 2e 20 20  h-water mark".  
0980: 54 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  The high-water m
0990: 61 72 6b 20 69 73 20 74 68 65 20 68 69 67 68 65  ark is the highe
09a0: 73 74 20 76 61 6c 75 65 20 65 76 65 72 20 73 65  st value ever se
09b0: 65 6e 0a 66 6f 72 20 74 68 65 20 6d 65 61 73 75  en.for the measu
09c0: 72 65 6d 65 6e 74 2c 20 61 74 20 6c 65 61 73 74  rement, at least
09d0: 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20   since the last 
09e0: 72 65 73 65 74 2e 20 20 54 68 65 20 53 51 4c 49  reset.  The SQLI
09f0: 54 45 5f 4d 45 4d 53 54 41 54 0a 76 69 72 74 75  TE_MEMSTAT.virtu
0a00: 61 6c 20 74 61 62 6c 65 20 64 6f 65 73 20 6e 6f  al table does no
0a10: 74 20 70 72 6f 76 69 64 65 20 61 20 6d 65 63 68  t provide a mech
0a20: 61 6e 69 73 6d 20 66 6f 72 20 72 65 73 65 74 74  anism for resett
0a30: 69 6e 67 20 74 68 65 20 68 69 67 68 2d 77 61 74  ing the high-wat
0a40: 65 72 20 6d 61 72 6b 2e 0a 0a 3c 70 3e 0a 44 65  er mark...<p>.De
0a50: 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68  pending on which
0a60: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65   parameter is be
0a70: 69 6e 67 20 69 6e 74 65 72 72 6f 67 61 74 65 64  ing interrogated
0a80: 2c 20 6f 6e 65 20 6f 66 20 74 68 65 20 56 41 4c  , one of the VAL
0a90: 55 45 0a 6f 72 20 48 49 57 54 52 20 6d 61 72 6b  UE.or HIWTR mark
0aa0: 20 6d 65 61 73 75 72 65 6d 65 6e 74 73 20 6d 69   measurements mi
0ab0: 67 68 74 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ght be undefined
0ac0: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
0ad0: 6f 6e 6c 79 20 74 68 65 0a 68 69 67 68 2d 77 61  only the.high-wa
0ae0: 74 65 72 20 6d 61 72 6b 20 69 73 20 6d 65 61 6e  ter mark is mean
0af0: 69 6e 67 66 75 6c 20 66 6f 72 20 5b 53 51 4c 49  ingful for [SQLI
0b00: 54 45 5f 53 54 41 54 55 53 5f 4d 41 4c 4c 4f 43  TE_STATUS_MALLOC
0b10: 5f 53 49 5a 45 5d 2c 20 61 6e 64 0a 6f 6e 6c 79  _SIZE], and.only
0b20: 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
0b30: 75 65 20 69 73 20 6d 65 61 6e 69 6e 67 66 75 6c  ue is meaningful
0b40: 20 66 6f 72 20 5b 53 51 4c 49 54 45 5f 44 42 53   for [SQLITE_DBS
0b50: 54 41 54 55 53 5f 43 41 43 48 45 5f 55 53 45 44  TATUS_CACHE_USED
0b60: 5d 2e 0a 46 6f 72 20 72 6f 77 73 20 77 68 65 72  ]..For rows wher
0b70: 65 20 6f 6e 65 20 6f 72 20 74 68 65 20 6f 74 68  e one or the oth
0b80: 65 72 20 6f 66 20 56 41 4c 55 45 20 6f 72 20 48  er of VALUE or H
0b90: 49 57 54 52 20 69 73 20 6e 6f 74 20 6d 65 61 6e  IWTR is not mean
0ba0: 69 6e 67 66 75 6c 2c 0a 74 68 61 74 20 76 61 6c  ingful,.that val
0bb0: 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  ue is returned a
0bc0: 73 20 4e 55 4c 4c 2e 0a 74 68 65 20 0a 0a 69 6e  s NULL..the ..in
0bd0: 74 65 72 66 61 63 65 73 2c 20 77 69 74 68 20 74  terfaces, with t
0be0: 68 65 20 69 6e 69 74 69 61 6c 0a                 he initial.