Documentation Source Text

Check-in [a4e4f94863]
Login

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

Overview
Comment:Preliminary documentation for the .sha3sum and .selftest commands of the CLI.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: a4e4f94863a9977803c47f344346f755212ea199
User & Date: drh 2017-03-15 13:56:48
Context
2017-03-15
14:08
Fix typos and improve the wording of the .selftest documentation. check-in: 6aaee6c270 user: drh tags: trunk
13:56
Preliminary documentation for the .sha3sum and .selftest commands of the CLI. check-in: a4e4f94863 user: drh tags: trunk
2017-03-14
23:28
Tighten and formalize the hack in althttpd that allows .well-known path prefixes on URIs. check-in: adbefa195f user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to pages/changes.in.

    33     33       [CHECK constraints].
    34     34   <li>Enhance the query plans for joins to detect empty tables early and
    35     35       halt without doing unnecessary work.
    36     36   <li>Enhance the [sqlite3_mprintf()] family of interfaces and the [printf SQL function]
    37     37       to put comma separators at the thousands marks for integers, if the "," format modifier
    38     38       is used in between the "%" and the "d" (example: "%,d").
    39     39   <li>Added the -D[SQLITE_MAX_MEMORY]=<i>N</i> compile-time option.
           40  +<li>Added the [.sha3sum dot-command] and the [.selftest dot-command] 
           41  +    to the [command-line shell]
    40     42   <li>Various performance improvements.
    41     43   <p><b>Bug Fixes:</b>
    42     44   <li>Ensure that indexed expressions with collating sequences are handled correctly.
    43     45       Fix for ticket [https://www.sqlite.org/src/info/eb703ba7b50c1a5|eb703ba7b50c1a5].
    44     46   <li>Fix a bug in the 'start of ...' modifiers for the [date and time functions].
    45     47       Ticket [https://www.sqlite.org/src/info/6097cb92745327a1|6097cb92745327a1]
    46     48   <li>In the [RBU extension], add extra sync operations to avoid the possibility of

Changes to pages/cli.in.

   730    730   as a second argument to the ".load" command.
   731    731   
   732    732   <p>Source code for several useful extensions can be found in the
   733    733   <a href="http://www.sqlite.org/src/tree?name=ext/misc&ci=trunk">ext/misc</a>
   734    734   subdirectory of the SQLite source tree.  You can use these extensions
   735    735   as-is, or as a basis for creating your own custom extensions to address
   736    736   your own particular needs.
          737  +
          738  +<tcl>hd_fragment sha3sum {.sha3sum dot-command}</tcl>
          739  +<h1>Cryptographic Hashes Of Database Content</h1>
          740  +
          741  +<p>The ".sha3sum" dot-command computes a
          742  +[https://en.wikipedia.org/wiki/SHA-3|SHA3] hash of the <em>content</em>
          743  +of the database.  To be clear, the hash is computed over the database content,
          744  +not its representation on disk.  This means, for example, that a [VACUUM]
          745  +or similar data-preserving transformation does not change the hash.
          746  +
          747  +<p>The ".sha3sum" command supports options "--sha3-224", "--sha3-256", 
          748  +"--sha3-384", and "--sha3-512" to define which variety of SHA3 to use
          749  +for the hash.  The default is SHA3-256.
          750  +
          751  +<p>The database schema (in the [sqlite_master] table) is not normally
          752  +included in the hash, but can be added by the "--schema" option.
          753  +
          754  +<p>The ".sha3sum" command takes a single optional argument which is a
          755  +[LIKE] pattern.  If this option is present, only tables whose names match
          756  +the [LIKE] pattern will be hashed.
          757  +
          758  +<p>The ".sha3sum" command is implemented with the help of the
          759  +[https://www.sqlite.org/src/file/ext/misc/shathree.c|extension function "sha3_query()"]
          760  +that is included with the command-line shell.
          761  +
          762  +<tcl>hd_fragment selftest {.selftest dot-command}</tcl>
          763  +<h1>Database Content Self-Tests</h1>
          764  +
          765  +<p>The ".selftest" command attempts to verify that a database is
          766  +intact and is not corrupt.
          767  +
          768  +<p>The ".selftest" command looks for a table in schema named "selftest"
          769  +and defined as follows:
          770  +
          771  +<tcl>DisplayCode {
          772  +CREATE TABLE selftest(
          773  +  tno INTEGER PRIMARY KEY,  -- Test number
          774  +  op TEXT,                  -- 'run' or 'memo'
          775  +  cmd TEXT,                 -- SQL command to run, or text of "memo"
          776  +  ans TEXT                  -- Expected result of the SQL command
          777  +);
          778  +}</tcl>
          779  +
          780  +<p>The .selftest command reads the rows of selftest in "tno" order.
          781  +For each 'memo' row, it writes the text in 'cmd' to the screen.  For
          782  +each 'run' row, it runs the 'cmd' text as SQL and compares the result
          783  +to the value in 'ans', and shows an error message if the two differ.
          784  +
          785  +<p>If there is no selftest table, the ".selftest" command runs
          786  +a [PRAGMA integrity_check].
          787  +
          788  +<p>The ".selftest --init" command creates the selftest table if it
          789  +does not already exists, then appends entries that check the SHA3
          790  +hash of the content of all tables.  Subsequent runs of ".selftest"
          791  +will verify that the database has not been changed in any way.  To
          792  +generates tests to verify that a subset of the tables are unchanged,
          793  +simply run ".selftest --init" then [DELETE] the selftest rows that
          794  +refer to tables that are not constant.  
   737    795   
   738    796   <tcl>hd_fragment dotother</tcl>
   739    797   <h1>Other Dot Commands</h1>
   740    798   
   741    799   <p>There are many other dot-commands available in the command-line
   742    800   shell.  See the ".help" command for a complete list for any particular
   743    801   version and build of SQLite.