Documentation Source Text

<blockquote><pre>
   CREATE TABLE x(a HIDDEN VARCHAR(12), b INTEGER, c INTEGER Hidden);
</pre></blockquote>

<p>Then the virtual table would be created with two hidden columns,
and with datatypes of "VARCHAR(12)" and "INTEGER".





<p>The xCreate must should return [SQLITE_OK] if it is successful in 
creating the new virtual table, or [SQLITE_ERROR] if it is not successful.
If not successful, the [sqlite3_vtab] structure must not be allocated. 
An error message may optionally be returned in *pzErr if unsuccessful.
Space to hold the error message string must be allocated using
an SQLite memory allocation function like 
................................................................................

<p>For example, if the aConstraint[3].argvIndex is set to 1, then 
when xFilter is called, the argv[0] passed to xFilter will have 
the EXPR value of the aConstraint[3] constraint.

<p>By default, the SQLite core double checks all constraints on 
each row of the virtual table that it receives. If such a check 
is redundant, the xBestFilter method can suppress that check by 
setting aConstraintUsage[].omit.

<tcl>########################################################## xDisconnect
hd_fragment xdisconnect {sqlite3_module.xDisconnect} {xDisconnect}</tcl>
<h3>2.4 The xDisconnect Method</h3>

<blockquote><pre>
................................................................................
will allocate the memory for the [sqlite3_vtab_cursor] (or a subclass),
initialize the new object, and make *ppCursor point to the new object.
The successful call then returns [SQLITE_OK].

<p>For every successful call to this method, the SQLite core will
later invoke the [sqlite3_module.xClose | xClose] method to destroy 
the allocated cursor.





<p>A virtual table implementation must be able to support an arbitrary
number of simultaneously open cursors.

<p>When initially opened, the cursor is in an undefined state.
The SQLite core will invoke the [xFilter] method
on the cursor prior to any attempt to position or read from the cursor.
................................................................................

<blockquote><pre>
  int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int N);
</pre></blockquote>

<p>The SQLite core invokes this method in order to find the value for 
the N-th column of the current row. N is zero-based so the first column 
is numbered 0. The xColumn method must uses one of the 
[sqlite3_result_blob | sqlite3_result_*() APIs] 
to return the result. 
The xColumn method returns its result back to SQLite using one of the
following interface:

<p>

<li> [sqlite3_result_blob()]
<li> [sqlite3_result_double()]
<li> [sqlite3_result_int()]
<li> [sqlite3_result_int64()]
<li> [sqlite3_result_null()]
<li> [sqlite3_result_text()]
<li> [sqlite3_result_text16()]
<li> [sqlite3_result_text16le()]
<li> [sqlite3_result_text16be()]
<li> [sqlite3_result_zeroblob()]

</p>




<p>To raise an error, the xColumn method should use one of the result_text() 
methods to set the error message text, then return an appropriate
[error code].  The xColumn method must return [SQLITE_OK] on success.

<p>The xColumn method is required for every virtual table implementation.

<blockquote><pre>
   CREATE TABLE x(a HIDDEN VARCHAR(12), b INTEGER, c INTEGER Hidden);
</pre></blockquote>

<p>Then the virtual table would be created with two hidden columns,
and with datatypes of "VARCHAR(12)" and "INTEGER".

<p>The xCreate method need not initialize the pModule, nRef, and zErrMsg
fields of the [sqlite3_vtab] object.  The SQLite core will take care of 
that chore.

<p>The xCreate must should return [SQLITE_OK] if it is successful in 
creating the new virtual table, or [SQLITE_ERROR] if it is not successful.
If not successful, the [sqlite3_vtab] structure must not be allocated. 
An error message may optionally be returned in *pzErr if unsuccessful.
Space to hold the error message string must be allocated using
an SQLite memory allocation function like 
................................................................................

<p>For example, if the aConstraint[3].argvIndex is set to 1, then 
when xFilter is called, the argv[0] passed to xFilter will have 
the EXPR value of the aConstraint[3] constraint.

<p>By default, the SQLite core double checks all constraints on 
each row of the virtual table that it receives. If such a check 
is redundant, the xBestFilter method can suppress that double-check by 
setting aConstraintUsage[].omit.

<tcl>########################################################## xDisconnect
hd_fragment xdisconnect {sqlite3_module.xDisconnect} {xDisconnect}</tcl>
<h3>2.4 The xDisconnect Method</h3>

<blockquote><pre>
................................................................................
will allocate the memory for the [sqlite3_vtab_cursor] (or a subclass),
initialize the new object, and make *ppCursor point to the new object.
The successful call then returns [SQLITE_OK].

<p>For every successful call to this method, the SQLite core will
later invoke the [sqlite3_module.xClose | xClose] method to destroy 
the allocated cursor.

<p>The xOpen method need not initialize the pVtab field of the
[sqlite3_vtab_cursor] structure.  The SQLite core will take care
of that chore automatically.

<p>A virtual table implementation must be able to support an arbitrary
number of simultaneously open cursors.

<p>When initially opened, the cursor is in an undefined state.
The SQLite core will invoke the [xFilter] method
on the cursor prior to any attempt to position or read from the cursor.
................................................................................

<blockquote><pre>
  int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int N);
</pre></blockquote>

<p>The SQLite core invokes this method in order to find the value for 
the N-th column of the current row. N is zero-based so the first column 
is numbered 0. 


The xColumn method may return its result back to SQLite using one of the
following interface:

<p>
<ul>
<li> [sqlite3_result_blob()]
<li> [sqlite3_result_double()]
<li> [sqlite3_result_int()]
<li> [sqlite3_result_int64()]
<li> [sqlite3_result_null()]
<li> [sqlite3_result_text()]
<li> [sqlite3_result_text16()]
<li> [sqlite3_result_text16le()]
<li> [sqlite3_result_text16be()]
<li> [sqlite3_result_zeroblob()]
</ul>
</p>

<p>If the xColumn method implementation calls none of the functions above,
then the value of the column defaults to an SQL NULL.

<p>To raise an error, the xColumn method should use one of the result_text() 
methods to set the error message text, then return an appropriate
[error code].  The xColumn method must return [SQLITE_OK] on success.

<p>The xColumn method is required for every virtual table implementation.

database component off onto a separate machine, then you should 
definitely consider using an enterprise-class client/server database
engine instead of SQLite.</p>
</li>

<li><p><b>Very large datasets</b></p>

<p>When you start a transaction in SQLite (which happens automatically
before any write operation that is not within an explicit BEGIN...COMMIT)
the engine has to allocate a bitmap of dirty pages in the disk file to
help it manage its rollback journal.  SQLite needs 256 bytes of RAM for
every 1MiB of database (assuming a 1024-byte page size: less memory is
used with larger page sizes, of course).  
For smaller databases, the amount of memory
required is not a problem, but when database begins to grow into the
multi-gigabyte range, the size of the bitmap can get quite large.  If
you need to store and modify more than a few dozen GB of data, you should
consider using a different database engine.
</p>
</li>

<li><p><b>High Concurrency</b></p>

<p>
SQLite uses reader/writer locks on the entire database file.  That means

database component off onto a separate machine, then you should 
definitely consider using an enterprise-class client/server database
engine instead of SQLite.</p>
</li>

<li><p><b>Very large datasets</b></p>

<p>With the default page size of 1024 bytes, an SQLite database is
limited in size to 2 tebibytes (2<sup><small>41</small></sup> bytes).
And even if it could handle larger databases, SQLite stores the entire
database in a single disk file and many filesystems limit the maximum
size of files to something less than this.  So if you are contemplating
databases of this magnitude, you would do well to consider using a
client/server database engine that spreads its content across multiple
disk files, and prehaps across multiple volumes.



</p>
</li>

<li><p><b>High Concurrency</b></p>

<p>
SQLite uses reader/writer locks on the entire database file.  That means