Documentation Source Text

Check-in [b8e6ac4ce4]
Login

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

Overview
Comment:Fix documentation typos pointed out on the mailing list by Philip Newton.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: b8e6ac4ce4cfa9634dc55ab40d3714e946443e61
User & Date: drh 2013-11-18 18:48:24
Context
2013-11-18
20:57
Correct minor typo. check-in: 9589b9982b user: mistachkin tags: trunk
18:48
Fix documentation typos pointed out on the mailing list by Philip Newton. check-in: b8e6ac4ce4 user: drh tags: trunk
2013-11-15
16:22
Fix a typo in the WITHOUT ROWID documentation. check-in: 5725d732c9 user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to pages/compile.in.

   630    630     the [query planner] that can help SQLite to chose a better query plan
   631    631     under certain situations.  The [ANALYZE] command is enhanced to collect
   632    632     histogram data from all columns of every index and store that data
   633    633     in the [sqlite_stat4] table.  The query planner will then use the
   634    634     histogram data to help it make better index choices.  The downside of
   635    635     this compile-time option is that it violates the
   636    636     [query planner stability guarantee] making it more difficult to ensure
   637         -  consistent performance is mass-produced applications.
          637  +  consistent performance in mass-produced applications.
   638    638     <p>
   639    639     SQLITE_ENABLE_STAT4 is an enhancement of [SQLITE_ENABLE_STAT3].  STAT3
   640    640     only recorded histogram data for the left-most column of each index
   641    641     whereas the STAT4 enhancement records histograph data from all columns
   642    642     of each index.
   643    643     The [SQLITE_ENABLE_STAT3] compile-time option is a no-op and is ignored
   644    644     if the SQLITE_ENABLE_STAT4 compile-time option is used.

Changes to pages/faq.in.

   523    523     rare bugs (see 
   524    524     <a href="http://www.sqlite.org/cvstrac/wiki?p=DatabaseCorruption">DatabaseCorruption</a>) 
   525    525     and even then the bugs are normally difficult to
   526    526     reproduce.  Even if your application crashes in the middle of an
   527    527     update, your database is safe.  The database is safe even if your OS
   528    528     crashes or takes a power loss.  The crash-resistance of SQLite has
   529    529     been extensively studied and tested and is attested by years of real-world 
   530         -  experience by millions of users."</p>
          530  +  experience by millions of users.</p>
   531    531   
   532    532     <p>That said, there are a number of things that external programs or bugs
   533    533     in your hardware or OS can do to corrupt a database file.  Details
   534    534     can be found in the discussions on the 
   535    535     <a href="atomiccommit.html">atomic commit</a> and 
   536    536     <a href="lockingv3.html">locking</a> support in SQLite
   537    537     as well as in the mailing list archives.</p>
................................................................................
   564    564   }
   565    565   
   566    566   faq {
   567    567     I get a compiler error if I use the SQLITE_OMIT_... 
   568    568     compile-time options when building SQLite.
   569    569   } {
   570    570     The [omitfeatures | SQLITE_OMIT_...] compile-time options only work
   571         -  when building from canonically source files.  They do <u>not</u> work
          571  +  when building from canonical source files.  They do <u>not</u> work
   572    572     when you build from the SQLite [amalgamation] or from the pre-processed
   573    573     source files.
   574    574   
   575    575     <p>It is possible to build a special [amalgamation] that will work with
   576    576     a predetermined set of SQLITE_OMIT_... options.  Instructions for doing
   577    577     so can be found with the [omitfeatures | SQLITE_OMIT_... documentation].
   578    578   }
................................................................................
   580    580   faq {
   581    581     My WHERE clause expression <tt>column1="column1"</tt> does not work.
   582    582     It causes every row of the table to be returned, not just the rows
   583    583     where column1 has the value "column1".
   584    584   } {
   585    585     Use single-quotes, not double-quotes, around string literals in SQL.
   586    586     This is what the SQL standard requires.  Your WHERE clause expression
   587         -  should read: <tt>column1='column2'</tt>
          587  +  should read: <tt>column1='column1'</tt>
   588    588   
   589    589     <p>SQL uses double-quotes around identifiers (column or table names) that
   590    590     contains special characters or which are keywords.  So double-quotes are
   591    591     a way of escaping identifier names.  Hence, when you say
   592    592     <tt>column1="column1"</tt> that is equivalent to 
   593    593     <tt>column1=column1</tt> which is obviously always true.
   594    594   }

Changes to pages/fileformat2.in.

   174    174   18 and 19 are intended to allow for enhancements of the file format
   175    175   in future versions of SQLite.  In current versions of SQLite, both of
   176    176   these values are 1 for rollback journalling modes and 2 for [WAL]
   177    177   journalling mode.  If a version of SQLite coded to the current
   178    178   file format specification encounters a database file where the read
   179    179   version is 1 or 2 but the write version is greater than 2, then the database
   180    180   file must be treated as read-only.  If a database file with a read version
   181         -greater than 2 is encounter, then that database cannot be read or written.</p>
          181  +greater than 2 is encountered, then that database cannot be read or written.</p>
   182    182   
   183    183   <h4>1.2.4 Reserved bytes per page</h4>
   184    184   
   185    185   <p>SQLite has the ability to set aside a small number of extra bytes at
   186    186   the end of every page for use by extensions.  These extra bytes are
   187    187   used, for example, by the SQLite Encryption Extension to store a nonce
   188    188   and/or cryptographic checksum associated with each page.  ^The 
................................................................................
   198    198   allowed to be less than 480.  In other words, if the page size is 512,
   199    199   then the reserved space size cannot exceed 32.)^</p>
   200    200   
   201    201   <h4>1.2.5 Payload fractions</h4>
   202    202   
   203    203   <p>^The maximum and minimum embedded payload fractions and the leaf
   204    204   payload fraction values must be 64, 32, and 32.  These values were
   205         -originally intended to as tunable parameters that could be used to
          205  +originally intended to be tunable parameters that could be used to
   206    206   modify the storage format of the b-tree algorithm.  However, that
   207    207   functionality is not supported and there are no current plans to add
   208    208   support in the future.  Hence, these three bytes are fixed at the
   209    209   values specified.</p>
   210    210   
   211    211   <h4>1.2.6 File change counter</h4>
   212    212   

Changes to pages/howtocorrupt.in.

   145    145   and will be unable to work around the POSIX advisory locking quirks.
   146    146   A <tt>close()</tt> operation on one connection might unknowingly 
   147    147   clear the locks on a different database connection, leading to database
   148    148   corruption.</p>
   149    149   
   150    150   <p>The scenario above sounds far-fetched.
   151    151   But the SQLite developers are aware of at 
   152         -least one commercial product that was release
          152  +least one commercial product that was released
   153    153   with exactly this bug.  The vendor came to the SQLite developers seeking
   154    154   help in tracking down some infrequent database corruption issues they were
   155    155   seeing on Linux and Mac.  The problem was eventually traced to the
   156    156   fact that the application was linking against two separate copies of SQLite.
   157    157   The solution was to change the application build procedures to link against
   158    158   just one copy of SQLite instead of two.</p>
   159    159   
................................................................................
   167    167   be select for use in an application that has to run on an NFS filesystem
   168    168   that does not support POSIX advisory locking.</p>
   169    169   
   170    170   <p>It is important that all connections to the same database file use 
   171    171   the same locking protocol.
   172    172   If one application is using POSIX advisory locks and another application
   173    173   is using dot-file locking, then the two applications will not see each
   174         -others locks and will not be able to coordinate database access, possibly
          174  +other's locks and will not be able to coordinate database access, possibly
   175    175   leading to database corruption.</p>
   176    176   
   177    177   <tcl>hd_fragment unlink {unlink corruption} {unlinked database files}</tcl>
   178    178   <h3>2.4 Unlinking or renaming a database file while in use</h3>
   179    179   
   180    180   <p>If two processes have open connections to the same database file and
   181    181   one process closes its connection, unlinks the file, then creates a new
................................................................................
   215    215   
   216    216   <h2>3.0 Failure to sync</h2>
   217    217   
   218    218   <p>In order to guarantee that database files are always consistent, SQLite
   219    219   will occasionally ask the operating system to flush all pending writes to
   220    220   persistent storage then wait for that flush to complete.  This is 
   221    221   accomplished using the <tt>fsync()</tt> system call under unix and
   222         -<tt>FlushFileBuffers()</tt> under windows.  We call this flush of
          222  +<tt>FlushFileBuffers()</tt> under Windows.  We call this flush of
   223    223   pending writes a "sync".</p>
   224    224   
   225    225   <p>Actually, if one is only concerned with atomic and consistent writes and
   226    226   is willing to forego durable writes, the sync operation does not need
   227    227   to wait until the content is completely stored on persistent media.  Instead,
   228    228   the sync operation can be thought of as an I/O barrier.  As long as all
   229    229   writes that occur before the sync are completed before any write that happens
................................................................................
   394    394   historical bugs in SQLite (now fixed) that could cause database corruption.
   395    395   And there may be yet a few more that remain undiscovered.  Because of the
   396    396   extensive testing and widespread use of SQLite, bugs that result in
   397    397   database corruption tend to be very obscure.  The likelihood
   398    398   of an application encountering an SQLite bug is small.  To illustrate this,
   399    399   an account is given below 
   400    400   of all database-corruption bugs found in SQLite during the
   401         -two-year period from 2009-04-01 to 2013-04-15.
          401  +four-year period from 2009-04-01 to 2013-04-15.
   402    402   This account should give the reader an intuitive sense of the
   403    403   kinds of bugs in SQLite that manage to slip through testing procedures
   404    404   and make it into a release.</p>
   405    405   
   406    406   
   407    407   <h3>7.1 False corruption reports due to database shrinkage</h3>
   408    408   
   409    409   <p>If a database is written by SQLite version 3.7.0 or later and then
   410    410   written again by SQLite version 3.6.23 or earlier in such a way as to
   411    411   make the size of the database file decrease, then the next time that
   412    412   SQLite version 3.7.0 access the database file, it might report that the
   413    413   database file is corrupt.  The database file is not really corrupt, however.
   414         -Version 3.7.0 was simply begin overly zealous in its corruption detection.</p>
          414  +Version 3.7.0 was simply being overly zealous in its corruption detection.</p>
   415    415   
   416    416   <p>The problem was fixed on 2011-02-20.  The fix first appears in
   417    417   SQLite version 3.7.6.</p>
   418    418   
   419         -<h3>7.2 Corruption follow switches between rollback and WAL modes</h3>
          419  +<h3>7.2 Corruption following switches between rollback and WAL modes</h3>
   420    420   
   421    421   <p>Repeatedly switching an SQLite database in and out of [WAL | WAL mode]
   422    422   and running the [VACUUM] command in between switches, in one process or
   423    423   thread, can cause another process or thread that has the database file
   424    424   open to miss the fact that the database has changed.  That second process
   425    425   or thread might then try to modify the database using a stale cache and
   426    426   cause database corruption.</p>
................................................................................
   486    486   has already completed, allowing that process to continue using the
   487    487   database file without running recovery first.  If that process writes
   488    488   to the file, then the file might go corrupt.  This race condition
   489    489   had apparently existing in all prior versions of SQLite for Windows going
   490    490   back to 2004.  But the race was very tight.  Practically speaking, you
   491    491   need a fast multi-core machine in which you launch two processes to run
   492    492   recovery at the same moment on two separate cores.  This defect was
   493         -on windows systems only and did not effect the posix OS interface.</p>
          493  +on Windows systems only and did not affect the posix OS interface.</p>

Changes to pages/lang.in.

  1135   1135   <h3>The RAISE() function</h3>
  1136   1136   
  1137   1137   <p>^(A special SQL function RAISE() may be used within a trigger-program,)^
  1138   1138   with the following syntax</p> 
  1139   1139   
  1140   1140   <tcl>BubbleDiagram raise-function</tcl>
  1141   1141   
  1142         -<p>^When one of the first three forms is called during trigger-program
         1142  +<p>^(When one of RAISE(ROLLBACK,...), RAISE(ABORT,...) or RAISE(FAIL,...)
         1143  +is called during trigger-program
  1143   1144   execution, the specified [ON CONFLICT] processing is performed
  1144         -(either ABORT, FAIL or ROLLBACK) and the current query terminates.
         1145  +the current query terminates.)^
  1145   1146   An error code of [SQLITE_CONSTRAINT] is returned to the application,
  1146   1147   along with the specified error message.</p>
  1147   1148   
  1148   1149   <p>^When RAISE(IGNORE) is called, the remainder of the current trigger program,
  1149   1150   the statement that caused the trigger program to execute and any subsequent
  1150         -trigger programs that would of been executed are abandoned. ^No database
         1151  +trigger programs that would have been executed are abandoned. ^No database
  1151   1152   changes are rolled back.  ^If the statement that caused the trigger program
  1152   1153   to execute is itself part of a trigger program, then that trigger program
  1153   1154   resumes execution at the beginning of the next step.
  1154   1155   </p>
  1155   1156   
  1156   1157   <tcl>hd_fragment temptrig {TEMP triggers on non-TEMP tables}</tcl>
  1157   1158   <h3>TEMP Triggers on Non-TEMP Tables</h3>
................................................................................
  1749   1750   [glob(<i>Y</i>,<i>X</i>)] and can be modified by overriding
  1750   1751   that function.</p>
  1751   1752   
  1752   1753   <tcl>hd_fragment regexp REGEXP</tcl>
  1753   1754   <p>^The REGEXP operator is a special syntax for the regexp()
  1754   1755   user function.  ^No regexp() user function is defined by default
  1755   1756   and so use of the REGEXP operator will normally result in an
  1756         -error message.  ^If a [application-defined SQL function] named "regexp"
  1757         -is added at run-time, that function will be called in order
  1758         -to implement the REGEXP operator.</p>
         1757  +error message.  ^If an [application-defined SQL function] named "regexp"
         1758  +is added at run-time, then the "<i>X</i> REGEXP <i>Y</i>" operator will
         1759  +be implemented as a call to "regexp(<i>Y</i>,<i>X</i>)".</p>
  1759   1760   
  1760   1761   <tcl>hd_fragment match MATCH</tcl>
  1761   1762   <p>^The MATCH operator is a special syntax for the match()
  1762   1763   application-defined function.  ^The default match() function implementation
  1763   1764   raises an exception and is not really useful for anything.
  1764   1765   ^But extensions can override the match() function with more
  1765   1766   helpful logic.</p>

Changes to pages/lockingv3.in.

   376    376       </li>
   377    377   <li>Drop the EXCLUSIVE and PENDING locks from the database file.
   378    378       </li>
   379    379   </ol>
   380    380   
   381    381   <p>As soon as the PENDING lock is released from the database file, other
   382    382   processes can begin reading the database again.  In the current implementation,
   383         -the RESERVED lock is also released, but that is not essential.  Future
   384         -versions of SQLite might provide a "CHECKPOINT" SQL command that will
   385         -commit all changes made so far within a transaction but retain the
   386         -RESERVED lock so that additional changes can be made without given
   387         -any other process an opportunity to write.</p>
          383  +the RESERVED lock is also released, but that is not essential for
          384  +correct operation.</p>
   388    385   
   389    386   <p>If a transaction involves multiple databases, then a more complex
   390    387   commit sequence is used, as follows:</p>
   391    388   
   392    389   <ol>
   393    390   <li value="4">
   394    391      Make sure all individual database files have an EXCLUSIVE lock and a

Changes to pages/malloc.in.

    50     50   errors.
    51     51   </p></li>
    52     52   
    53     53   <li><p>
    54     54   <b>Memory usage limits.</b>
    55     55   The [sqlite3_soft_heap_limit64()] mechanism allows the application to
    56     56   set a memory usage limit that SQLite strives to stay below.  SQLite
    57         -will attempt to reuse memory from its caches rather than allocation new
           57  +will attempt to reuse memory from its caches rather than allocating new
    58     58   memory as it approaches the soft limit.
    59     59   </p></li>
    60     60   
    61     61   <li><p>
    62     62   <b>Zero-malloc option</b>
    63     63   The application can provide SQLite with several buffers of bulk memory
    64     64   at startup and SQLite will then use those provided buffers for all of
................................................................................
   346    346   
   347    347   <p>Memsys6 was added in SQLite [version 3.6.1].
   348    348   It is very experimental.  Its future is uncertain and it may be removed
   349    349   in a subsequent release.  Update:  Memsys6 was removed as of 
   350    350   [version 3.6.5].</p>
   351    351   
   352    352   <p>Other experimental memory allocators might be added in future releases
   353         -of SQLite.  One many anticipate that these will be called memsys7, memsys8,
          353  +of SQLite.  One may anticipate that these will be called memsys7, memsys8,
   354    354   and so forth.</p>
   355    355   
   356    356   <a name="appalloc"></a>
   357    357   <h4>3.1.5 Application-defined memory allocators</h4>
   358    358   
   359    359   <p>New memory allocators do not have to be part of the SQLite source tree
   360    360   nor included in the sqlite3.c [amalgamation].  Individual applications can

Changes to pages/optoverview.in.

   315    315     <ol>
   316    316     <li>^The left-hand side of the LIKE or GLOB operator must be the name
   317    317         of an indexed column with [affinity | TEXT affinity].</li>
   318    318     <li>^The right-hand side of the LIKE or GLOB must be either a string literal
   319    319         or a [parameter] bound to a string literal
   320    320         that does not begin with a wildcard character.</li>
   321    321     <li>^The ESCAPE clause cannot appear on the LIKE operator.</li>
   322         -  <li>^The build-in functions used to implement LIKE and GLOB must not
          322  +  <li>^The built-in functions used to implement LIKE and GLOB must not
   323    323         have been overloaded using the sqlite3_create_function() API.</li>
   324    324     <li>^For the GLOB operator, the column must be indexed using the 
   325    325         built-in BINARY collating sequence.</li>
   326    326     <li>^For the LIKE operator, if [case_sensitive_like] mode is enabled then
   327    327         the column must indexed using BINARY collating sequence, or if
   328    328         [case_sensitive_like] mode is disabled then the column must indexed
   329    329         using built-in NOCASE collating sequence.</li>

Changes to pages/pragma.in.

   127    127     
   128    128   <p>    ^The application_id PRAGMA is used to query or set the 32-bit
   129    129          unsigned big-endian "Application ID" integer located at offset
   130    130          68 into the [database header].  Applications that use SQLite as their
   131    131          [application file-format] should set the Application ID integer to
   132    132          a unique integer so that utilities such as 
   133    133          [http://www.darwinsys.com/file/ | file(1)] can determine the specific
   134         -       file type rather than just reporting "SQLite3 Database".  A list
          134  +       file type rather than just reporting "SQLite3 Database".  A list of
   135    135          assigned application IDs can be seen by consulting the
   136    136          [http://www.sqlite.org/src/artifact?ci=trunk&filename=magic.txt
   137    137           |magic.txt] file in the SQLite source repository.
   138    138   }
   139    139   
   140    140   Pragma {automatic_index} {
   141    141       <p>^(<b>PRAGMA automatic_index;

Changes to pages/queryplanner-ng.in.

   358    358   There are no API changes nor modifications
   359    359   to compilation procedures.</p>
   360    360   
   361    361   <p>But as with any query planner change, upgrading to the NGQP does carry
   362    362   a small risk of introducing performance regressions.  The problem here is
   363    363   not that the NGQP is incorrect or buggy or inferior to the legacy query
   364    364   planner.  Given reliable information about the selectivity of indices, 
   365         -the NGQP should always pick a plan than is as good or better than before.
          365  +the NGQP should always pick a plan that is as good or better than before.
   366    366   The problem is that some applications may be using low-quality and
   367    367   low-selectivity indices without having run [ANALYZE].  The older query
   368    368   planners look at many fewer possible implementations for each query and 
   369    369   so they may have stumbled over a good plan by stupid luck.  The NGQP, on 
   370    370   the other hand, looks at many more query plan possibilities, and it may 
   371    371   chose a different query plan that
   372    372   works better in theory, assuming good indices, but which gives a performance

Changes to pages/tempfiles.in.

   128    128   as described above.  The PERSIST journal mode foregoes the deletion of
   129    129   the journal file and instead overwrites the rollback journal header
   130    130   with zeros, which prevents other processes from rolling back the
   131    131   journal and thus has the same effect as deleting the journal file, though
   132    132   without the expense of actually removing the file from disk.  In other
   133    133   words, journal mode PERSIST exhibits the same behavior as is seen
   134    134   in EXCLUSIVE locking mode. The
   135         -OFF journal mode causes SQLite to the rollback journal.
          135  +OFF journal mode causes SQLite to omit the rollback journal, completely.
          136  +In other words, no rollback journal is every written if journal mode is
          137  +set to OFF.
   136    138   The OFF journal mode disables the atomic
   137    139   commit and rollback capabilities of SQLite.  The ROLLBACK command
   138    140   is not available when OFF journal mode is set.  And if a crash or power
   139    141   loss occurs in the middle of a transaction that uses the OFF journal
   140    142   mode, no recovery is possible and the database file will likely
   141    143   go corrupt.
   142    144   The MEMORY journal mode causes the rollback journal to be stored in
................................................................................
   415    417   
   416    418   <p>
   417    419   More complex queries may or may not be able to employ query
   418    420   flattening to avoid the temporary table.  Whether or not
   419    421   the query can be flattened depends on such factors as whether
   420    422   or not the subquery or outer query contain aggregate functions,
   421    423   ORDER BY or GROUP BY clauses, LIMIT clauses, and so forth.
   422         -The rules for when a query and cannot be flattened are
          424  +The rules for when a query can and cannot be flattened are
   423    425   very complex and are beyond the scope of this document.
   424    426   </p>
   425    427   
   426    428   <tcl>hd_fragment transidx</tcl>
   427    429   <h3>2.8 Transient Indices</h3>
   428    430   
   429    431   <p>
................................................................................
   462    464   compared to the previous to see if it starts a new "group".
   463    465   The ordering by GROUP BY terms is done in exactly the same way
   464    466   as the ordering by ORDER BY terms.  A preexisting index is used
   465    467   if possible, but if no suitable index is available, a transient
   466    468   index is created.
   467    469   </p>
   468    470   
   469         -<p>
   470         -The previous two paragraphs describe the implementation of SQLite
   471         -as of version 3.5.8.  There are known problems with this approach
   472         -for very large results sets - result sets that are larger than the
   473         -available disk cache.  Future versions of SQLite will likely address
   474         -this deficiency by completely reworking the sort algorithm for 
   475         -cases when no suitable preexisting sort index is available.  The
   476         -new sort algorithm will also use temporary files, but not in the
   477         -same way as the current implementation, the temporary files
   478         -for the new implementation will probably not be index files.
   479         -</p>
   480         -
   481    471   <p>
   482    472   The DISTINCT keyword on an aggregate query is implemented by
   483    473   creating a transient index in a temporary file and storing
   484    474   each result row in that index.  As new result rows are computed
   485    475   a check is made to see if they already exist in the transient
   486    476   index and if they do the new result row is discarded.
   487    477   </p>

Changes to pages/wal.in.

    44     44       [wal-index] shared memory file associated with the database, if that
    45     45       file exists, or else write access on the directory containing
    46     46       the database file if the "<tt>-shm</tt>" file does not exist.
    47     47   <li>WAL might be very slightly slower (perhaps 1% or 2% slower)
    48     48       than the traditional rollback-journal approach
    49     49       in applications that do mostly reads and seldom write.
    50     50   <li>There is an additional quasi-persistent "<tt>-wal</tt>" file and
    51         -    "<tt>-shm</tt> shared memory file associated with each
           51  +    "<tt>-shm</tt>" shared memory file associated with each
    52     52       database, which can make SQLite less appealing for use as an 
    53     53       [application file-format].
    54     54   <li>There is the extra operation of [checkpointing] which, though automatic
    55     55       by default, is still something that application developers need to
    56     56       be mindful of.
    57     57   <li>WAL works best with smaller transactions.  WAL does
    58     58       not work well for very large transactions.  For transactions larger than