Documentation Source Text

Check-in [e09448dc9d]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Fix requirements marks in the file format document. Improvements to PRAGMA documentation.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: e09448dc9d3119d9688ea69fc90ea7da9dad8ad5
User & Date: drh 2014-08-11 21:17:38
Context
2014-08-11
23:56
Updates to the "How SQLite Is Tested" document. check-in: b7925a9372 user: drh tags: trunk
21:17
Fix requirements marks in the file format document. Improvements to PRAGMA documentation. check-in: e09448dc9d user: drh tags: trunk
18:36
Updates to expression documentation. check-in: 5608ec77f8 user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to pages/fileformat2.in.

   956    956   
   957    957   <p>A [collating function] for each column is necessary in order to compute
   958    958   the order of text fields.
   959    959   ^(SQLite defines three built-in collating functions:)^
   960    960   </p>
   961    961   
   962    962   <blockquote><table border=0 cellspacing=10>
   963         -<tr>^<td valign=top>BINARY
   964         -    <td>Strings are compared byte by byte using the memcmp() function
   965         -        from the standard C library.
   966         -<tr>^<td valign=top>NOCASE
   967         -    <td>Like BINARY except that uppercase ASCII characters ('A' through 'Z')
          963  +<tr><td valign=top>BINARY
          964  +    <td> ^(The built-in BINARY collation compares strings byte by byte
          965  +        using the memcmp() function
          966  +        from the standard C library.)^
          967  +<tr><td valign=top>NOCASE
          968  +    <td> ^(The NOCASE collation is like BINARY except that uppercase
          969  +        ASCII characters ('A' through 'Z')
   968    970           are folded into their lowercase equivalents prior to running the
   969         -        comparison.  Note that only ASCII characters are case-folded.  ^NOCASE
   970         -        does not implement a general purpose unicode caseless comparison.
   971         -<tr>^<td valign=top>RTRIM
   972         -    <td>Like BINARY except that spaces at the end of the string are elided
   973         -        prior to comparison.
          971  +        comparison.  Note that only ASCII characters are case-folded.)^
          972  +        ^(NOCASE
          973  +        does not implement a general purpose unicode caseless comparison.)^
          974  +<tr><td valign=top>RTRIM
          975  +    <td> ^(RTRIM is like BINARY except that spaces at the end of the string
          976  +        are elided prior to comparison.)^
   974    977   </table></blockquote>
   975    978   
   976    979   <p>^Additional application-specific collating functions can be added to
   977    980   SQLite using the [sqlite3_create_collation()] interface.</p>
   978    981   
   979    982   <p>^The default collating function for all strings is BINARY.
   980    983   ^Alternative collating functions for table columns can be specified in the
................................................................................
   982    985   ^When a column is indexed, the same collating function specified in the
   983    986   [CREATE TABLE] statement is used for the column in the index, by default,
   984    987   though this can be overridden using a COLLATE clause in the 
   985    988   [CREATE INDEX] statement.
   986    989   
   987    990   <h3>2.3 Representation Of SQL Tables</h3>
   988    991   
   989         -<p>Each ordinary SQL table in the database schema is represented on-disk
   990         -by a table b-tree.  Each entry in the table b-tree corresponds to a row
   991         -of the SQL table.  The [rowid] of the SQL table is the 64-bit signed
          992  +<p> ^Each ordinary SQL table in the database schema is represented on-disk
          993  +by a table b-tree.  ^Each entry in the table b-tree corresponds to a row
          994  +of the SQL table.  T^he [rowid] of the SQL table is the 64-bit signed
   992    995   integer key for each entry in the table b-tree.</p>
   993    996   
   994         -<p>The content of each SQL table row is stored in the database file by
          997  +<p> ^The content of each SQL table row is stored in the database file by
   995    998   first combining the values in the various columns into a byte array
   996    999   in the record format, then storing that byte array as the payload in
   997   1000   an entry in the table b-tree.  ^The order of values in the record is
   998   1001   the same as the order of columns in the SQL table definition.
   999   1002   ^When an SQL table that includes an
  1000   1003   [INTEGER PRIMARY KEY] column (which aliases the [rowid]) then that
  1001   1004   column appears in the record as a NULL value.  ^SQLite will always use
  1002   1005   the table b-tree key rather than the NULL value when referencing the
  1003   1006   [INTEGER PRIMARY KEY] column.</p>
  1004   1007   
  1005         -<p>^If the [affinity] of a column is REAL and that column contains a
         1008  +<p> ^If the [affinity] of a column is REAL and that column contains a
  1006   1009   value that can be converted to an integer without loss of information
  1007   1010   (if the value contains no fractional part and is not too large to be
  1008   1011   represented as an integer) then the column may be stored in the record
  1009   1012   as an integer.  ^SQLite will convert the value back to floating
  1010   1013   point when extracting it from the record.</p>
  1011   1014   
  1012   1015   <h3>2.4 Representation of WITHOUT ROWID Tables</h3>
  1013   1016   
  1014         -<p>If an SQL table is created using the "WITHOUT ROWID" clause at the
         1017  +<p>^If an SQL table is created using the "WITHOUT ROWID" clause at the
  1015   1018   end of its CREATE TABLE statement, then that table is a [WITHOUT ROWID]
  1016         -table and uses a different on-disk representation.  A WITHOUT ROWID
         1019  +table and uses a different on-disk representation.  ^A WITHOUT ROWID
  1017   1020   table uses an index b-tree rather than a table b-tree for storage.
  1018         -The key for each entry in the WITHOUT ROWID b-tree is a record composed
         1021  +^The key for each entry in the WITHOUT ROWID b-tree is a record composed
  1019   1022   of the columns of the PRIMARY KEY followed by all remaining columns of
  1020         -the table.  The primary key columns appear in the order they they were
         1023  +the table.  ^The primary key columns appear in the order they they were
  1021   1024   declared in the PRIMARY KEY clause and the remaining columns appear in
  1022   1025   the order they occur in the CREATE TABLE statement.
  1023   1026   
  1024   1027   <p>^Hence, the content encoding for a WITHOUT ROWID table is the same
  1025   1028   as the content encoding for an ordinary rowid table, except that the
  1026   1029   order of the columns is rearranged so that PRIMARY KEY columns come
  1027   1030   first, and the content is used as the key in an index b-tree rather
................................................................................
  1050   1053   CREATE INDEX statement is true.
  1051   1054   ^Corresponding rows in the index and table b-trees share the same rowid
  1052   1055   or primary key values and contain the same value for all indexed columns.</p>
  1053   1056   
  1054   1057   <h4>2.5.1 Suppression of redundant columns in WITHOUT ROWID secondary indexed
  1055   1058   </h4>
  1056   1059   
  1057         -<p>In an index on a WITHOUT ROWID table, if one or more of the columns
         1060  +<p> ^In an index on a WITHOUT ROWID table, if one or more of the columns
  1058   1061   of table PRIMARY KEY are also columns of the index, then the
  1059   1062   indexed column is not repeated in the table-key suffix on the end of
  1060         -the index record.  As an example, consider the following SQL:
         1063  +the index record.  ^(As an example, consider the following SQL:
  1061   1064   
  1062   1065   <blockquote><pre>
  1063   1066   CREATE TABLE ex25(a,b,c,d,e,PRIMARY KEY(d,c,a)) WITHOUT rowid;
  1064   1067   CREATE INDEX ex25ce ON ex25(c,e);
  1065   1068   CREATE INDEX ex25acde ON ex25(a,c,d,e);
  1066   1069   </pre></blockquote>
  1067   1070   
  1068   1071   <p>Each row in the ex25ce index of the example above consists of a record
  1069   1072   containing the following columns: c, e, d, a.  The first two columns are
  1070   1073   the columns being indexed, c and e.  The remaining columns are the primary
  1071   1074   key of the corresponding table row.  Normally, the primary key would be
  1072   1075   columns d, c, and a, but because column c already appears earlier in the
  1073         -index, it is omitted from the key suffix.</p>
         1076  +index, it is omitted from the key suffix.)^</p>
  1074   1077   
  1075         -<p>In the extreme case where the columns being indexed cover all columns
         1078  +<p>^(In the extreme case where the columns being indexed cover all columns
  1076   1079   of the PRIMARY KEY, the index will consist of only the columns being
  1077         -indexed.  The ex25acde example above demonstrates this.  Each entry in
         1080  +indexed.  The ex25acde example above demonstrates this.)^  ^Each entry in
  1078   1081   the ex25acde index consists of only the columns a, c, d, and e, in that
  1079   1082   order.</p>
  1080   1083   
  1081         -<p>The suppression of redundant columns in the key suffix of an index
  1082         -entry only occurs in WITHOUT ROWID tables.  In an ordinary rowid table,
         1084  +<p> ^The suppression of redundant columns in the key suffix of an index
         1085  +entry only occurs in WITHOUT ROWID tables.  ^In an ordinary rowid table,
  1083   1086   the index entry always ends with the rowid even if the [INTEGER PRIMARY KEY]
  1084   1087   column is one of the columns being indexed.</p>
  1085   1088   
  1086   1089   <tcl>hd_fragment sqlite_master {sqlite_master} {sqlite_master table}</tcl>
  1087   1090   <h3>2.6 Storage Of The SQL Database Schema</h3>
  1088   1091   
  1089   1092   <p>^Page 1 of a database file is the root page of a table b-tree that
................................................................................
  1206   1209   <h4>2.6.2 The sqlite_sequence table</h4>
  1207   1210   
  1208   1211   <p>^The sqlite_sequence table is an internal table used to help implement
  1209   1212   [AUTOINCREMENT].  ^The sqlite_sequence table is created automatically
  1210   1213   whenever any ordinary table with an AUTOINCREMENT integer primary
  1211   1214   key is created.  ^Once created, the sqlite_sequence table exists in the
  1212   1215   sqlite_master table forever; it cannot be dropped.
  1213         -The schema for the sqlite_sequence table is:
         1216  +^(The schema for the sqlite_sequence table is:
  1214   1217   
  1215   1218   <blockquote><pre>
  1216   1219   CREATE TABLE sqlite_sequence(name,seq);
  1217         -</pre></blockquote>
         1220  +</pre></blockquote>)^
  1218   1221   
  1219   1222   <p>^There is a single row in the sqlite_sequence table for each ordinary
  1220         -table that uses AUTOINCREMENT.  The name of the table (as it appears in
         1223  +table that uses AUTOINCREMENT.  ^(The name of the table (as it appears in
  1221   1224   sqlite_master.name) is in the sqlite_sequence.main field and the largest
  1222   1225   [INTEGER PRIMARY KEY] ever used by that table is in the sqlite_sequence.seq
  1223         -field.  ^New automatically generated integer primary keys for AUTOINCREMENT
         1226  +field.)^  ^New automatically generated integer primary keys for AUTOINCREMENT
  1224   1227   tables are guaranteed to be larger than the sqlite_sequence.seq field for
  1225   1228   that table.
  1226   1229   ^(If the sqlite_sequence.seq field of an AUTOINCREMENT table is already at
  1227   1230   the largest integer value (9223372036854775807) then attempts to add new
  1228   1231   rows to that table with an automatically generated integer primary will fail
  1229   1232   with an [SQLITE_FULL] error.)^
  1230   1233   ^The sqlite_sequence.seq field is automatically updated if required when
................................................................................
  1247   1250   <h4>2.6.3 The sqlite_stat1 table</h4>
  1248   1251   
  1249   1252   <p>^The sqlite_stat1 is an internal table created by the [ANALYZE] command
  1250   1253   and used to hold supplemental information about tables and indexes that the
  1251   1254   query planner can use to help it find better ways of performing queries.
  1252   1255   ^Applications can update, delete from, insert into or drop the sqlite_stat1
  1253   1256   table, but may not create or alter the sqlite_stat1 table.
  1254         -^The schema of the sqlite_stat1 table is as follows:
         1257  +^(The schema of the sqlite_stat1 table is as follows:
  1255   1258   
  1256   1259   <blockquote><pre>
  1257   1260   CREATE TABLE sqlite_stat1(tbl,idx,stat);
  1258         -</pre></blockquote>
         1261  +</pre></blockquote>)^
  1259   1262   
  1260         -<p>There is normally one row per index, with the index identified by the
  1261         -name in the sqlite_stat1.idx column.  The sqlite_stat1.tbl column is
  1262         -the name of the table to which the index belongs.  In each such row, 
         1263  +<p> ^(There is normally one row per index, with the index identified by the
         1264  +name in the sqlite_stat1.idx column.)^  ^(The sqlite_stat1.tbl column is
         1265  +the name of the table to which the index belongs.)^  ^(In each such row, 
  1263   1266   the sqlite_stat.stat column will be
  1264         -a string consisting of a list of integers.  The first integer in this
  1265         -list is the approximate number of rows in the index and in the table.  
  1266         -The second integer is the approximate average number of rows in the index
  1267         -that have the same value in the first column of the index.  The third 
         1267  +a string consisting of a list of integers followed by zero or more 
         1268  +arguments.)^  ^The first integer in this
         1269  +list is the approximate number of rows in the index and in the table.
         1270  +^The second integer is the approximate average number of rows in the index
         1271  +that have the same value in the first column of the index.  ^The third 
  1268   1272   integer is the approximate average number of rows in the index that have 
  1269         -the same value for the first two columns.  The N-th integer (for N>1) 
         1273  +the same value for the first two columns.  ^The N-th integer (for N>1) 
  1270   1274   is the approximate average number of rows in 
  1271         -the index which have the same value for the first N-1 columns.  For
  1272         -a K-column index, there will be K+1 integers in the stat column.  If
         1275  +the index which have the same value for the first N-1 columns.  ^For
         1276  +a K-column index, there will be K+1 integers in the stat column.  ^If
  1273   1277   the index is unique, then the last integer will be 1.
  1274   1278   
  1275   1279   <p>^The list of integers in the stat column can optionally be followed
  1276         -by the keyword "unordered".  ^The "unordered" keyword, if it is present,
  1277         -must be separated from the last integer by a single space.  ^If the
  1278         -"unordered" keyword is present, then the query planner assumes that
  1279         -the index is unordered and will not use the index for a range query
         1280  +by arguments, each of which is a sequence of non-space characters.
         1281  +^All arguments are preceded by a single space.
         1282  +^Unrecognized arguments are silently ignored.
         1283  +
         1284  +<p>^If the "unordered" argument is present, then the query planner assumes
         1285  +that the index is unordered and will not use the index for a range query
  1280   1286   or for sorting.
  1281   1287   
  1282         -<p>^The list of integers in the stat column can also optionally be followed
  1283         -by a token of the form "sz=NNN" where NNN is an unsigned integer.  The
  1284         -"sz=NNN" token, if present, must be separated from the last integer by a
  1285         -single space.  ^The "sz=NNN" token means that the average row size over all 
  1286         -records of the table or
         1288  +<p>^The "sz=NNN" argument (where NNN represents a sequence of 1 or more digits)
         1289  +means that the average row size over all records of the table or
  1287   1290   index is NNN bytes per row.  ^The SQLite query planner might use the
  1288   1291   estimated row size information provided by the "sz=NNN" token
  1289   1292   to help it choose smaller tables and indexes that require less disk I/O.
  1290   1293   
  1291   1294   <p>New text tokens may be added to the end of the stat column in future
  1292   1295   enhancements to SQLite.  For compatibility, unrecognized tokens at the end
  1293   1296   of the stat column are silently ignored.
  1294   1297   
  1295         -<p>If the sqlite_stat1.idx column is NULL, then the sqlite_stat1.stat
         1298  +<p>^(If the sqlite_stat1.idx column is NULL, then the sqlite_stat1.stat
  1296   1299   column contains a single integer which is the approximate number of
  1297         -rows in the table identified by sqlite_stat1.tbl.
         1300  +rows in the table identified by sqlite_stat1.tbl.)^
  1298   1301   
  1299   1302   <tcl>hd_fragment stat2tab {sqlite_stat2}</tcl>
  1300   1303   <h4>2.6.4 The sqlite_stat2 table</h4>
  1301   1304   
  1302   1305   <p>The sqlite_stat2 is only created and is only used if SQLite is compiled
  1303   1306   with SQLITE_ENABLE_STAT2 and if the SQLite version number is between
  1304   1307   3.6.18 and 3.7.8.  The sqlite_stat2 table is neither read nor written by any
................................................................................
  1333   1336   <p>The format for sqlite_stat2 is recorded here for legacy reference.  
  1334   1337   Recent versions of SQLite no longer support sqlite_stat2 and the
  1335   1338   sqlite_stat2 table, it is exists, is simply ignored.
  1336   1339   
  1337   1340   <tcl>hd_fragment stat3tab {sqlite_stat3} SQLITE_STAT3</tcl>
  1338   1341   <h4>2.6.5 The sqlite_stat3 table</h4>
  1339   1342   
  1340         -<p>The sqlite_stat3 is only only used if SQLite is compiled
         1343  +<p>The sqlite_stat3 is only used if SQLite is compiled
  1341   1344   with [SQLITE_ENABLE_STAT3] or [SQLITE_ENABLE_STAT4]
  1342   1345   and if the SQLite version number is 3.7.9 or greater.
  1343   1346   The sqlite_stat3 table is neither read nor written by any
  1344   1347   version of SQLite before 3.7.9.
  1345   1348   If the [SQLITE_ENABLE_STAT4] compile-time option is used and the
  1346   1349   SQLite version number is 3.8.1 or greater, then sqlite_stat3 might
  1347   1350   be read but not written.
  1348   1351   The sqlite_stat3 table contains additional information
  1349   1352   about the distribution of keys within an index, information that the
  1350   1353   query planner can use to devise better and faster query algorithms.
  1351         -The schema of the sqlite_stat3 table is as follows:
         1354  +^(The schema of the sqlite_stat3 table is as follows:
  1352   1355   
  1353   1356   <blockquote><pre>
  1354   1357   CREATE TABLE sqlite_stat3(tbl,idx,nEq,nLt,nDLt,sample);
  1355         -</pre></blockquote>
         1358  +</pre></blockquote>)^
  1356   1359   
  1357   1360   <p>There are usually multiple entries in the sqlite_stat3 table for each index.
  1358         -The sqlite_stat3.sample column holds the value of the left-most field of an
  1359         -index identified by sqlite_stat3.idx and sqlite_stat3.tbl.
  1360         -The sqlite_stat3.nEq column holds the approximate
         1361  +^(The sqlite_stat3.sample column holds the value of the left-most field of an
         1362  +index identified by sqlite_stat3.idx and sqlite_stat3.tbl.)^
         1363  +^(The sqlite_stat3.nEq column holds the approximate
  1361   1364   number of entries in the index whose left-most column exactly matches
  1362         -the sample.  
  1363         -The sqlite_stat3.nLt holds the approximate number of entries in the
  1364         -index whose left-most column is less than the sample.
  1365         -The sqlite_stat3.nDLt column holds the approximate
         1365  +the sample.)^
         1366  +^(The sqlite_stat3.nLt holds the approximate number of entries in the
         1367  +index whose left-most column is less than the sample.)^
         1368  +^(The sqlite_stat3.nDLt column holds the approximate
  1366   1369   number of distinct left-most entries in the index that are less than
  1367         -the sample.
         1370  +the sample.)^
  1368   1371   
  1369         -<p>There can be an arbitrary number of sqlite_stat3 entries per index.
         1372  +<p>^There can be an arbitrary number of sqlite_stat3 entries per index.
  1370   1373   The [ANALYZE] command will typically generate sqlite_stat3 tables
  1371   1374   that contain between 10 and 40 samples that are distributed across
  1372   1375   the key space and with large nEq values.
  1373   1376   
  1374   1377   <tcl>hd_fragment stat4tab {sqlite_stat4} SQLITE_STAT4</tcl>
  1375   1378   <h4>2.6.6 The sqlite_stat4 table</h4>
  1376   1379   
................................................................................
  1379   1382   3.8.1 or greater.  The sqlite_stat4 table is neither read nor written by any
  1380   1383   version of SQLite before 3.8.1.
  1381   1384   The sqlite_stat4 table contains additional information
  1382   1385   about the distribution of keys within an index or the distribution of
  1383   1386   keys in the primary key of a [WITHOUT ROWID] table.
  1384   1387   The query planner can sometimes use the additional information in
  1385   1388   the sqlite_stat4 table to devise better and faster query algorithms.
  1386         -The schema of the sqlite_stat4 table is as follows:
         1389  +^(The schema of the sqlite_stat4 table is as follows:
  1387   1390   
  1388   1391   <blockquote><pre>
  1389   1392   CREATE TABLE sqlite_stat4(tbl,idx,nEq,nLt,nDLt,sample);
  1390         -</pre></blockquote>
         1393  +</pre></blockquote>)^
  1391   1394   
  1392   1395   <p>There are typically between 10 to 40 entries in the sqlite_stat4 table for
  1393   1396   each index for which statistics are available, however these limits are
  1394   1397   not hard bounds.
  1395   1398   The meanings of the columns in the sqlite_stat4 table are as follows:
  1396   1399   
  1397   1400   <center>
  1398   1401   <table border="0" width="100%" cellpadding="10">
  1399   1402   <tr><td valign="top" align="right">tbl:</td>
  1400         -    <td>The sqlite_stat4.tbl column holds name of the table that owns
  1401         -    the index that the row describes
         1403  +    <td>^(The sqlite_stat4.tbl column holds name of the table that owns
         1404  +    the index that the row describes)^
  1402   1405   
  1403   1406   <tr><td valign="top" align="right">idx:</td>
  1404         -    <td>The sqlite_stat4.idx column holds name of the index that the
         1407  +    <td>^(The sqlite_stat4.idx column holds name of the index that the
  1405   1408       row describes, or in the case of
  1406   1409       an sqlite_stat4 entry for a [WITHOUT ROWID] table, the
  1407         -    name of the table itself.
         1410  +    name of the table itself.)^
  1408   1411   
  1409   1412   <tr><td valign="top" align="right">sample:</td>
  1410         -    <td>The sqlite_stat4.sample column holds a BLOB
         1413  +    <td>^(The sqlite_stat4.sample column holds a BLOB
  1411   1414       in the [record format] that encodes the indexed columns followed by
  1412   1415       the rowid for a rowid table or by the columns of the primary key 
  1413         -    for a WITHOUT ROWID table.
  1414         -    The sqlite_stat4.sample BLOB for the WITHOUT ROWID table itself 
  1415         -    contains just the columns of the primary key.
         1416  +    for a WITHOUT ROWID table.)^
         1417  +    ^(The sqlite_stat4.sample BLOB for the WITHOUT ROWID table itself 
         1418  +    contains just the columns of the primary key.)^
  1416   1419       Let the number of columns encoded by the sqlite_stat4.sample blob be N.
  1417         -    For indexes on an ordinary rowid table, N will be one more than the number 
         1420  +    ^For indexes on an ordinary rowid table, N will be one more than the number 
  1418   1421       of columns indexed.
  1419         -    For indexes on WITHOUT ROWID tables, N will be the number of columns
         1422  +    ^For indexes on WITHOUT ROWID tables, N will be the number of columns
  1420   1423       indexed plus the number of columns in the primary key.
  1421         -    For a WITHOUT ROWID table, N will be the number of columns in the
         1424  +    ^For a WITHOUT ROWID table, N will be the number of columns in the
  1422   1425       primary key.
  1423   1426   
  1424   1427   <tr><td valign="top" align="right">nEq:</td>
  1425         -    <td>The sqlite_stat4.nEq column holds a list of N integers where 
         1428  +    <td>^(The sqlite_stat4.nEq column holds a list of N integers where 
  1426   1429       the K-th integer is the approximate number of entries in the index
  1427   1430       whose left-most K columns exactly match the K left-most columns
  1428         -    of the sample.
         1431  +    of the sample.)^
  1429   1432   
  1430   1433   <tr><td valign="top" align="right">nLt:</td>
  1431         -    <td>The sqlite_stat4.nLt column holds a list of N integers where
         1434  +    <td>^(The sqlite_stat4.nLt column holds a list of N integers where
  1432   1435       the K-th integer is the approximate number of entries in the
  1433   1436       index whose K left-most columns are collectively less than the 
  1434         -    K left-most columns of the sample.
         1437  +    K left-most columns of the sample.)^
  1435   1438   
  1436   1439   <tr><td valign="top" align="right">nDLt:</td>
  1437         -    <td>The sqlite_stat4.nDLt column holds a list of N integers where the K-th 
  1438         -    integers is the approximate
         1440  +    <td>^(The sqlite_stat4.nDLt column holds a list of N integers where
         1441  +    the K-th integers is the approximate
  1439   1442       number of entries in the index that are distinct in the first K columns and
  1440   1443       that are whose left-most K columns are collectively less than the left-most
  1441         -    K columns of the sample.
         1444  +    K columns of the sample.)^
  1442   1445   </table>
  1443   1446   </center>
  1444   1447   
  1445   1448   <p>The sqlite_stat4 is a generalization of the sqlite_stat3 table.  The
  1446   1449   sqlite_stat3 table provides information about the left-most column of an
  1447   1450   index whereas the sqlite_stat4 table provides information about all columns
  1448   1451   of the index.
  1449   1452   
  1450         -<p>There can be an arbitrary number of sqlite_stat4 entries per index.
         1453  +<p>^There can be an arbitrary number of sqlite_stat4 entries per index.
  1451   1454   The [ANALYZE] command will typically generate sqlite_stat4 tables
  1452   1455   that contain between 10 and 40 samples that are distributed across
  1453   1456   the key space and with large nEq values.
  1454   1457   
  1455   1458   <tcl>hd_fragment rollbackjournal {rollback journal format}</tcl>
  1456   1459   <h2>3.0 The Rollback Journal</h2>
  1457   1460   
................................................................................
  1488   1491   
  1489   1492   <p>A valid rollback journal begins with a header in the following format:</p>
  1490   1493   
  1491   1494   <center>
  1492   1495   <i>Rollback Journal Header Format</i><br>
  1493   1496   <table width="80%" border=1>
  1494   1497   <tr><th>Offset<th>Size<th>Description
  1495         -<tr>^(<td valign=top align=center>0
         1498  +<tr><td valign=top align=center>0
  1496   1499       <td valign=top align=center>8
  1497         -    <td>Header string:  0xd9, 0xd5, 0x05, 0xf9, 0x20, 0xa1, 0x63, 0xd7)^
  1498         -<tr>^(<td valign=top align=center>8
         1500  +    <td>Header string:  0xd9, 0xd5, 0x05, 0xf9, 0x20, 0xa1, 0x63, 0xd7
         1501  +<tr><td valign=top align=center>8
  1499   1502       <td valign=top align=center>4
  1500   1503       <td>The "Page Count" - The number of pages in the next segment of the 
  1501   1504           journal, or -1 to
  1502         -        mean all content to the end of the file)^
  1503         -<tr>^(<td valign=top align=center>12
         1505  +        mean all content to the end of the file
         1506  +<tr><td valign=top align=center>12
  1504   1507       <td valign=top align=center>4
  1505         -    <td>A random nonce for the checksum)^
  1506         -<tr>^(<td valign=top align=center>16
         1508  +    <td>A random nonce for the checksum
         1509  +<tr><td valign=top align=center>16
  1507   1510       <td valign=top align=center>4
  1508         -    <td>Initial size of the database in pages)^
  1509         -<tr>^(<td valign=top align=center>20
         1511  +    <td>Initial size of the database in pages
         1512  +<tr><td valign=top align=center>20
  1510   1513       <td valign=top align=center>4
  1511   1514       <td>Size of a disk sector assumed by the process that wrote this
  1512         -        journal.)^
  1513         -<tr>^(<td valign=top align=center>24
         1515  +        journal.
         1516  +<tr><td valign=top align=center>24
  1514   1517       <td valign=top align=center>4
  1515         -    <td>Size of pages in this journal.)^
         1518  +    <td>Size of pages in this journal.
  1516   1519   </table>
  1517   1520   </center>
  1518   1521   
  1519   1522   <p>^A rollback journal header is padded with zeros out to the size of a 
  1520   1523   single sector (as defined by the sector size integer at offset 20).
  1521   1524   The header is in a sector by itself so that if a power loss occurs while
  1522   1525   writing the sector, information that follows the header will be
................................................................................
  1535   1538   in the journal header) be N.
  1536   1539   Then the format of a page record is as follows:</p>
  1537   1540   
  1538   1541   <center>
  1539   1542   <i>Rollback Journal Page Record Format</i><br>
  1540   1543   <table width="80%" border=1>
  1541   1544   <tr><th>Offset<th>Size<th>Description
  1542         -<tr>^(<td valign=top align=center>0
         1545  +<tr><td valign=top align=center>0
  1543   1546       <td valign=top align=center>4
  1544         -    <td>The page number in the database file)^
  1545         -<tr>^(<td valign=top align=center>4
         1547  +    <td>The page number in the database file
         1548  +<tr><td valign=top align=center>4
  1546   1549       <td valign=top align=center>N
  1547         -    <td>Original content of the page prior to the start of the transaction)^
  1548         -<tr>^(<td valign=top align=center>N+4
         1550  +    <td>Original content of the page prior to the start of the transaction
         1551  +<tr><td valign=top align=center>N+4
  1549   1552       <td valign=top align=center>4
  1550         -    <td>Checksum)^
         1553  +    <td>Checksum
  1551   1554   </table>
  1552   1555   </center>
  1553   1556   
  1554   1557   
  1555   1558   <p>^(The checksum is an unsigned 32-bit integer computed as follows:</p>
  1556   1559   
  1557   1560   <ol>

Changes to pages/pragma.in.

  1319   1319       <i>database</i>, or on all attached databases if <i>database</i>
  1320   1320       is omitted.  ^If [write-ahead log] mode is disabled, this pragma is a
  1321   1321       harmless no-op.</p>
  1322   1322   
  1323   1323       <p>^Invoking this
  1324   1324       pragma without an argument is equivalent to calling the
  1325   1325       [sqlite3_wal_checkpoint()] C interface.</p>
  1326         -    ^Invoking this pragma with an argument is equivalent to calling the
         1326  +    ^(Invoking this pragma with an argument is equivalent to calling the
  1327   1327       [sqlite3_wal_checkpoint_v2()] C interface with a 
  1328   1328       [SQLITE_CHECKPOINT_PASSIVE | 3rd parameter]
  1329         -    corresponding to the argument:
         1329  +    corresponding to the argument:)^
  1330   1330   
  1331   1331       <dl>
  1332         -    <dt>PASSIVE<dd>
         1332  +    ^(<dt>PASSIVE<dd>
  1333   1333         Checkpoint as many frames as possible without waiting for any database 
  1334   1334         readers or writers to finish. Sync the db file if all frames in the log
  1335         -      are checkpointed. This mode is the same as calling 
  1336         -      sqlite3_wal_checkpoint(). The
  1337         -      [sqlite3_busy_handler|busy-handler callback] is never invoked.
         1335  +      are checkpointed.)^ ^(This mode is the same as calling 
         1336  +      sqlite3_wal_checkpoint().)^ ^(The
         1337  +      [sqlite3_busy_handler|busy-handler callback] is never invoked.)^
  1338   1338      
  1339         -    <dt>FULL<dd>
         1339  +    ^(<dt>FULL<dd>
  1340   1340         This mode blocks 
  1341   1341         (invokes the [sqlite3_busy_handler|busy-handler callback])
  1342   1342         until there is no
  1343   1343         database writer and all readers are reading from the most recent database
  1344   1344         snapshot. It then checkpoints all frames in the log file and syncs the
  1345         -      database file. This call blocks database writers while it is running,
  1346         -      but not database readers.
         1345  +      database file.)^ ^(FULL blocks database writers while it is
         1346  +      running, but not database readers.)^
  1347   1347      
  1348         -    <dt>RESTART<dd>
         1348  +    ^(<dt>RESTART<dd>
  1349   1349         This mode works the same way as SQLITE_CHECKPOINT_FULL, except after 
  1350   1350         checkpointing the log file it blocks (calls the 
  1351   1351         [sqlite3_busy_handler|busy-handler callback])
  1352         -      until all readers are reading from the database file only. This ensures 
         1352  +      until all readers are reading from the database file only.)^ This ensures 
  1353   1353         that the next client to write to the database file restarts the log file 
  1354         -      from the beginning. This call blocks database writers while it is running,
  1355         -      but not database readers.
         1354  +      from the beginning. ^(RESTART blocks database writers while it is
         1355  +      running, but not database readers.)^
  1356   1356       </dl>
  1357   1357   
  1358   1358   
  1359   1359       <p>^The wal_checkpoint pragma returns a single row with three
  1360   1360       integer columns.  ^The first column is usually 0 but will be
  1361   1361       1 if a RESTART or FULL checkpoint was blocked from completing,
  1362   1362       for example because another thread or process was actively
................................................................................
  1375   1375   
  1376   1376   Pragma wal_autocheckpoint {
  1377   1377       <p><b>PRAGMA wal_autocheckpoint;<br>
  1378   1378        PRAGMA wal_autocheckpoint=</b><i>N</i><b>;</b></p>
  1379   1379   
  1380   1380       <p>^This pragma queries or sets the [write-ahead log] 
  1381   1381       [checkpointing | auto-checkpoint] interval.
  1382         -    When the [write-ahead log] is enabled (via the
         1382  +    ^When the [write-ahead log] is enabled (via the
  1383   1383       [journal_mode pragma]) a checkpoint will be run automatically whenever
  1384   1384       the write-ahead log equals or exceeds <i>N</i> pages in length.
  1385         -    Setting the auto-checkpoint size to zero or a negative value
         1385  +    ^Setting the auto-checkpoint size to zero or a negative value
  1386   1386       turns auto-checkpointing off.</p>
  1387   1387       
  1388   1388       <p>^This pragma is a wrapper around the
  1389   1389       [sqlite3_wal_autocheckpoint()] C interface.
  1390         -    All automatic checkpoints are [sqlite3_wal_checkpoint_v2|PASSIVE].</p>
         1390  +    ^All automatic checkpoints are [sqlite3_wal_checkpoint_v2|PASSIVE].</p>
  1391   1391   
  1392   1392       <p>^Autocheckpointing is enabled by default with an interval
  1393   1393       of 1000 or [SQLITE_DEFAULT_WAL_AUTOCHECKPOINT].</p>
  1394   1394   
  1395   1395   }
  1396   1396   
  1397   1397   Pragma ignore_check_constraints {