/ Check-in [8c1e85aa]
Login

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

Overview
Comment:Clearification of some documentation text. Added requirements marks.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 8c1e85aab9e0d90726057e25e2ea0663341c070f
User & Date: drh 2015-03-06 04:37:26
Context
2015-03-07
13:56
Fix the LIKE optimization so that it finds BLOB entries in addition to text entries. Ticket [05f43be8fdda9f]. check-in: 74cb0b03 user: drh tags: trunk
2015-03-06
16:45
The LIKE optimization must be applied twice, once for strings and a second time for BLOBs. Ticket [05f43be8fdda9f]. This check-in is a proof-of-concept of how that might be done. check-in: 5757e803 user: drh tags: like-opt-fix
04:37
Clearification of some documentation text. Added requirements marks. check-in: 8c1e85aa user: drh tags: trunk
03:31
Clarification of documentation on sqlite3_backup. check-in: 31d5e9b4 user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to src/pragma.c.

   313    313     if( sqlite3AuthCheck(pParse, SQLITE_PRAGMA, zLeft, zRight, zDb) ){
   314    314       goto pragma_out;
   315    315     }
   316    316   
   317    317     /* Send an SQLITE_FCNTL_PRAGMA file-control to the underlying VFS
   318    318     ** connection.  If it returns SQLITE_OK, then assume that the VFS
   319    319     ** handled the pragma and generate a no-op prepared statement.
          320  +  **
          321  +  ** IMPLEMENTATION-OF: R-12238-55120 Whenever a PRAGMA statement is parsed,
          322  +  ** an SQLITE_FCNTL_PRAGMA file control is sent to the open sqlite3_file
          323  +  ** object corresponding to the database file to which the pragma
          324  +  ** statement refers.
          325  +  **
          326  +  ** IMPLEMENTATION-OF: R-29875-31678 The argument to the SQLITE_FCNTL_PRAGMA
          327  +  ** file control is an array of pointers to strings (char**) in which the
          328  +  ** second element of the array is the name of the pragma and the third
          329  +  ** element is the argument to the pragma or NULL if the pragma has no
          330  +  ** argument.
   320    331     */
   321    332     aFcntl[0] = 0;
   322    333     aFcntl[1] = zLeft;
   323    334     aFcntl[2] = zRight;
   324    335     aFcntl[3] = 0;
   325    336     db->busyHandler.nBusy = 0;
   326    337     rc = sqlite3_file_control(db, zDb, SQLITE_FCNTL_PRAGMA, (void*)aFcntl);

Changes to src/sqlite.h.in.

   747    747   ** CAPI3REF: Standard File Control Opcodes
   748    748   ** KEYWORDS: {file control opcodes} {file control opcode}
   749    749   **
   750    750   ** These integer constants are opcodes for the xFileControl method
   751    751   ** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]
   752    752   ** interface.
   753    753   **
          754  +** <ul>
          755  +** <li>[[SQLITE_FCNTL_LOCKSTATE]]
   754    756   ** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging.  This
   755    757   ** opcode causes the xFileControl method to write the current state of
   756    758   ** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
   757    759   ** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
   758    760   ** into an integer that the pArg argument points to. This capability
   759         -** is used during testing and only needs to be supported when SQLITE_TEST
   760         -** is defined.
   761         -** <ul>
          761  +** is used during testing and is only available when the SQLITE_TEST
          762  +** compile-time option is used.
          763  +**
   762    764   ** <li>[[SQLITE_FCNTL_SIZE_HINT]]
   763    765   ** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS
   764    766   ** layer a hint of how large the database file will grow to be during the
   765    767   ** current transaction.  This hint is not guaranteed to be accurate but it
   766    768   ** is often close.  The underlying VFS might choose to preallocate database
   767    769   ** file space based on this hint in order to help writes to the database
   768    770   ** file run faster.
................................................................................
   879    881   ** of the char** argument point to a string obtained from [sqlite3_mprintf()]
   880    882   ** or the equivalent and that string will become the result of the pragma or
   881    883   ** the error message if the pragma fails. ^If the
   882    884   ** [SQLITE_FCNTL_PRAGMA] file control returns [SQLITE_NOTFOUND], then normal 
   883    885   ** [PRAGMA] processing continues.  ^If the [SQLITE_FCNTL_PRAGMA]
   884    886   ** file control returns [SQLITE_OK], then the parser assumes that the
   885    887   ** VFS has handled the PRAGMA itself and the parser generates a no-op
   886         -** prepared statement.  ^If the [SQLITE_FCNTL_PRAGMA] file control returns
          888  +** prepared statement if result string is NULL, or that returns a copy
          889  +** of the result string if the string is non-NULL.
          890  +** ^If the [SQLITE_FCNTL_PRAGMA] file control returns
   887    891   ** any result code other than [SQLITE_OK] or [SQLITE_NOTFOUND], that means
   888    892   ** that the VFS encountered an error while handling the [PRAGMA] and the
   889    893   ** compilation of the PRAGMA fails with an error.  ^The [SQLITE_FCNTL_PRAGMA]
   890    894   ** file control occurs at the beginning of pragma statement analysis and so
   891    895   ** it is able to override built-in [PRAGMA] statements.
   892    896   **
   893    897   ** <li>[[SQLITE_FCNTL_BUSYHANDLER]]

Changes to src/test_multiplex.c.

  1000   1000       case SQLITE_FCNTL_SIZE_HINT:
  1001   1001       case SQLITE_FCNTL_CHUNK_SIZE:
  1002   1002         /* no-op these */
  1003   1003         rc = SQLITE_OK;
  1004   1004         break;
  1005   1005       case SQLITE_FCNTL_PRAGMA: {
  1006   1006         char **aFcntl = (char**)pArg;
         1007  +      /*
         1008  +      ** EVIDENCE-OF: R-29875-31678 The argument to the SQLITE_FCNTL_PRAGMA
         1009  +      ** file control is an array of pointers to strings (char**) in which the
         1010  +      ** second element of the array is the name of the pragma and the third
         1011  +      ** element is the argument to the pragma or NULL if the pragma has no
         1012  +      ** argument.
         1013  +      */
  1007   1014         if( aFcntl[1] && sqlite3_stricmp(aFcntl[1],"multiplex_truncate")==0 ){
  1008   1015           if( aFcntl[2] && aFcntl[2][0] ){
  1009   1016             if( sqlite3_stricmp(aFcntl[2], "on")==0
  1010   1017              || sqlite3_stricmp(aFcntl[2], "1")==0 ){
  1011   1018               pGroup->bTruncate = 1;
  1012   1019             }else
  1013   1020             if( sqlite3_stricmp(aFcntl[2], "off")==0
  1014   1021              || sqlite3_stricmp(aFcntl[2], "0")==0 ){
  1015   1022               pGroup->bTruncate = 0;
  1016   1023             }
  1017   1024           }
         1025  +        /* EVIDENCE-OF: R-27806-26076 The handler for an SQLITE_FCNTL_PRAGMA
         1026  +        ** file control can optionally make the first element of the char**
         1027  +        ** argument point to a string obtained from sqlite3_mprintf() or the
         1028  +        ** equivalent and that string will become the result of the pragma
         1029  +        ** or the error message if the pragma fails.
         1030  +        */
  1018   1031           aFcntl[0] = sqlite3_mprintf(pGroup->bTruncate ? "on" : "off");
  1019   1032           rc = SQLITE_OK;
  1020   1033           break;
  1021   1034         }
  1022   1035         /* If the multiplexor does not handle the pragma, pass it through
  1023   1036         ** into the default case. */
  1024   1037       }

Changes to test/multiplex4.test.

    55     55     db eval {
    56     56       DELETE FROM t1;
    57     57       VACUUM;
    58     58     }
    59     59     multiplex_file_list mx4test
    60     60   } {mx4test.db}
    61     61   
           62  +# NB:  The PRAGMA multiplex_truncate command is implemented using the
           63  +# SQLITE_FCNTL_PRAGMA file-control...
           64  +#
           65  +# EVIDENCE-OF: R-12238-55120 Whenever a PRAGMA statement is parsed, an
           66  +# SQLITE_FCNTL_PRAGMA file control is sent to the open sqlite3_file
           67  +# object corresponding to the database file to which the pragma
           68  +# statement refers.
           69  +#
    62     70   do_test multiplex4-1.2 {
    63     71     db eval {PRAGMA multiplex_truncate}
    64     72   } {on}
    65     73   do_test multiplex4-1.3 {
    66     74     db eval {PRAGMA multiplex_truncate=off}
    67     75   } {off}
    68     76   do_test multiplex4-1.4 {
................................................................................
    79     87   } {off}
    80     88   do_test multiplex4-1.8 {
    81     89     db eval {PRAGMA multiplex_truncate=1}
    82     90   } {on}
    83     91   do_test multiplex4-1.9 {
    84     92     db eval {PRAGMA multiplex_truncate=0}
    85     93   } {off}
           94  +
           95  +# EVIDENCE-OF: R-26188-08449 If the SQLITE_FCNTL_PRAGMA file control
           96  +# returns SQLITE_OK, then the parser assumes that the VFS has handled
           97  +# the PRAGMA itself and the parser generates a no-op prepared statement
           98  +# if result string is NULL, or that returns a copy of the result string
           99  +# if the string is non-NULL.
          100  +#
          101  +do_test multiplex4-1.9-explain {
          102  +  db eval {EXPLAIN PRAGMA multiplex_truncate=0;}
          103  +} {/String8 \d \d \d off/}
    86    104   
    87    105   do_test multiplex4-1.10 {
    88    106     db eval {
    89    107       INSERT INTO t1(x) VALUES(randomblob(250000));
    90    108     }
    91    109     multiplex_file_list mx4test
    92    110   } {mx4test.001 mx4test.db}

Changes to test/rdonly.test.

    28     28   do_test rdonly-1.1 {
    29     29     execsql {
    30     30       CREATE TABLE t1(x);
    31     31       INSERT INTO t1 VALUES(1);
    32     32       SELECT * FROM t1;
    33     33     }
    34     34   } {1}
           35  +
           36  +# EVIDENCE-OF: R-29639-16887 The sqlite3_db_readonly(D,N) interface
           37  +# returns 1 if the database N of connection D is read-only, 0 if it is
           38  +# read/write, or -1 if N is not the name of a database on connection D.
           39  +#
    35     40   do_test rdonly-1.1.1 {
    36     41     sqlite3_db_readonly db main
    37     42   } {0}
    38     43   
    39     44   # Changes the write version from 1 to 3.  Verify that the database
    40     45   # can be read but not written.
    41     46   #

Changes to test/shrink.test.

    20     20   do_test shrink-1.1 {
    21     21     db eval {
    22     22       PRAGMA cache_size = 2000;
    23     23       CREATE TABLE t1(x,y);
    24     24       INSERT INTO t1 VALUES(randomblob(1000000),1);
    25     25     }
    26     26     set ::baseline sqlite3_memory_used
           27  +  # EVIDENCE-OF: R-58814-63508 The sqlite3_db_release_memory(D) interface
           28  +  # attempts to free as much heap memory as possible from database
           29  +  # connection D.
    27     30     sqlite3_db_release_memory db
    28     31     expr {$::baseline > [sqlite3_memory_used]+500000}
    29     32   } {1}
    30     33   do_test shrink-1.2 {
    31     34     set baseline [sqlite3_memory_used]
    32     35     db eval {
    33     36       UPDATE t1 SET y=y+1;

Changes to test/sort4.test.

    21     21   sqlite3_shutdown
    22     22   sqlite3_config_pmasz 10
    23     23   sqlite3_initialize
    24     24   sqlite3 db test.db
    25     25   
    26     26   
    27     27   # Configure the sorter to use 3 background threads.
    28         -db eval {PRAGMA threads=3}
           28  +#
           29  +# EVIDENCE-OF: R-19249-32353 SQLITE_LIMIT_WORKER_THREADS The maximum
           30  +# number of auxiliary worker threads that a single prepared statement
           31  +# may start.
           32  +#
           33  +do_test sort4-init001 {
           34  +  db eval {PRAGMA threads=5}
           35  +  sqlite3_limit db SQLITE_LIMIT_WORKER_THREADS -1
           36  +} {5}
           37  +do_test sort4-init002 {
           38  +  sqlite3_limit db SQLITE_LIMIT_WORKER_THREADS 3
           39  +  db eval {PRAGMA threads}
           40  +} {3}
           41  +
    29     42   
    30     43   # Minimum number of seconds to run for. If the value is 0, each test
    31     44   # is run exactly once. Otherwise, tests are repeated until the timeout
    32     45   # expires.
    33     46   set SORT4TIMEOUT 0
    34     47   if {[permutation] == "multithread"} { set SORT4TIMEOUT 300 }
    35     48   

Changes to test/sqllimits1.test.

   246    246     sqlite3_limit db SQLITE_LIMIT_VARIABLE_NUMBER -1
   247    247   } $SQLITE_MAX_VARIABLE_NUMBER
   248    248   
   249    249   #--------------------------------------------------------------------
   250    250   # Test cases sqllimits1-5.* test that the SQLITE_MAX_LENGTH limit
   251    251   # is enforced.
   252    252   #
          253  +# EVIDENCE-OF: R-61987-00541 SQLITE_LIMIT_LENGTH The maximum size of any
          254  +# string or BLOB or table row, in bytes.
          255  +#
   253    256   db close
   254    257   sqlite3 db test.db
   255    258   set LARGESIZE 99999
   256    259   set SQLITE_LIMIT_LENGTH 100000
   257    260   sqlite3_limit db SQLITE_LIMIT_LENGTH $SQLITE_LIMIT_LENGTH
   258    261   
   259    262   do_test sqllimits1-5.1.1 {
................................................................................
   401    404     } {1 {string or blob too big}}
   402    405   }
   403    406   unset strvalue
   404    407   
   405    408   #--------------------------------------------------------------------
   406    409   # Test cases sqllimits1-6.* test that the SQLITE_MAX_SQL_LENGTH limit
   407    410   # is enforced.
          411  +#
          412  +# EVIDENCE-OF: R-09808-17554 SQLITE_LIMIT_SQL_LENGTH The maximum length
          413  +# of an SQL statement, in bytes.
   408    414   #
   409    415   do_test sqllimits1-6.1 {
   410    416     sqlite3_limit db SQLITE_LIMIT_SQL_LENGTH 50000
   411    417     set sql "SELECT 1 WHERE 1==1"
   412    418     set tail " /* A comment to take up space in order to make the string\
   413    419                   longer without increasing the expression depth */\
   414    420                   AND   1  ==  1"
................................................................................
   562    568     execsql {
   563    569       DROP TABLE abc;
   564    570     }
   565    571   } {}
   566    572   
   567    573   #--------------------------------------------------------------------
   568    574   # Test cases sqllimits1-8.* test the SQLITE_MAX_COLUMN limit.
          575  +#
          576  +# EVIDENCE-OF: R-43996-29471 SQLITE_LIMIT_COLUMN The maximum number of
          577  +# columns in a table definition or in the result set of a SELECT or the
          578  +# maximum number of columns in an index or in an ORDER BY or GROUP BY
          579  +# clause.
   569    580   #
   570    581   set SQLITE_LIMIT_COLUMN 200
   571    582   sqlite3_limit db SQLITE_LIMIT_COLUMN $SQLITE_LIMIT_COLUMN
   572    583   do_test sqllimits1-8.1 {
   573    584     # Columns in a table.
   574    585     set cols [list]
   575    586     for {set i 0} {$i <= $SQLITE_LIMIT_COLUMN} {incr i} {
................................................................................
   666    677   
   667    678   
   668    679   #--------------------------------------------------------------------
   669    680   # These tests - sqllimits1-9.* - test that the SQLITE_LIMIT_EXPR_DEPTH
   670    681   # limit is enforced. The limit refers to the number of terms in 
   671    682   # the expression.
   672    683   #
          684  +# EVIDENCE-OF: R-12723-08526 SQLITE_LIMIT_EXPR_DEPTH The maximum depth
          685  +# of the parse tree on any expression.
          686  +#
   673    687   if {$SQLITE_MAX_EXPR_DEPTH==0} {
   674    688     puts -nonewline stderr "WARNING: Compile with -DSQLITE_MAX_EXPR_DEPTH to run "
   675    689     puts stderr "tests sqllimits1-9.X"
   676    690   } else {
   677    691     do_test sqllimits1-9.1 {
   678    692       set max $::SQLITE_MAX_EXPR_DEPTH
   679    693       set expr "(1 [string repeat {AND 1 } $max])"
................................................................................
   724    738   # in a single VDBE program.
   725    739   #
   726    740   # TODO
   727    741   
   728    742   #--------------------------------------------------------------------
   729    743   # Test the SQLITE_LIMIT_FUNCTION_ARG limit works. Test case names
   730    744   # match the pattern "sqllimits1-11.*".
          745  +#
          746  +# EVIDENCE-OF: R-59001-45278 SQLITE_LIMIT_FUNCTION_ARG The maximum
          747  +# number of arguments on a function.
   731    748   #
   732    749   for {set max 5} {$max<=$SQLITE_MAX_FUNCTION_ARG} {incr max} {
   733    750     do_test sqllimits1-11.$max.1 {
   734    751       set vals [list]
   735    752       sqlite3_limit db SQLITE_LIMIT_FUNCTION_ARG $::max
   736    753       for {set i 0} {$i < $::max} {incr i} {
   737    754         lappend vals $i
................................................................................
   758    775       catchsql "SELECT myfunc([join $vals ,])"
   759    776     } {1 {too many arguments on function myfunc}}
   760    777   }
   761    778   
   762    779   #--------------------------------------------------------------------
   763    780   # Test cases sqllimits1-12.*: Test the SQLITE_MAX_ATTACHED limit.
   764    781   #
          782  +# EVIDENCE-OF: R-41778-26203 SQLITE_LIMIT_ATTACHED The maximum number of
          783  +# attached databases.
          784  +#
   765    785   ifcapable attach {
   766    786     do_test sqllimits1-12.1 {
   767    787       set max $::SQLITE_MAX_ATTACHED
   768    788       for {set i 0} {$i < ($max)} {incr i} {
   769    789         forcedelete test${i}.db test${i}.db-journal
   770    790       }
   771    791       for {set i 0} {$i < ($max)} {incr i} {
................................................................................
   781    801     } {}
   782    802   }
   783    803   
   784    804   #--------------------------------------------------------------------
   785    805   # Test cases sqllimits1-13.*: Check that the SQLITE_MAX_VARIABLE_NUMBER 
   786    806   # limit works.
   787    807   #
          808  +# EVIDENCE-OF: R-42363-29104 SQLITE_LIMIT_VARIABLE_NUMBER The maximum
          809  +# index number of any parameter in an SQL statement.
          810  +#
   788    811   do_test sqllimits1-13.1 {
   789    812     set max $::SQLITE_MAX_VARIABLE_NUMBER
   790    813     catchsql "SELECT ?[expr {$max+1}] FROM t1"
   791    814   } "1 {variable number must be between ?1 and ?$::SQLITE_MAX_VARIABLE_NUMBER}"
   792    815   do_test sqllimits1-13.2 {
   793    816     set max $::SQLITE_MAX_VARIABLE_NUMBER
   794    817     set vals [list]
................................................................................
   802    825   #--------------------------------------------------------------------
   803    826   # Test cases sqllimits1-15.* verify that the 
   804    827   # SQLITE_MAX_LIKE_PATTERN_LENGTH limit is enforced. This limit only
   805    828   # applies to the built-in LIKE operator, supplying an external 
   806    829   # implementation by overriding the like() scalar function bypasses
   807    830   # this limitation.
   808    831   #
          832  +# EVIDENCE-OF: R-12940-37052 SQLITE_LIMIT_LIKE_PATTERN_LENGTH The
          833  +# maximum length of the pattern argument to the LIKE or GLOB operators.
          834  +#
   809    835   # These tests check that the limit is not incorrectly applied to
   810    836   # the left-hand-side of the LIKE operator (the string being tested
   811    837   # against the pattern).
   812    838   #
   813    839   set SQLITE_LIMIT_LIKE_PATTERN 1000
   814    840   sqlite3_limit db SQLITE_LIMIT_LIKE_PATTERN_LENGTH $SQLITE_LIMIT_LIKE_PATTERN
   815    841   do_test sqllimits1-15.1 {