New sqlite3_module method: xPrepareSql()

This commit adds a new method named xPrepareSql to sqlite3_module and an
associated opcode VPrepareSql. That opcode is emitted immediately before
a VFilter opcode when querying virtual tables.

xPrepareSql takes two arguments: a pointer to the virtual table's cursor
and, missing from existing sqlite3_module methods, the SQL string being
executed by the application.

Prior to the introduction of this method, a virtual table that mirrored
a remote table had no way to tell which columns of the remote server
were requested by the application. Therefore, such an implementation
would typically `SELECT *` from the remote table and let callbacks such
as xColumn() and xNext() decide which data to send back to the
application. The problem with this approach is that queries that SELECT
just a subset of the remote columns trigger the transfer of data over
the network even though they won't be used.

xPrepareSql gives an opportunity for the virtual table implementation to
inspect the query string and selectively choose which columns from the
remote server to pull and cache locally.

Because this change introduces a new method to sqlite3_module, new
modules wishing to implement a callback for xPrepareSql must declare
a module version (iVersion) 4 or above.

Author: lucasvr

src/sqlite.h.in

@@ -7076,6 +7076,8 @@ struct sqlite3_module {
   /* The methods above are in versions 1 and 2 of the sqlite_module object.
   ** Those below are for version 3 and greater. */
   int (*xShadowName)(const char*);
+  /** The methods below are for version 4 and greater. */
+  int (*xPrepareSql)(sqlite3_vtab_cursor*, const char*);
 };
 
 /*

src/test8.c

@@ -1293,6 +1293,17 @@ static int echoRollbackTo(sqlite3_vtab *pVTab, int iSavepoint){
   return SQLITE_OK;
 }
 
+static int echoShadowName(const char *name){
+  assert( name );
+  return SQLITE_OK;
+}
+
+static int echoPrepareSql(sqlite3_vtab_cursor *cur, const char *sql){
+  assert( cur );
+  assert( sql );
+  return SQLITE_OK;
+}
+
 /*
 ** A virtual table module that merely "echos" the contents of another
 ** table (like an SQL VIEW).
@@ -1321,7 +1332,7 @@ static sqlite3_module echoModule = {
 };
 
 static sqlite3_module echoModuleV2 = {
-  2,                         /* iVersion */
+  4,                         /* iVersion */
   echoCreate,
   echoConnect,
   echoBestIndex,
@@ -1343,7 +1354,9 @@ static sqlite3_module echoModuleV2 = {
   echoRename,                /* xRename - rename the table */
   echoSavepoint,
   echoRelease,
-  echoRollbackTo
+  echoRollbackTo,
+  echoShadowName,
+  echoPrepareSql,
 };
 
 /*

src/vdbe.c

@@ -8072,6 +8072,40 @@ case OP_VInitIn: {        /* out2 */
 }
 #endif /* SQLITE_OMIT_VIRTUALTABLE */
 
+#ifndef SQLITE_OMIT_VIRTUALTABLE
+/* Opcode: VPrepareSql P1 * * * *
+**
+** P1 is a cursor opened using VOpen.
+**
+** This opcode invokes the xPrepareSql method on the virtual table specified
+** by P1. The SQL text parameter to xPrepareSql is obtained from Vdbe* `p`.
+**
+*/
+case OP_VPrepareSql: {
+  const sqlite3_module *pModule;
+  sqlite3_vtab_cursor *pVCur;
+  sqlite3_vtab *pVtab;
+  VdbeCursor *pCur;
+
+  pCur = p->apCsr[pOp->p1];
+  assert( pCur!=0 );
+  assert( pCur->eCurType==CURTYPE_VTAB );
+  pVCur = pCur->uc.pVCur;
+  pVtab = pVCur->pVtab;
+  pModule = pVtab->pModule;
+
+  /* Invoke the xPrepareSql method */
+   if( pModule->iVersion>=4 ){
+    if( pModule->xPrepareSql && p->zSql ){
+      rc = pModule->xPrepareSql(pVCur, p->zSql);
+      if( rc ) goto abort_due_to_error; // TODO set and test error msg
+    }
+  }
+
+  if( rc ) goto abort_due_to_error;
+  break;
+}
+#endif /* SQLITE_OMIT_VIRTUALTABLE */
 
 #ifndef SQLITE_OMIT_VIRTUALTABLE
 /* Opcode: VFilter P1 P2 P3 P4 *

src/wherecode.c

@@ -1415,6 +1415,8 @@ Bitmask sqlite3WhereCodeOneLoopStart(
     int addrNotFound;
     int nConstraint = pLoop->nLTerm;
 
+    sqlite3VdbeAddOp1(v, OP_VPrepareSql, iCur);
+
     iReg = sqlite3GetTempRange(pParse, nConstraint+2);
     addrNotFound = pLevel->addrBrk;
     for(j=0; j<nConstraint; j++){

test/rowvaluevtab.test

@@ -22,6 +22,10 @@ ifcapable !vtab {
 
 register_echo_module db
 
+#############
+# Test echo
+#############
+
 do_execsql_test 1.0 {
   CREATE TABLE t1(a, b, c);
   CREATE INDEX t1b ON t1(b);
@@ -92,4 +96,40 @@ do_vfilter4_test 1.4f {
   SELECT a FROM e1 WHERE (b, c) IN ( VALUES(2, 2) )
 } {{SELECT rowid, a, b, c FROM 't1' WHERE b = ?}}
 
+######################################################################
+# Test echo_v2. We simply want to ensure that OP_VPrepareSql executes
+######################################################################
+
+do_execsql_test 2.0 {
+  CREATE TABLE t2(a, b, c);
+  CREATE INDEX t2b ON t2(b);
+  INSERT INTO t2 VALUES('one', 1, 1);
+  INSERT INTO t2 VALUES('two', 1, 2);
+  INSERT INTO t2 VALUES('three', 1, 3);
+
+  WITH s(i) AS (
+    SELECT 1 UNION ALL SELECT i+1 FROM s WHERE i<10000
+  ) INSERT INTO t2 SELECT NULL, NULL, NULL FROM s;
+  CREATE VIRTUAL TABLE e2 USING echo_v2(t2);
+}
+
+proc do_vpreparesql1_test {tn sql expected} {
+  set rc -1
+  db eval "explain $sql" {
+    if {$opcode=="VPrepareSql"} {
+      set rc 0
+    }
+  }
+  if {$rc != $expected} {
+    error "Unexpected result $rc, was hoping for $expected"
+  }
+}
+
+do_execsql_test 2.1 {
+  SELECT a FROM e2 WHERE (b, c) IN ( VALUES(1, 3) )
+} {three}
+do_vpreparesql1_test 2.1f {
+  SELECT a FROM e2 WHERE (b, c) IN ( VALUES(2, 2) )
+} {0}
+
 finish_test