System.Data.SQLite
Check-in [70455e449b]
Not logged in

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

Overview
Comment:Pickup the SQLite core library 3.14 doc changes from upstream.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 70455e449be2e7811ede5d1e54eff001616ab7b6
User & Date: mistachkin 2016-08-09 00:02:18
Context
2016-08-09
00:20
Pickup the 'vtab.html' doc fix from upstream. check-in: 006a35fb5e user: mistachkin tags: trunk
00:02
Pickup the SQLite core library 3.14 doc changes from upstream. check-in: 70455e449b user: mistachkin tags: trunk
2016-08-08
22:47
Update SQLite core library to the 3.14 release. check-in: e7806a71e7 user: mistachkin tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to Doc/Extra/Core/images/syntax/expr.gif.

cannot compute difference between binary files

Changes to Doc/Extra/Core/lang_expr.html.

   544    544   <h3>The IN and NOT IN operators</h3>
   545    545   <p>The IN and NOT IN operators take a single scalar operand on the
   546    546   left and a vector operand on the right
   547    547   formed by an explicit list of zero or more scalars or by a 
   548    548   single subquery.
   549    549   When the right operand of an IN or NOT IN operator is a subquery, the
   550    550   subquery must have a single result column.
          551  +The "subquery" on the right-hand side of an IN operator can be a
          552  +table name or <a href="vtab.html#tabfunc2">table-valued function</a> name in which case the
          553  +subquery is understood to be "(SELECT * FROM <i>name</i>)".
   551    554   When the right operand is an empty set, the result of IN is false and the
   552    555   result of NOT IN is true, regardless of the left operand and even if the
   553    556   left operand is NULL.
   554         -The result of an IN or NOT IN operator is determined by the following
          557  +<p>The result of an IN or NOT IN operator is determined by the following
   555    558   matrix:
   556    559   
   557    560   <center>
   558    561   <table border=1>
   559    562   <tr>
   560    563   <th>Left operand <br>is NULL
   561    564   <th>Right operand <br>contains NULL

Changes to Doc/Special/Core/vtab.html.

   133    133       </div>
   134    134     </table>
   135    135   
   136    136   <div class=startsearch></div>
   137    137     
   138    138   
   139    139   
   140         -<h1 align="center">The Virtual Table Mechanism Of SQLite</h1>
   141    140   
   142    141   
   143         -<h2>1.0 Introduction</h2>
          142  +
          143  +    <div class=fancy>
          144  +    <div style="font-size:2em;text-align:center;color:#044a64">
          145  +      The Virtual Table Mechanism Of SQLite
          146  +    </div>
          147  +    <div style="font-size:1.5em;margin:1em;color:#044a64">
          148  +      Table Of Contents</div>
          149  +    <div id=toc> <div style="margin-left:6ex"><a href="#section_1">1. Introduction</a></div><div style="margin-left:12ex"><a href="#section_1_1">1.1. Usage</a></div><div style="margin-left:18ex"><a href="#section_1_1_1">1.1.1. Temporary virtual tables</a></div><div style="margin-left:18ex"><a href="#section_1_1_2">1.1.2. Eponymous virtual tables</a></div><div style="margin-left:18ex"><a href="#section_1_1_3">1.1.3. Eponymous-only virtual tables</a></div><div style="margin-left:12ex"><a href="#section_1_2">1.2. Implementation</a></div><div style="margin-left:12ex"><a href="#section_1_3">1.3. Virtual Tables And Shared Cache</a></div><div style="margin-left:12ex"><a href="#section_1_4">1.4. Creating New Virtual Table Implementations</a></div><div style="margin-left:6ex"><a href="#section_2">2. Virtual Table Methods</a></div><div style="margin-left:12ex"><a href="#section_2_1">2.1. The xCreate Method</a></div><div style="margin-left:18ex"><a href="#section_2_1_1">2.1.1. Hidden columns in virtual tables</a></div><div style="margin-left:18ex"><a href="#section_2_1_2">2.1.2. Table-valued functions</a></div><div style="margin-left:18ex"><a href="#section_2_1_3">2.1.3.  WITHOUT ROWID Virtual Tables </a></div><div style="margin-left:12ex"><a href="#section_2_2">2.2. The xConnect Method</a></div><div style="margin-left:12ex"><a href="#section_2_3">2.3. The xBestIndex Method</a></div><div style="margin-left:18ex"><a href="#section_2_3_1">2.3.1. Inputs</a></div><div style="margin-left:18ex"><a href="#section_2_3_2">2.3.2. Outputs</a></div><div style="margin-left:12ex"><a href="#section_2_4">2.4. The xDisconnect Method</a></div><div style="margin-left:12ex"><a href="#section_2_5">2.5. The xDestroy Method</a></div><div style="margin-left:12ex"><a href="#section_2_6">2.6. The xOpen Method</a></div><div style="margin-left:12ex"><a href="#section_2_7">2.7. The xClose Method</a></div><div style="margin-left:12ex"><a href="#section_2_8">2.8. The xEof Method</a></div><div style="margin-left:12ex"><a href="#section_2_9">2.9. The xFilter Method</a></div><div style="margin-left:12ex"><a href="#section_2_10">2.10. The xNext Method</a></div><div style="margin-left:12ex"><a href="#section_2_11">2.11. The xColumn Method</a></div><div style="margin-left:12ex"><a href="#section_2_12">2.12. The xRowid Method</a></div><div style="margin-left:12ex"><a href="#section_2_13">2.13. The xUpdate Method</a></div><div style="margin-left:12ex"><a href="#section_2_14">2.14. The xFindFunction Method</a></div><div style="margin-left:12ex"><a href="#section_2_15">2.15. The xBegin Method</a></div><div style="margin-left:12ex"><a href="#section_2_16">2.16. The xSync Method</a></div><div style="margin-left:12ex"><a href="#section_2_17">2.17. The xCommit Method</a></div><div style="margin-left:12ex"><a href="#section_2_18">2.18. The xRollback Method</a></div><div style="margin-left:12ex"><a href="#section_2_19">2.19. The xRename Method</a></div><div style="margin-left:12ex"><a href="#section_2_20">2.20. The xSavepoint, xRelease, and xRollbackTo Methods</a></div> </div>
          150  +    <div class=startsearch></div>
          151  +  
          152  +
          153  +<h1 id="section_1">1. Introduction</h1>
   144    154   
   145    155   <p>A virtual table is an object that is registered with an open SQLite
   146    156   <a href="c3ref/sqlite3.html">database connection</a>. From the perspective of an SQL statement,
   147    157   the virtual table object looks like any other table or view. 
   148    158   But behind the scenes, queries and updates on a virtual table
   149    159   invoke callback methods of the virtual table object instead of
   150         -reading and writing to the database file.
          160  +reading and writing on the database file.
   151    161   
   152    162   <p>The virtual table mechanism allows an application to publish
   153    163   interfaces that are accessible from SQL statements as if they were
   154    164   tables. SQL statements can do almost anything to a
   155    165   virtual table that they can do to a real table, with the following
   156    166   exceptions:
   157    167   
................................................................................
   186    196        (the <a href="dbstat.html">dbstat virtual table</a>)
   187    197   <li> Read and/or write the content of a comma-separated value (CSV)
   188    198        file
   189    199   <li> Access the filesystem of the host computer as if it were a database table
   190    200   <li> Enabling SQL manipulation of data in statistics packages like R
   191    201   </ul>
   192    202   
   193         -<h3>1.1 Usage</h3>
          203  +
          204  +<h2 id="section_1_1">1.1. Usage</h2>
   194    205   
   195    206   <p>A virtual table is created using a <a href="lang_createvtab.html">CREATE VIRTUAL TABLE</a> statement.
   196    207   
   197    208   <p><b><a href="syntax/create-virtual-table-stmt.html">create-virtual-table-stmt:</a></b>
   198    209   <button id='x1475' onclick='hideorshow("x1475","x1476")'>hide</button></p>
   199    210    <blockquote id='x1476'>
   200    211    <img alt="syntax diagram create-virtual-table-stmt" src="images/syntax/create-virtual-table-stmt.gif" />
................................................................................
   233    244   arguments.
   234    245   
   235    246   <p>Once a virtual table has been created, it can be used like any other 
   236    247   table with the exceptions noted above and imposed by specific virtual
   237    248   table implementations. A virtual table is destroyed using the ordinary
   238    249   <a href="lang_droptable.html">DROP TABLE</a> syntax.
   239    250   
   240         -<h4>1.1.1 Temporary virtual tables</h4>
          251  +<h3 id="section_1_1_1">1.1.1. Temporary virtual tables</h3>
   241    252   
   242    253   <p>There is no "CREATE TEMP VIRTUAL TABLE" statement.  To create a
   243    254   temporary virtual table, add the "temp" schema
   244    255   before the virtual table name.
   245    256   
   246    257   <blockcuqote><pre>
   247    258      CREATE VIRTUAL TABLE <b>temp.</b>tablename USING module(arg1, ...);
   248    259   </pre></blockquote>
   249    260   
   250    261   <a name="epovtab"></a>
   251    262   
   252         -<h4>1.1.2 Eponymous virtual tables</h4>
          263  +<h3 id="section_1_1_2">1.1.2. Eponymous virtual tables</h3>
   253    264   
   254    265   <p>Some virtual tables exist automatically in the "main" schema of
   255    266   every database connection in which their
   256    267   module is registered, even without a <a href="lang_createvtab.html">CREATE VIRTUAL TABLE</a> statement.
   257    268   Such virtual tables are called "eponymous virtual tables".
   258    269   To use an eponymous virtual table, simply use the 
   259    270   module name as if it were a table.
................................................................................
   277    288   using the <a href="lang_createvtab.html">CREATE VIRTUAL TABLE</a> statement.  The <a href="vtab.html#xconnect">xConnect</a> method whenever
   278    289   a database connection attaches to or reparses a schema. When these two methods
   279    290   are the same, that indicates that the virtual table has no persistent
   280    291   state that needs to be created and destroyed.
   281    292   
   282    293   <a name="epoonlyvtab"></a>
   283    294   
   284         -<h5>1.1.2.1 Eponymous-only virtual tables</h5>
          295  +<h3 id="section_1_1_3">1.1.3. Eponymous-only virtual tables</h3>
   285    296   <p>If the <a href="vtab.html#xcreate">xCreate</a> method is NULL, then
   286    297   <a href="lang_createvtab.html">CREATE VIRTUAL TABLE</a> statements are prohibited for that virtual table,
   287    298   and the virtual table is an "eponymous-only virtual table".
   288    299   Eponymous-only virtual tables are useful as 
   289    300   <a href="vtab.html#tabfunc2">table-valued functions</a>.
   290    301   
   291    302   <p>
   292    303   Note that SQLite versions prior to 3.9.0 did not check the xCreate method
   293    304   for NULL before invoking it.  So if an eponymous-only virtual table is
   294    305   registered with SQLite version 3.8.11.1 or earlier and a <a href="lang_createvtab.html">CREATE VIRTUAL TABLE</a>
   295    306   command is attempted against that virtual table module, a jump to a NULL
   296    307   pointer will occur, resulting in a crash.
   297    308   
   298         -<h3>1.2 Implementation</h3>
          309  +<h2 id="section_1_2">1.2. Implementation</h2>
   299    310   
   300    311   <p>Several new C-level objects are used by the virtual table implementation:
   301    312   
   302    313   <blockquote><pre>
   303    314     typedef struct sqlite3_vtab sqlite3_vtab;
   304    315     typedef struct sqlite3_index_info sqlite3_index_info;
   305    316     typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor;
................................................................................
   440    451   definition might be extended with additional methods and in that case 
   441    452   the iVersion value will be increased.
   442    453   
   443    454   <p>The rest of the module structure consists of methods used to implement
   444    455   various features of the virtual table. Details on what each of these 
   445    456   methods do are provided in the sequel.
   446    457   
   447         -<h3>1.3 Virtual Tables And Shared Cache</h3>
          458  +<h2 id="section_1_3">1.3. Virtual Tables And Shared Cache</h2>
   448    459   
   449    460   <p>Prior to SQLite <a href="releaselog/3_6_17.html">version 3.6.17</a>, the virtual table mechanism assumes 
   450    461   that each <a href="c3ref/sqlite3.html">database connection</a> kept
   451    462   its own copy of the database schema. Hence, the virtual table mechanism
   452    463   could not be used in a database that has <a href="sharedcache.html">shared cache mode</a> enabled. 
   453    464   The <a href="c3ref/create_module.html">sqlite3_create_module()</a> interface would return an error if 
   454    465   <a href="sharedcache.html">shared cache mode</a> is enabled.  That restriction was relaxed
   455    466   beginning with SQLite <a href="releaselog/3_6_17.html">version 3.6.17</a>.
   456    467   
   457         -<h3>1.4 Creating New Virtual Table Implementations</h3>
          468  +<h2 id="section_1_4">1.4. Creating New Virtual Table Implementations</h2>
   458    469   
   459    470   <p>Follow these steps to create your own virtual table:
   460    471   
   461    472   <p>
   462    473   <ol>
   463    474   <li> Write all necessary methods.
   464    475   <li> Create an instance of the <a href="c3ref/module.html">sqlite3_module</a> structure containing pointers
................................................................................
   475    486   (for testing purposes). You might use one of those as a guide. Locate 
   476    487   these test virtual table implementations by searching 
   477    488   for "sqlite3_create_module".
   478    489   
   479    490   <p>You might also want to implement your new virtual table as a 
   480    491   <a href="c3ref/load_extension.html">loadable extension</a>.
   481    492   
   482         -<h2>2.0 Virtual Table Methods</h2>
          493  +<h1 id="section_2">2. Virtual Table Methods</h1>
   483    494   
   484    495   <a name="xcreate"></a>
   485    496   
   486         -<h3>2.1 The xCreate Method</h3>
          497  +<h2 id="section_2_1">2.1. The xCreate Method</h2>
   487    498   
   488    499   <blockquote><pre>
   489    500     int (*xCreate)(sqlite3 *db, void *pAux,
   490    501                  int argc, char **argv,
   491    502                  sqlite3_vtab **ppVTab,
   492    503                  char **pzErr);
   493    504   </pre></blockquote>
   494    505   
   495         -<p>This method is called to create a new instance of a virtual table 
   496         -in response to a <a href="lang_createvtab.html">CREATE VIRTUAL TABLE</a> statement. 
   497         -The db parameter is a pointer to the SQLite <a href="c3ref/sqlite3.html">database connection</a> that 
          506  +<p>The xCreate method is called to create a new instance of a virtual table 
          507  +in response to a <a href="lang_createvtab.html">CREATE VIRTUAL TABLE</a> statement.
          508  +If the xCreate method is the same pointer as the <a href="vtab.html#xconnect">xConnect</a> method, then the
          509  +virtual table is an <a href="vtab.html#epovtab">eponymous virtual table</a>.
          510  +If the xCreate method is omitted (if it is a NULL pointer) then the virtual 
          511  +table is an <a href="vtab.html#epoonlyvtab">eponymous-only virtual table</a>.
          512  +
          513  +
          514  +<p>The db parameter is a pointer to the SQLite <a href="c3ref/sqlite3.html">database connection</a> that 
   498    515   is executing the <a href="lang_createvtab.html">CREATE VIRTUAL TABLE</a> statement. 
   499    516   The pAux argument is the copy of the client data pointer that was the 
   500    517   fourth argument to the <a href="c3ref/create_module.html">sqlite3_create_module()</a> or
   501    518   <a href="c3ref/create_module.html">sqlite3_create_module_v2()</a> call that registered the 
   502    519   <a href="c3ref/module.html">virtual table module</a>. 
   503    520   The argv parameter is an array of argc pointers to null terminated strings. 
   504    521   The first string, argv[0], is the name of the module being invoked.   The
................................................................................
   565    582   If the xCreate method is the exact same pointer as the <a href="vtab.html#xconnect">xConnect</a> method,
   566    583   that indicates that the virtual table does not need to initialize backing
   567    584   store.  Such a virtual table can be used as an <a href="vtab.html#epovtab">eponymous virtual table</a>
   568    585   or as a named virtual table using <a href="lang_createvtab.html">CREATE VIRTUAL TABLE</a> or both.
   569    586   
   570    587   <a name="hiddencol"></a>
   571    588   
   572         -<h4>2.1.1 Hidden columns in virtual tables</h4>
          589  +<h3 id="section_2_1_1">2.1.1. Hidden columns in virtual tables</h3>
   573    590   <p>If a column datatype contains the special keyword "HIDDEN"
   574    591   (in any combination of upper and lower case letters) then that keyword
   575    592   it is omitted from the column datatype name and the column is marked 
   576    593   as a hidden column internally. 
   577    594   A hidden column differs from a normal column in three respects:
   578    595   
   579    596   <p>
................................................................................
   598    615   <p>An example use of hidden columns can be seen in the <a href="fts3.html">FTS3</a> virtual 
   599    616   table implementation, where every FTS virtual table
   600    617   contains an <a href="fts3.html#hiddencol">FTS hidden column</a> that is used to pass information from the
   601    618   virtual table into <a href="fts3.html#snippet">FTS auxiliary functions</a> and to the <a href="fts3.html#section_3">FTS MATCH</a> operator.
   602    619   
   603    620   <a name="tabfunc2"></a>
   604    621   
   605         -<h4>2.1.2 Table-valued functions</h4>
          622  +<h3 id="section_2_1_2">2.1.2. Table-valued functions</h3>
   606    623   
   607    624   <p>A <a href="vtab.html">virtual table</a> that contains <a href="vtab.html#hiddencol">hidden columns</a> can be used like
   608    625   a table-valued function in the FROM clause of a <a href="lang_select.html">SELECT</a> statement.
   609    626   The arguments to the table-valued function become constraints on 
   610    627   the HIDDEN columns of the virtual table.
   611    628   
   612    629   <p>For example, the "generate_series" extension (located in the
................................................................................
   641    658   
   642    659   <p>Arguments on the virtual table name are matched to <a href="vtab.html#hiddencol">hidden columns</a>
   643    660   in order.  The number of arguments can be less than the
   644    661   number of hidden columns, in which case the latter hidden columns are
   645    662   unconstrained.  However, an error results if there are more arguments
   646    663   than there are hidden columns in the virtual table.
   647    664   
          665  +<a name="worid"></a>
          666  +
          667  +<h3 id="section_2_1_3">2.1.3.  WITHOUT ROWID Virtual Tables </h3>
          668  +
          669  +<p>Beginning with SQLite <a href="releaselog/3_14.html">version 3.14.0</a>, the CREATE TABLE statement that
          670  +is passed into <a href="c3ref/declare_vtab.html">sqlite3_declare_vtab()</a> may contain a <a href="withoutrowid.html">WITHOUT ROWID</a> clause.
          671  +This is useful for cases where the virtual table rows 
          672  +cannot easily be mapped into unique integers.  A CREATE TABLE
          673  +statement that includes WITHOUT ROWID must define one or more columns as
          674  +the PRIMARY KEY.  Every column of the PRIMARY KEY must individually be
          675  +NOT NULL and all columns for each row must be collectively unique.
          676  +
          677  +<p>Note that SQLite does not enforce the PRIMARY KEY for a WITHOUT ROWID
          678  +virtual table.  Enforcement is the responsibility of the underlying
          679  +virtual table implementation.  But SQLite does assume that the PRIMARY KEY
          680  +constraint is valid - that the identified columns really are UNIQUE and
          681  +NOT NULL - and it uses that assumption to optimize queries against the
          682  +virtual table.
          683  +
          684  +<p>The rowid column is not accessible on a
          685  +WITHOUT ROWID virtual table (of course).  Furthermore, since the
          686  +<a href="vtab.html#xupdate">xUpdate</a> method depends on having a valid rowid, the <a href="vtab.html#xupdate">xUpdate</a> method 
          687  +must be NULL for a WITHOUT ROWID virtual table.  That in turn means that
          688  +WITHOUT ROWID virtual tables must be read-only.
          689  +
   648    690   
   649    691   <a name="xconnect"></a>
   650    692   
   651         -<h3>2.2 The xConnect Method</h3>
          693  +<h2 id="section_2_2">2.2. The xConnect Method</h2>
   652    694   
   653    695   <blockquote><pre>
   654    696     int (*xConnect)(sqlite3*, void *pAux,
   655    697                  int argc, char **argv,
   656    698                  sqlite3_vtab **ppVTab,
   657    699                  char **pzErr);
   658    700   </pre></blockquote>
................................................................................
   700    742   <p>The xConnect method is required for every virtual table implementation, 
   701    743   though the <a href="vtab.html#xcreate">xCreate</a> and xConnect pointers of the <a href="c3ref/module.html">sqlite3_module</a> object
   702    744   may point to the same function if the virtual table does not need to
   703    745   initialize backing store.
   704    746   
   705    747   <a name="xbestindex"></a>
   706    748   
   707         -<h3>2.3 The xBestIndex Method</h3>
          749  +<h2 id="section_2_3">2.3. The xBestIndex Method</h2>
   708    750   
   709    751   <p>SQLite uses the xBestIndex method of a virtual table module to determine
   710    752   the best way to access the virtual table. 
   711    753   The xBestIndex method has a prototype like this:
   712    754   
   713    755   <blockquote><pre>
   714    756     int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);
................................................................................
   813    855   <p>Note that xBestIndex will always be called before <a href="vtab.html#xfilter">xFilter</a>, since
   814    856   the idxNum and idxStr outputs from xBestIndex are required inputs to
   815    857   xFilter.  However, there is no guarantee that xFilter will be called
   816    858   following a successful xBestIndex.  
   817    859   
   818    860   <p>The xBestIndex method is required for every virtual table implementation.
   819    861   
   820         -<h4>2.3.1 Inputs</h4>
          862  +<h3 id="section_2_3_1">2.3.1. Inputs</h3>
   821    863   
   822    864   <p>The main thing that the SQLite core is trying to communicate to 
   823    865   the virtual table is the constraints that are available to limit 
   824    866   the number of rows that need to be searched. The aConstraint[] array 
   825    867   contains one entry for each constraint. There will be exactly 
   826    868   nConstraint entries in that array.
   827    869   
................................................................................
   895    937   means that the first column is used.  The second lowest bit corresponds
   896    938   to the second column.  And so forth.  If the most significant bit of
   897    939   colUsed is set, that means that one or more columns other than the 
   898    940   first 63 columns are used.  If column usage information is needed by the
   899    941   <a href="vtab.html#xfilter">xFilter</a> method, then the required bits must be encoded into either
   900    942   the idxNum or idxStr output fields.
   901    943   
   902         -<h4>2.3.2 Outputs</h4>
          944  +<h3 id="section_2_3_2">2.3.2. Outputs</h3>
   903    945   
   904    946   <p>Given all of the information above, the job of the xBestIndex 
   905    947   method it to figure out the best way to search the virtual table.
   906    948   
   907    949   <p>The xBestIndex method fills the idxNum and idxStr fields with 
   908    950   information that communicates an indexing strategy to the <a href="vtab.html#xfilter">xFilter</a> 
   909    951   method. The information in idxNum and idxStr is arbitrary as far 
................................................................................
   961   1003   <p>By default, the SQLite core double checks all constraints on 
   962   1004   each row of the virtual table that it receives. If such a check 
   963   1005   is redundant, the xBestFilter method can suppress that double-check by 
   964   1006   setting aConstraintUsage[].omit.
   965   1007   
   966   1008   <a name="xdisconnect"></a>
   967   1009   
   968         -<h3>2.4 The xDisconnect Method</h3>
         1010  +<h2 id="section_2_4">2.4. The xDisconnect Method</h2>
   969   1011   
   970   1012   <blockquote><pre>
   971   1013     int (*xDisconnect)(sqlite3_vtab *pVTab);
   972   1014   </pre></blockquote>
   973   1015   
   974   1016   <p>This method releases a connection to a virtual table. 
   975   1017   Only the <a href="c3ref/vtab.html">sqlite3_vtab</a> object is destroyed.
................................................................................
   984   1026   
   985   1027   <p>The xDisconnect method is required for every virtual table implementation,
   986   1028   though it is acceptable for the xDisconnect and <a href="vtab.html#sqlite3_module.xDestroy">xDestroy</a> methods to be
   987   1029   the same function if that makes sense for the particular virtual table.
   988   1030   
   989   1031   <a name="sqlite3_module.xDestroy"></a>
   990   1032   
   991         -<h3>2.5 The xDestroy Method</h3>
         1033  +<h2 id="section_2_5">2.5. The xDestroy Method</h2>
   992   1034   
   993   1035   <blockquote><pre>
   994   1036     int (*xDestroy)(sqlite3_vtab *pVTab);
   995   1037   </pre></blockquote>
   996   1038   
   997   1039   <p>This method releases a connection to a virtual table, just like 
   998   1040   the <a href="vtab.html#xdisconnect">xDisconnect</a> method, and it also destroys the underlying 
................................................................................
  1004   1046   
  1005   1047   <p>The xDestroy method is required for every virtual table implementation,
  1006   1048   though it is acceptable for the <a href="vtab.html#xdisconnect">xDisconnect</a> and xDestroy methods to be
  1007   1049   the same function if that makes sense for the particular virtual table.
  1008   1050   
  1009   1051   <a name="xopen"></a>
  1010   1052   
  1011         -<h3>2.6 The xOpen Method</h3>
         1053  +<h2 id="section_2_6">2.6. The xOpen Method</h2>
  1012   1054   
  1013   1055   <blockquote><pre>
  1014   1056     int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);
  1015   1057   </pre></blockquote>
  1016   1058   
  1017   1059   <p>The xOpen method creates a new cursor used for accessing (read and/or
  1018   1060   writing) a virtual table.  A successful invocation of this method 
................................................................................
  1035   1077   The SQLite core will invoke the <a href="vtab.html#xfilter">xFilter</a> method
  1036   1078   on the cursor prior to any attempt to position or read from the cursor.
  1037   1079   
  1038   1080   <p>The xOpen method is required for every virtual table implementation.
  1039   1081   
  1040   1082   <a name="xclose"></a>
  1041   1083   
  1042         -<h3>2.7 The xClose Method</h3>
         1084  +<h2 id="section_2_7">2.7. The xClose Method</h2>
  1043   1085   
  1044   1086   <blockquote><pre>
  1045   1087     int (*xClose)(sqlite3_vtab_cursor*);
  1046   1088   </pre></blockquote>
  1047   1089   
  1048   1090   <p>The xClose method closes a cursor previously opened by 
  1049   1091   <a href="vtab.html#xopen">xOpen</a>. 
................................................................................
  1055   1097   returns an error.  The SQLite core will not use the
  1056   1098   <a href="c3ref/vtab_cursor.html">sqlite3_vtab_cursor</a> again after it has been closed.
  1057   1099   
  1058   1100   <p>The xClose method is required for every virtual table implementation.
  1059   1101   
  1060   1102   <a name="xeof"></a>
  1061   1103   
  1062         -<h3>2.8 The xEof Method</h3>
         1104  +<h2 id="section_2_8">2.8. The xEof Method</h2>
  1063   1105   
  1064   1106   <blockquote><pre>
  1065   1107     int (*xEof)(sqlite3_vtab_cursor*);
  1066   1108   </pre></blockquote>
  1067   1109   
  1068   1110   <p>The xEof method must return false (zero) if the specified cursor 
  1069   1111   currently points to a valid row of data, or true (non-zero) otherwise. 
................................................................................
  1070   1112   This method is called by the SQL engine immediately after each 
  1071   1113   <a href="vtab.html#xfilter">xFilter</a> and <a href="vtab.html#xnext">xNext</a> invocation.
  1072   1114   
  1073   1115   <p>The xEof method is required for every virtual table implementation.
  1074   1116   
  1075   1117   <a name="xfilter"></a>
  1076   1118   
  1077         -<h3>2.9 The xFilter Method</h3>
         1119  +<h2 id="section_2_9">2.9. The xFilter Method</h2>
  1078   1120   
  1079   1121   <blockquote><pre>
  1080   1122     int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr,
  1081   1123                   int argc, sqlite3_value **argv);
  1082   1124   </pre></blockquote>
  1083   1125   
  1084   1126   <p>This method begins a search of a virtual table. 
................................................................................
  1105   1147   <p>This method must return <a href="rescode.html#ok">SQLITE_OK</a> if successful, or an sqlite 
  1106   1148   <a href="rescode.html">error code</a> if an error occurs.
  1107   1149   
  1108   1150   <p>The xFilter method is required for every virtual table implementation.
  1109   1151   
  1110   1152   <a name="xnext"></a>
  1111   1153   
  1112         -<h3>2.10 The xNext Method</h3>
         1154  +<h2 id="section_2_10">2.10. The xNext Method</h2>
  1113   1155   
  1114   1156   <blockquote><pre>
  1115   1157     int (*xNext)(sqlite3_vtab_cursor*);
  1116   1158   </pre></blockquote>
  1117   1159   
  1118   1160   <p>The xNext method advances a <a href="c3ref/vtab_cursor.html">virtual table cursor</a>
  1119   1161   to the next row of a result set initiated by <a href="vtab.html#xfilter">xFilter</a>. 
................................................................................
  1126   1168   <p>This method must return <a href="rescode.html#ok">SQLITE_OK</a> if successful, or an sqlite 
  1127   1169   <a href="rescode.html">error code</a> if an error occurs.
  1128   1170   
  1129   1171   <p>The xNext method is required for every virtual table implementation.
  1130   1172   
  1131   1173   <a name="xcolumn"></a>
  1132   1174   
  1133         -<h3>2.11 The xColumn Method</h3>
         1175  +<h2 id="section_2_11">2.11. The xColumn Method</h2>
  1134   1176   
  1135   1177   <blockquote><pre>
  1136   1178     int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int N);
  1137   1179   </pre></blockquote>
  1138   1180   
  1139   1181   <p>The SQLite core invokes this method in order to find the value for 
  1140   1182   the N-th column of the current row. N is zero-based so the first column 
................................................................................
  1164   1206   methods to set the error message text, then return an appropriate
  1165   1207   <a href="rescode.html">error code</a>.  The xColumn method must return <a href="rescode.html#ok">SQLITE_OK</a> on success.
  1166   1208   
  1167   1209   <p>The xColumn method is required for every virtual table implementation.
  1168   1210   
  1169   1211   <a name="xrowid"></a>
  1170   1212   
  1171         -<h3>2.12 The xRowid Method</h3>
         1213  +<h2 id="section_2_12">2.12. The xRowid Method</h2>
  1172   1214   
  1173   1215   <blockquote><pre>
  1174   1216     int (*xRowid)(sqlite3_vtab_cursor *pCur, sqlite_int64 *pRowid);
  1175   1217   </pre></blockquote>
  1176   1218   
  1177   1219   <p>A successful invocation of this method will cause *pRowid to be
  1178   1220   filled with the <a href="lang_createtable.html#rowid">rowid</a> of row that the
................................................................................
  1180   1222   This method returns <a href="rescode.html#ok">SQLITE_OK</a> on success.
  1181   1223   It returns an appropriate <a href="rescode.html">error code</a> on failure.</p>
  1182   1224   
  1183   1225   <p>The xRowid method is required for every virtual table implementation.
  1184   1226   
  1185   1227   <a name="xupdate"></a>
  1186   1228   
  1187         -<h3>2.13 The xUpdate Method</h3>
         1229  +<h2 id="section_2_13">2.13. The xUpdate Method</h2>
  1188   1230   
  1189   1231   <blockquote><pre>
  1190   1232     int (*xUpdate)(
  1191   1233       sqlite3_vtab *pVTab,
  1192   1234       int argc,
  1193   1235       sqlite3_value **argv,
  1194   1236       sqlite_int64 *pRowid
................................................................................
  1278   1320   <p>The xUpdate method is optional.
  1279   1321   If the xUpdate pointer in the <a href="c3ref/module.html">sqlite3_module</a> for a virtual table
  1280   1322   is a NULL pointer, then the virtual table is read-only.
  1281   1323   
  1282   1324   
  1283   1325   <a name="xfindfunction"></a>
  1284   1326   
  1285         -<h3>2.14 The xFindFunction Method</h3>
         1327  +<h2 id="section_2_14">2.14. The xFindFunction Method</h2>
  1286   1328   
  1287   1329   <blockquote><pre>
  1288   1330     int (*xFindFunction)(
  1289   1331       sqlite3_vtab *pVtab,
  1290   1332       int nArg,
  1291   1333       const char *zName,
  1292   1334       void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),
................................................................................
  1314   1356   first argument.
  1315   1357   
  1316   1358   <p>The function pointer returned by this routine must be valid for
  1317   1359   the lifetime of the <a href="c3ref/vtab.html">sqlite3_vtab</a> object given in the first parameter.
  1318   1360   
  1319   1361   <a name="xBegin"></a>
  1320   1362   
  1321         -<h3>2.15 The xBegin Method</h3>
         1363  +<h2 id="section_2_15">2.15. The xBegin Method</h2>
  1322   1364   
  1323   1365   <blockquote><pre>
  1324   1366     int (*xBegin)(sqlite3_vtab *pVTab);
  1325   1367   </pre></blockquote>
  1326   1368   
  1327   1369   <p>This method begins a transaction on a virtual table.
  1328   1370   This is method is optional.  The xBegin pointer of <a href="c3ref/module.html">sqlite3_module</a>
................................................................................
  1334   1376   on a single virtual table
  1335   1377   without an intervening call to either <a href="vtab.html#xcommit">xCommit</a> or <a href="vtab.html#xrollback">xRollback</a>.
  1336   1378   Multiple calls to other methods can and likely will occur in between
  1337   1379   the xBegin and the corresponding <a href="vtab.html#xcommit">xCommit</a> or <a href="vtab.html#xrollback">xRollback</a>.
  1338   1380   
  1339   1381   <a name="xsync"></a>
  1340   1382   
  1341         -<h3>2.16 The xSync Method</h3>
         1383  +<h2 id="section_2_16">2.16. The xSync Method</h2>
  1342   1384   
  1343   1385   <blockquote><pre>
  1344   1386     int (*xSync)(sqlite3_vtab *pVTab);
  1345   1387   </pre></blockquote>
  1346   1388   
  1347   1389   
  1348   1390   <p>This method signals the start of a two-phase commit on a virtual
................................................................................
  1354   1396   prior to an <a href="vtab.html#xcommit">xCommit</a> or <a href="vtab.html#xrollback">xRollback</a>.  In order to implement two-phase
  1355   1397   commit, the xSync method on all virtual tables is invoked prior to
  1356   1398   invoking the <a href="vtab.html#xcommit">xCommit</a> method on any virtual table.  If any of the 
  1357   1399   xSync methods fail, the entire transaction is rolled back.
  1358   1400   
  1359   1401   <a name="xcommit"></a>
  1360   1402   
  1361         -<h3>2.17 The xCommit Method</h3>
         1403  +<h2 id="section_2_17">2.17. The xCommit Method</h2>
  1362   1404   
  1363   1405   <blockquote><pre>
  1364   1406     int (*xCommit)(sqlite3_vtab *pVTab);
  1365   1407   </pre></blockquote>
  1366   1408   
  1367   1409   <p>This method causes a virtual table transaction to commit.
  1368   1410   This is method is optional.  The xCommit pointer of <a href="c3ref/module.html">sqlite3_module</a>
................................................................................
  1370   1412   
  1371   1413   <p>A call to this method always follows a prior call to <a href="vtab.html#xBegin">xBegin</a> and
  1372   1414   <a href="vtab.html#xsync">xSync</a>.
  1373   1415   
  1374   1416   
  1375   1417   <a name="xrollback"></a>
  1376   1418   
  1377         -<h3>2.18 The xRollback Method</h3>
         1419  +<h2 id="section_2_18">2.18. The xRollback Method</h2>
  1378   1420   
  1379   1421   <blockquote><pre>
  1380   1422     int (*xRollback)(sqlite3_vtab *pVTab);
  1381   1423   </pre></blockquote>
  1382   1424   
  1383   1425   <p>This method causes a virtual table transaction to rollback.
  1384   1426   This is method is optional.  The xRollback pointer of <a href="c3ref/module.html">sqlite3_module</a>
................................................................................
  1385   1427   may be NULL.
  1386   1428   
  1387   1429   <p>A call to this method always follows a prior call to <a href="vtab.html#xBegin">xBegin</a>.
  1388   1430   
  1389   1431   
  1390   1432   <a name="xrename"></a>
  1391   1433   
  1392         -<h3>2.19 The xRename Method</h3>
         1434  +<h2 id="section_2_19">2.19. The xRename Method</h2>
  1393   1435   
  1394   1436   <blockquote><pre>
  1395   1437     int (*xRename)(sqlite3_vtab *pVtab, const char *zNew);
  1396   1438   </pre></blockquote>
  1397   1439   
  1398   1440   <p>This method provides notification that the virtual table implementation
  1399   1441   that the virtual table will be given a new name. 
................................................................................
  1400   1442   If this method returns <a href="rescode.html#ok">SQLITE_OK</a> then SQLite renames the table.
  1401   1443   If this method returns an <a href="rescode.html">error code</a> then the renaming is prevented.
  1402   1444   
  1403   1445   <p>The xRename method is required for every virtual table implementation.
  1404   1446   
  1405   1447   <a name="xsavepoint"></a>
  1406   1448   
  1407         -<h3>2.20 The xSavepoint, xRelease, and xRollbackTo Methods</h3>
         1449  +<h2 id="section_2_20">2.20. The xSavepoint, xRelease, and xRollbackTo Methods</h2>
  1408   1450   
  1409   1451   <blockquote><pre>
  1410   1452     int (*xSavepoint)(sqlite3_vtab *pVtab, int);
  1411   1453     int (*xRelease)(sqlite3_vtab *pVtab, int);
  1412   1454     int (*xRollbackTo)(sqlite3_vtab *pVtab, int);
  1413   1455   </pre></blockquote>
  1414   1456   

Changes to Doc/vtab.tcl.

    24     24   }
    25     25   
    26     26   proc escapeSubSpec { data } {
    27     27     regsub -all -- {&} $data {\\\&} data
    28     28     regsub -all -- {\\(\d+)} $data {\\\\\1} data
    29     29     return $data
    30     30   }
           31  +
           32  +proc removeSectionId { value } {
           33  +  regsub -- { id="section(?:_\d+)+"} $value "" value
           34  +  return $value
           35  +}
    31     36   
    32     37   proc englishToList { value } {
    33     38     set result [list]
    34     39   
    35     40     foreach element [split $value "\t\n ,"] {
    36     41       if {[string tolower $element] ni [list "" and or]} then {
    37     42         lappend result $element
................................................................................
    82     87     upvar 1 $indexVarName index
    83     88     upvar 1 $methodsVarName methods
    84     89   
    85     90     array set levels {p 0}
    86     91     set length [llength $lines]
    87     92   
    88     93     while {$index < $length} {
    89         -    set line [lindex $lines $index]
           94  +    set line [removeSectionId [lindex $lines $index]]
    90     95   
    91     96       if {[regexp -- $pattern $line]} then {
    92     97         break; # stop on this line for outer loop.
    93     98       } else {
    94     99         set trimLine [string trim $line]; set data ""
    95    100   
    96    101         if {$levels(p) > 0 && [string length $trimLine] == 0} then {
................................................................................
   187    192   
   188    193   set inputData [string map [list \
   189    194       {<font size="6" color="red">*** DRAFT ***</font>} ""] $inputData]
   190    195   
   191    196   set inputData [string map [list {<p align="center"></p>} ""] $inputData]
   192    197   
   193    198   set lines [split [string map [list \r\n \n] $inputData] \n]
   194         -set patterns(method) {^<h3>2\.\d+ The (.*) Method(?:s)?</h3>$}
          199  +
          200  +set patterns(method) {^<h2>2\.\d+\. The (.*) Method(?:s)?</h2>$}
   195    201   set prefix "        /// "
   196    202   unset -nocomplain methods; set start false
   197    203   
   198    204   for {set index 0} {$index < [llength $lines]} {} {
   199         -  set line [lindex $lines $index]
          205  +  set line [removeSectionId [lindex $lines $index]]
   200    206   
   201    207     if {$start} then {
   202    208       if {[regexp -- $patterns(method) $line dummy capture]} then {
   203    209         foreach method [englishToList $capture] {
   204    210           set methodIndex [expr {$index + 1}]
   205    211   
   206    212           extractMethod \
................................................................................
   207    213               $method $lines $patterns(method) $prefix methodIndex methods
   208    214         }
   209    215   
   210    216         set index $methodIndex
   211    217       } else {
   212    218         incr index
   213    219       }
   214         -  } elseif {[regexp -- {^<h2>2\.0 Virtual Table Methods</h2>$} $line]} then {
          220  +  } elseif {[regexp -- {^<h1>2\. Virtual Table Methods</h1>$} $line]} then {
   215    221       set start true; incr index
   216    222     } else {
   217    223       incr index
   218    224     }
   219    225   }
   220    226   
   221    227   set outputData [string map [list \r\n \n] [readFile $outputFileName]]

Changes to System.Data.SQLite/ISQLiteNativeModule.cs.

    18     18           /// <para><code>
    19     19           ///   int (*xCreate)(sqlite3 *db, void *pAux,
    20     20           ///                int argc, char **argv,
    21     21           ///                sqlite3_vtab **ppVTab,
    22     22           ///                char **pzErr);
    23     23           /// </code></para>
    24     24           /// <para>
    25         -        /// This method is called to create a new instance of a virtual table 
    26         -        /// in response to a CREATE VIRTUAL TABLE statement. 
           25  +        /// The xCreate method is called to create a new instance of a virtual table 
           26  +        /// in response to a CREATE VIRTUAL TABLE statement.
           27  +        /// If the xCreate method is the same pointer as the xConnect method, then the
           28  +        /// virtual table is an eponymous virtual table.
           29  +        /// If the xCreate method is omitted (if it is a NULL pointer) then the virtual 
           30  +        /// table is an eponymous-only virtual table.
           31  +        /// </para>
           32  +        /// <para>
    27     33           /// The db parameter is a pointer to the SQLite database connection that 
    28     34           /// is executing the CREATE VIRTUAL TABLE statement. 
    29     35           /// The pAux argument is the copy of the client data pointer that was the 
    30     36           /// fourth argument to the sqlite3_create_module() or
    31     37           /// sqlite3_create_module_v2() call that registered the 
    32     38           /// virtual table module. 
    33     39           /// The argv parameter is an array of argc pointers to null terminated strings. 
................................................................................
   173    179           /// <para>
   174    180           /// Arguments on the virtual table name are matched to hidden columns
   175    181           /// in order.  The number of arguments can be less than the
   176    182           /// number of hidden columns, in which case the latter hidden columns are
   177    183           /// unconstrained.  However, an error results if there are more arguments
   178    184           /// than there are hidden columns in the virtual table.
   179    185           /// </para>
          186  +        /// <para>
          187  +        /// Beginning with SQLite version 3.14.0, the CREATE TABLE statement that
          188  +        /// is passed into sqlite3_declare_vtab() may contain a WITHOUT ROWID clause.
          189  +        /// This is useful for cases where the virtual table rows 
          190  +        /// cannot easily be mapped into unique integers.  A CREATE TABLE
          191  +        /// statement that includes WITHOUT ROWID must define one or more columns as
          192  +        /// the PRIMARY KEY.  Every column of the PRIMARY KEY must individually be
          193  +        /// NOT NULL and all columns for each row must be collectively unique.
          194  +        /// </para>
          195  +        /// <para>
          196  +        /// Note that SQLite does not enforce the PRIMARY KEY for a WITHOUT ROWID
          197  +        /// virtual table.  Enforcement is the responsibility of the underlying
          198  +        /// virtual table implementation.  But SQLite does assume that the PRIMARY KEY
          199  +        /// constraint is valid - that the identified columns really are UNIQUE and
          200  +        /// NOT NULL - and it uses that assumption to optimize queries against the
          201  +        /// virtual table.
          202  +        /// </para>
          203  +        /// <para>
          204  +        /// The rowid column is not accessible on a
          205  +        /// WITHOUT ROWID virtual table (of course).  Furthermore, since the
          206  +        /// xUpdate method depends on having a valid rowid, the xUpdate method 
          207  +        /// must be NULL for a WITHOUT ROWID virtual table.  That in turn means that
          208  +        /// WITHOUT ROWID virtual tables must be read-only.
          209  +        /// </para>
   180    210           /// </summary>
   181    211           /// <param name="pDb">
   182    212           /// The native database connection handle.
   183    213           /// </param>
   184    214           /// <param name="pAux">
   185    215           /// The original native pointer value that was provided to the
   186    216           /// sqlite3_create_module(), sqlite3_create_module_v2() or