4 ** The author disclaims copyright to this source code. In place of
5 ** a legal notice, here is a blessing:
7 ** May you do good and not evil.
8 ** May you find forgiveness for yourself and forgive others.
9 ** May you share freely, never taking more than you give.
11 *************************************************************************
12 ** This file contains code used to help implement virtual tables.
14 #ifndef SQLITE_OMIT_VIRTUALTABLE
15 #include "sqliteInt.h"
18 ** Before a virtual table xCreate() or xConnect() method is invoked, the
19 ** sqlite3.pVtabCtx member variable is set to point to an instance of
20 ** this struct allocated on the stack. It is used by the implementation of
21 ** the sqlite3_declare_vtab() and sqlite3_vtab_config() APIs, both of which
22 ** are invoked only from within xCreate and xConnect methods.
25 VTable
*pVTable
; /* The virtual table being constructed */
26 Table
*pTab
; /* The Table object to which the virtual table belongs */
27 VtabCtx
*pPrior
; /* Parent context (if any) */
28 int bDeclared
; /* True after sqlite3_declare_vtab() is called */
32 ** Construct and install a Module object for a virtual table. When this
33 ** routine is called, it is guaranteed that all appropriate locks are held
34 ** and the module is not already part of the connection.
36 Module
*sqlite3VtabCreateModule(
37 sqlite3
*db
, /* Database in which module is registered */
38 const char *zName
, /* Name assigned to this module */
39 const sqlite3_module
*pModule
, /* The definition of the module */
40 void *pAux
, /* Context pointer for xCreate/xConnect */
41 void (*xDestroy
)(void *) /* Module destructor function */
44 int nName
= sqlite3Strlen30(zName
);
45 pMod
= (Module
*)sqlite3Malloc(sizeof(Module
) + nName
+ 1);
50 char *zCopy
= (char *)(&pMod
[1]);
51 memcpy(zCopy
, zName
, nName
+1);
53 pMod
->pModule
= pModule
;
55 pMod
->xDestroy
= xDestroy
;
57 pDel
= (Module
*)sqlite3HashInsert(&db
->aModule
,zCopy
,(void*)pMod
);
58 assert( pDel
==0 || pDel
==pMod
);
61 sqlite3DbFree(db
, pDel
);
69 ** The actual function that does the work of creating a new module.
70 ** This function implements the sqlite3_create_module() and
71 ** sqlite3_create_module_v2() interfaces.
73 static int createModule(
74 sqlite3
*db
, /* Database in which module is registered */
75 const char *zName
, /* Name assigned to this module */
76 const sqlite3_module
*pModule
, /* The definition of the module */
77 void *pAux
, /* Context pointer for xCreate/xConnect */
78 void (*xDestroy
)(void *) /* Module destructor function */
82 sqlite3_mutex_enter(db
->mutex
);
83 if( sqlite3HashFind(&db
->aModule
, zName
) ){
84 rc
= SQLITE_MISUSE_BKPT
;
86 (void)sqlite3VtabCreateModule(db
, zName
, pModule
, pAux
, xDestroy
);
88 rc
= sqlite3ApiExit(db
, rc
);
89 if( rc
!=SQLITE_OK
&& xDestroy
) xDestroy(pAux
);
90 sqlite3_mutex_leave(db
->mutex
);
96 ** External API function used to create a new virtual-table module.
98 int sqlite3_create_module(
99 sqlite3
*db
, /* Database in which module is registered */
100 const char *zName
, /* Name assigned to this module */
101 const sqlite3_module
*pModule
, /* The definition of the module */
102 void *pAux
/* Context pointer for xCreate/xConnect */
104 #ifdef SQLITE_ENABLE_API_ARMOR
105 if( !sqlite3SafetyCheckOk(db
) || zName
==0 ) return SQLITE_MISUSE_BKPT
;
107 return createModule(db
, zName
, pModule
, pAux
, 0);
111 ** External API function used to create a new virtual-table module.
113 int sqlite3_create_module_v2(
114 sqlite3
*db
, /* Database in which module is registered */
115 const char *zName
, /* Name assigned to this module */
116 const sqlite3_module
*pModule
, /* The definition of the module */
117 void *pAux
, /* Context pointer for xCreate/xConnect */
118 void (*xDestroy
)(void *) /* Module destructor function */
120 #ifdef SQLITE_ENABLE_API_ARMOR
121 if( !sqlite3SafetyCheckOk(db
) || zName
==0 ) return SQLITE_MISUSE_BKPT
;
123 return createModule(db
, zName
, pModule
, pAux
, xDestroy
);
127 ** Lock the virtual table so that it cannot be disconnected.
128 ** Locks nest. Every lock should have a corresponding unlock.
129 ** If an unlock is omitted, resources leaks will occur.
131 ** If a disconnect is attempted while a virtual table is locked,
132 ** the disconnect is deferred until all locks have been removed.
134 void sqlite3VtabLock(VTable
*pVTab
){
140 ** pTab is a pointer to a Table structure representing a virtual-table.
141 ** Return a pointer to the VTable object used by connection db to access
142 ** this virtual-table, if one has been created, or NULL otherwise.
144 VTable
*sqlite3GetVTable(sqlite3
*db
, Table
*pTab
){
146 assert( IsVirtual(pTab
) );
147 for(pVtab
=pTab
->pVTable
; pVtab
&& pVtab
->db
!=db
; pVtab
=pVtab
->pNext
);
152 ** Decrement the ref-count on a virtual table object. When the ref-count
153 ** reaches zero, call the xDisconnect() method to delete the object.
155 void sqlite3VtabUnlock(VTable
*pVTab
){
156 sqlite3
*db
= pVTab
->db
;
159 assert( pVTab
->nRef
>0 );
160 assert( db
->magic
==SQLITE_MAGIC_OPEN
|| db
->magic
==SQLITE_MAGIC_ZOMBIE
);
163 if( pVTab
->nRef
==0 ){
164 sqlite3_vtab
*p
= pVTab
->pVtab
;
166 p
->pModule
->xDisconnect(p
);
168 sqlite3DbFree(db
, pVTab
);
173 ** Table p is a virtual table. This function moves all elements in the
174 ** p->pVTable list to the sqlite3.pDisconnect lists of their associated
175 ** database connections to be disconnected at the next opportunity.
176 ** Except, if argument db is not NULL, then the entry associated with
177 ** connection db is left in the p->pVTable list.
179 static VTable
*vtabDisconnectAll(sqlite3
*db
, Table
*p
){
181 VTable
*pVTable
= p
->pVTable
;
184 /* Assert that the mutex (if any) associated with the BtShared database
185 ** that contains table p is held by the caller. See header comments
186 ** above function sqlite3VtabUnlockList() for an explanation of why
187 ** this makes it safe to access the sqlite3.pDisconnect list of any
188 ** database connection that may have an entry in the p->pVTable list.
190 assert( db
==0 || sqlite3SchemaMutexHeld(db
, 0, p
->pSchema
) );
193 sqlite3
*db2
= pVTable
->db
;
194 VTable
*pNext
= pVTable
->pNext
;
201 pVTable
->pNext
= db2
->pDisconnect
;
202 db2
->pDisconnect
= pVTable
;
207 assert( !db
|| pRet
);
212 ** Table *p is a virtual table. This function removes the VTable object
213 ** for table *p associated with database connection db from the linked
214 ** list in p->pVTab. It also decrements the VTable ref count. This is
215 ** used when closing database connection db to free all of its VTable
216 ** objects without disturbing the rest of the Schema object (which may
217 ** be being used by other shared-cache connections).
219 void sqlite3VtabDisconnect(sqlite3
*db
, Table
*p
){
222 assert( IsVirtual(p
) );
223 assert( sqlite3BtreeHoldsAllMutexes(db
) );
224 assert( sqlite3_mutex_held(db
->mutex
) );
226 for(ppVTab
=&p
->pVTable
; *ppVTab
; ppVTab
=&(*ppVTab
)->pNext
){
227 if( (*ppVTab
)->db
==db
){
228 VTable
*pVTab
= *ppVTab
;
229 *ppVTab
= pVTab
->pNext
;
230 sqlite3VtabUnlock(pVTab
);
238 ** Disconnect all the virtual table objects in the sqlite3.pDisconnect list.
240 ** This function may only be called when the mutexes associated with all
241 ** shared b-tree databases opened using connection db are held by the
242 ** caller. This is done to protect the sqlite3.pDisconnect list. The
243 ** sqlite3.pDisconnect list is accessed only as follows:
245 ** 1) By this function. In this case, all BtShared mutexes and the mutex
246 ** associated with the database handle itself must be held.
248 ** 2) By function vtabDisconnectAll(), when it adds a VTable entry to
249 ** the sqlite3.pDisconnect list. In this case either the BtShared mutex
250 ** associated with the database the virtual table is stored in is held
251 ** or, if the virtual table is stored in a non-sharable database, then
252 ** the database handle mutex is held.
254 ** As a result, a sqlite3.pDisconnect cannot be accessed simultaneously
255 ** by multiple threads. It is thread-safe.
257 void sqlite3VtabUnlockList(sqlite3
*db
){
258 VTable
*p
= db
->pDisconnect
;
261 assert( sqlite3BtreeHoldsAllMutexes(db
) );
262 assert( sqlite3_mutex_held(db
->mutex
) );
265 sqlite3ExpirePreparedStatements(db
);
267 VTable
*pNext
= p
->pNext
;
268 sqlite3VtabUnlock(p
);
275 ** Clear any and all virtual-table information from the Table record.
276 ** This routine is called, for example, just before deleting the Table
279 ** Since it is a virtual-table, the Table structure contains a pointer
280 ** to the head of a linked list of VTable structures. Each VTable
281 ** structure is associated with a single sqlite3* user of the schema.
282 ** The reference count of the VTable structure associated with database
283 ** connection db is decremented immediately (which may lead to the
284 ** structure being xDisconnected and free). Any other VTable structures
285 ** in the list are moved to the sqlite3.pDisconnect list of the associated
286 ** database connection.
288 void sqlite3VtabClear(sqlite3
*db
, Table
*p
){
289 if( !db
|| db
->pnBytesFreed
==0 ) vtabDisconnectAll(0, p
);
290 if( p
->azModuleArg
){
292 for(i
=0; i
<p
->nModuleArg
; i
++){
293 if( i
!=1 ) sqlite3DbFree(db
, p
->azModuleArg
[i
]);
295 sqlite3DbFree(db
, p
->azModuleArg
);
300 ** Add a new module argument to pTable->azModuleArg[].
301 ** The string is not copied - the pointer is stored. The
302 ** string will be freed automatically when the table is
305 static void addModuleArgument(sqlite3
*db
, Table
*pTable
, char *zArg
){
306 int nBytes
= sizeof(char *)*(2+pTable
->nModuleArg
);
308 azModuleArg
= sqlite3DbRealloc(db
, pTable
->azModuleArg
, nBytes
);
309 if( azModuleArg
==0 ){
310 sqlite3DbFree(db
, zArg
);
312 int i
= pTable
->nModuleArg
++;
313 azModuleArg
[i
] = zArg
;
314 azModuleArg
[i
+1] = 0;
315 pTable
->azModuleArg
= azModuleArg
;
320 ** The parser calls this routine when it first sees a CREATE VIRTUAL TABLE
321 ** statement. The module name has been parsed, but the optional list
322 ** of parameters that follow the module name are still pending.
324 void sqlite3VtabBeginParse(
325 Parse
*pParse
, /* Parsing context */
326 Token
*pName1
, /* Name of new table, or database name */
327 Token
*pName2
, /* Name of new table or NULL */
328 Token
*pModuleName
, /* Name of the module for the virtual table */
329 int ifNotExists
/* No error if the table already exists */
331 int iDb
; /* The database the table is being created in */
332 Table
*pTable
; /* The new virtual table */
333 sqlite3
*db
; /* Database connection */
335 sqlite3StartTable(pParse
, pName1
, pName2
, 0, 0, 1, ifNotExists
);
336 pTable
= pParse
->pNewTable
;
337 if( pTable
==0 ) return;
338 assert( 0==pTable
->pIndex
);
341 iDb
= sqlite3SchemaToIndex(db
, pTable
->pSchema
);
344 assert( pTable
->nModuleArg
==0 );
345 addModuleArgument(db
, pTable
, sqlite3NameFromToken(db
, pModuleName
));
346 addModuleArgument(db
, pTable
, 0);
347 addModuleArgument(db
, pTable
, sqlite3DbStrDup(db
, pTable
->zName
));
348 assert( (pParse
->sNameToken
.z
==pName2
->z
&& pName2
->z
!=0)
349 || (pParse
->sNameToken
.z
==pName1
->z
&& pName2
->z
==0)
351 pParse
->sNameToken
.n
= (int)(
352 &pModuleName
->z
[pModuleName
->n
] - pParse
->sNameToken
.z
355 #ifndef SQLITE_OMIT_AUTHORIZATION
356 /* Creating a virtual table invokes the authorization callback twice.
357 ** The first invocation, to obtain permission to INSERT a row into the
358 ** sqlite_master table, has already been made by sqlite3StartTable().
359 ** The second call, to obtain permission to create the table, is made now.
361 if( pTable
->azModuleArg
){
362 sqlite3AuthCheck(pParse
, SQLITE_CREATE_VTABLE
, pTable
->zName
,
363 pTable
->azModuleArg
[0], pParse
->db
->aDb
[iDb
].zDbSName
);
369 ** This routine takes the module argument that has been accumulating
370 ** in pParse->zArg[] and appends it to the list of arguments on the
371 ** virtual table currently under construction in pParse->pTable.
373 static void addArgumentToVtab(Parse
*pParse
){
374 if( pParse
->sArg
.z
&& pParse
->pNewTable
){
375 const char *z
= (const char*)pParse
->sArg
.z
;
376 int n
= pParse
->sArg
.n
;
377 sqlite3
*db
= pParse
->db
;
378 addModuleArgument(db
, pParse
->pNewTable
, sqlite3DbStrNDup(db
, z
, n
));
383 ** The parser calls this routine after the CREATE VIRTUAL TABLE statement
384 ** has been completely parsed.
386 void sqlite3VtabFinishParse(Parse
*pParse
, Token
*pEnd
){
387 Table
*pTab
= pParse
->pNewTable
; /* The table being constructed */
388 sqlite3
*db
= pParse
->db
; /* The database connection */
390 if( pTab
==0 ) return;
391 addArgumentToVtab(pParse
);
393 if( pTab
->nModuleArg
<1 ) return;
395 /* If the CREATE VIRTUAL TABLE statement is being entered for the
396 ** first time (in other words if the virtual table is actually being
397 ** created now instead of just being read out of sqlite_master) then
398 ** do additional initialization work and store the statement text
399 ** in the sqlite_master table.
401 if( !db
->init
.busy
){
408 /* Compute the complete text of the CREATE VIRTUAL TABLE statement */
410 pParse
->sNameToken
.n
= (int)(pEnd
->z
- pParse
->sNameToken
.z
) + pEnd
->n
;
412 zStmt
= sqlite3MPrintf(db
, "CREATE VIRTUAL TABLE %T", &pParse
->sNameToken
);
414 /* A slot for the record has already been allocated in the
415 ** SQLITE_MASTER table. We just need to update that slot with all
416 ** the information we've collected.
418 ** The VM register number pParse->regRowid holds the rowid of an
419 ** entry in the sqlite_master table tht was created for this vtab
420 ** by sqlite3StartTable().
422 iDb
= sqlite3SchemaToIndex(db
, pTab
->pSchema
);
423 sqlite3NestedParse(pParse
,
425 "SET type='table', name=%Q, tbl_name=%Q, rootpage=0, sql=%Q "
427 db
->aDb
[iDb
].zDbSName
, MASTER_NAME
,
433 sqlite3DbFree(db
, zStmt
);
434 v
= sqlite3GetVdbe(pParse
);
435 sqlite3ChangeCookie(pParse
, iDb
);
437 sqlite3VdbeAddOp0(v
, OP_Expire
);
438 zWhere
= sqlite3MPrintf(db
, "name='%q' AND type='table'", pTab
->zName
);
439 sqlite3VdbeAddParseSchemaOp(v
, iDb
, zWhere
);
441 iReg
= ++pParse
->nMem
;
442 sqlite3VdbeLoadString(v
, iReg
, pTab
->zName
);
443 sqlite3VdbeAddOp2(v
, OP_VCreate
, iDb
, iReg
);
446 /* If we are rereading the sqlite_master table create the in-memory
447 ** record of the table. The xConnect() method is not called until
448 ** the first time the virtual table is used in an SQL statement. This
449 ** allows a schema that contains virtual tables to be loaded before
450 ** the required virtual table implementations are registered. */
453 Schema
*pSchema
= pTab
->pSchema
;
454 const char *zName
= pTab
->zName
;
455 assert( sqlite3SchemaMutexHeld(db
, 0, pSchema
) );
456 pOld
= sqlite3HashInsert(&pSchema
->tblHash
, zName
, pTab
);
459 assert( pTab
==pOld
); /* Malloc must have failed inside HashInsert() */
462 pParse
->pNewTable
= 0;
467 ** The parser calls this routine when it sees the first token
468 ** of an argument to the module name in a CREATE VIRTUAL TABLE statement.
470 void sqlite3VtabArgInit(Parse
*pParse
){
471 addArgumentToVtab(pParse
);
477 ** The parser calls this routine for each token after the first token
478 ** in an argument to the module name in a CREATE VIRTUAL TABLE statement.
480 void sqlite3VtabArgExtend(Parse
*pParse
, Token
*p
){
481 Token
*pArg
= &pParse
->sArg
;
486 assert(pArg
->z
<= p
->z
);
487 pArg
->n
= (int)(&p
->z
[p
->n
] - pArg
->z
);
492 ** Invoke a virtual table constructor (either xCreate or xConnect). The
493 ** pointer to the function to invoke is passed as the fourth parameter
494 ** to this procedure.
496 static int vtabCallConstructor(
500 int (*xConstruct
)(sqlite3
*,void*,int,const char*const*,sqlite3_vtab
**,char**),
506 const char *const*azArg
= (const char *const*)pTab
->azModuleArg
;
507 int nArg
= pTab
->nModuleArg
;
513 /* Check that the virtual-table is not already being initialized */
514 for(pCtx
=db
->pVtabCtx
; pCtx
; pCtx
=pCtx
->pPrior
){
515 if( pCtx
->pTab
==pTab
){
516 *pzErr
= sqlite3MPrintf(db
,
517 "vtable constructor called recursively: %s", pTab
->zName
519 return SQLITE_LOCKED
;
523 zModuleName
= sqlite3DbStrDup(db
, pTab
->zName
);
525 return SQLITE_NOMEM_BKPT
;
528 pVTable
= sqlite3MallocZero(sizeof(VTable
));
531 sqlite3DbFree(db
, zModuleName
);
532 return SQLITE_NOMEM_BKPT
;
535 pVTable
->pMod
= pMod
;
537 iDb
= sqlite3SchemaToIndex(db
, pTab
->pSchema
);
538 pTab
->azModuleArg
[1] = db
->aDb
[iDb
].zDbSName
;
540 /* Invoke the virtual table constructor */
541 assert( &db
->pVtabCtx
);
542 assert( xConstruct
);
544 sCtx
.pVTable
= pVTable
;
545 sCtx
.pPrior
= db
->pVtabCtx
;
547 db
->pVtabCtx
= &sCtx
;
548 rc
= xConstruct(db
, pMod
->pAux
, nArg
, azArg
, &pVTable
->pVtab
, &zErr
);
549 db
->pVtabCtx
= sCtx
.pPrior
;
550 if( rc
==SQLITE_NOMEM
) sqlite3OomFault(db
);
551 assert( sCtx
.pTab
==pTab
);
555 *pzErr
= sqlite3MPrintf(db
, "vtable constructor failed: %s", zModuleName
);
557 *pzErr
= sqlite3MPrintf(db
, "%s", zErr
);
560 sqlite3DbFree(db
, pVTable
);
561 }else if( ALWAYS(pVTable
->pVtab
) ){
562 /* Justification of ALWAYS(): A correct vtab constructor must allocate
563 ** the sqlite3_vtab object if successful. */
564 memset(pVTable
->pVtab
, 0, sizeof(pVTable
->pVtab
[0]));
565 pVTable
->pVtab
->pModule
= pMod
->pModule
;
567 if( sCtx
.bDeclared
==0 ){
568 const char *zFormat
= "vtable constructor did not declare schema: %s";
569 *pzErr
= sqlite3MPrintf(db
, zFormat
, pTab
->zName
);
570 sqlite3VtabUnlock(pVTable
);
575 /* If everything went according to plan, link the new VTable structure
576 ** into the linked list headed by pTab->pVTable. Then loop through the
577 ** columns of the table to see if any of them contain the token "hidden".
578 ** If so, set the Column COLFLAG_HIDDEN flag and remove the token from
579 ** the type string. */
580 pVTable
->pNext
= pTab
->pVTable
;
581 pTab
->pVTable
= pVTable
;
583 for(iCol
=0; iCol
<pTab
->nCol
; iCol
++){
584 char *zType
= sqlite3ColumnType(&pTab
->aCol
[iCol
], "");
587 nType
= sqlite3Strlen30(zType
);
588 for(i
=0; i
<nType
; i
++){
589 if( 0==sqlite3StrNICmp("hidden", &zType
[i
], 6)
590 && (i
==0 || zType
[i
-1]==' ')
591 && (zType
[i
+6]=='\0' || zType
[i
+6]==' ')
598 int nDel
= 6 + (zType
[i
+6] ? 1 : 0);
599 for(j
=i
; (j
+nDel
)<=nType
; j
++){
600 zType
[j
] = zType
[j
+nDel
];
602 if( zType
[i
]=='\0' && i
>0 ){
603 assert(zType
[i
-1]==' ');
606 pTab
->aCol
[iCol
].colFlags
|= COLFLAG_HIDDEN
;
607 oooHidden
= TF_OOOHidden
;
609 pTab
->tabFlags
|= oooHidden
;
615 sqlite3DbFree(db
, zModuleName
);
620 ** This function is invoked by the parser to call the xConnect() method
621 ** of the virtual table pTab. If an error occurs, an error code is returned
622 ** and an error left in pParse.
624 ** This call is a no-op if table pTab is not a virtual table.
626 int sqlite3VtabCallConnect(Parse
*pParse
, Table
*pTab
){
627 sqlite3
*db
= pParse
->db
;
633 if( !IsVirtual(pTab
) || sqlite3GetVTable(db
, pTab
) ){
637 /* Locate the required virtual table module */
638 zMod
= pTab
->azModuleArg
[0];
639 pMod
= (Module
*)sqlite3HashFind(&db
->aModule
, zMod
);
642 const char *zModule
= pTab
->azModuleArg
[0];
643 sqlite3ErrorMsg(pParse
, "no such module: %s", zModule
);
647 rc
= vtabCallConstructor(db
, pTab
, pMod
, pMod
->pModule
->xConnect
, &zErr
);
649 sqlite3ErrorMsg(pParse
, "%s", zErr
);
652 sqlite3DbFree(db
, zErr
);
658 ** Grow the db->aVTrans[] array so that there is room for at least one
659 ** more v-table. Return SQLITE_NOMEM if a malloc fails, or SQLITE_OK otherwise.
661 static int growVTrans(sqlite3
*db
){
662 const int ARRAY_INCR
= 5;
664 /* Grow the sqlite3.aVTrans array if required */
665 if( (db
->nVTrans
%ARRAY_INCR
)==0 ){
667 int nBytes
= sizeof(sqlite3_vtab
*) * (db
->nVTrans
+ ARRAY_INCR
);
668 aVTrans
= sqlite3DbRealloc(db
, (void *)db
->aVTrans
, nBytes
);
670 return SQLITE_NOMEM_BKPT
;
672 memset(&aVTrans
[db
->nVTrans
], 0, sizeof(sqlite3_vtab
*)*ARRAY_INCR
);
673 db
->aVTrans
= aVTrans
;
680 ** Add the virtual table pVTab to the array sqlite3.aVTrans[]. Space should
681 ** have already been reserved using growVTrans().
683 static void addToVTrans(sqlite3
*db
, VTable
*pVTab
){
684 /* Add pVtab to the end of sqlite3.aVTrans */
685 db
->aVTrans
[db
->nVTrans
++] = pVTab
;
686 sqlite3VtabLock(pVTab
);
690 ** This function is invoked by the vdbe to call the xCreate method
691 ** of the virtual table named zTab in database iDb.
693 ** If an error occurs, *pzErr is set to point to an English language
694 ** description of the error and an SQLITE_XXX error code is returned.
695 ** In this case the caller must call sqlite3DbFree(db, ) on *pzErr.
697 int sqlite3VtabCallCreate(sqlite3
*db
, int iDb
, const char *zTab
, char **pzErr
){
703 pTab
= sqlite3FindTable(db
, zTab
, db
->aDb
[iDb
].zDbSName
);
704 assert( pTab
&& IsVirtual(pTab
) && !pTab
->pVTable
);
706 /* Locate the required virtual table module */
707 zMod
= pTab
->azModuleArg
[0];
708 pMod
= (Module
*)sqlite3HashFind(&db
->aModule
, zMod
);
710 /* If the module has been registered and includes a Create method,
711 ** invoke it now. If the module has not been registered, return an
712 ** error. Otherwise, do nothing.
714 if( pMod
==0 || pMod
->pModule
->xCreate
==0 || pMod
->pModule
->xDestroy
==0 ){
715 *pzErr
= sqlite3MPrintf(db
, "no such module: %s", zMod
);
718 rc
= vtabCallConstructor(db
, pTab
, pMod
, pMod
->pModule
->xCreate
, pzErr
);
721 /* Justification of ALWAYS(): The xConstructor method is required to
722 ** create a valid sqlite3_vtab if it returns SQLITE_OK. */
723 if( rc
==SQLITE_OK
&& ALWAYS(sqlite3GetVTable(db
, pTab
)) ){
726 addToVTrans(db
, sqlite3GetVTable(db
, pTab
));
734 ** This function is used to set the schema of a virtual table. It is only
735 ** valid to call this function from within the xCreate() or xConnect() of a
736 ** virtual table module.
738 int sqlite3_declare_vtab(sqlite3
*db
, const char *zCreateTable
){
745 #ifdef SQLITE_ENABLE_API_ARMOR
746 if( !sqlite3SafetyCheckOk(db
) || zCreateTable
==0 ){
747 return SQLITE_MISUSE_BKPT
;
750 sqlite3_mutex_enter(db
->mutex
);
752 if( !pCtx
|| pCtx
->bDeclared
){
753 sqlite3Error(db
, SQLITE_MISUSE
);
754 sqlite3_mutex_leave(db
->mutex
);
755 return SQLITE_MISUSE_BKPT
;
758 assert( IsVirtual(pTab
) );
760 memset(&sParse
, 0, sizeof(sParse
));
761 sParse
.declareVtab
= 1;
763 sParse
.nQueryLoop
= 1;
764 if( SQLITE_OK
==sqlite3RunParser(&sParse
, zCreateTable
, &zErr
)
767 && !sParse
.pNewTable
->pSelect
768 && !IsVirtual(sParse
.pNewTable
)
771 Table
*pNew
= sParse
.pNewTable
;
773 pTab
->aCol
= pNew
->aCol
;
774 pTab
->nCol
= pNew
->nCol
;
775 pTab
->tabFlags
|= pNew
->tabFlags
& (TF_WithoutRowid
|TF_NoVisibleRowid
);
778 assert( pTab
->pIndex
==0 );
779 assert( HasRowid(pNew
) || sqlite3PrimaryKeyIndex(pNew
)!=0 );
781 && pCtx
->pVTable
->pMod
->pModule
->xUpdate
!=0
782 && sqlite3PrimaryKeyIndex(pNew
)->nKeyCol
!=1
784 /* WITHOUT ROWID virtual tables must either be read-only (xUpdate==0)
785 ** or else must have a single-column PRIMARY KEY */
790 assert( pIdx
->pNext
==0 );
798 sqlite3ErrorWithMsg(db
, SQLITE_ERROR
, (zErr
? "%s" : 0), zErr
);
799 sqlite3DbFree(db
, zErr
);
802 sParse
.declareVtab
= 0;
805 sqlite3VdbeFinalize(sParse
.pVdbe
);
807 sqlite3DeleteTable(db
, sParse
.pNewTable
);
808 sqlite3ParserReset(&sParse
);
810 assert( (rc
&0xff)==rc
);
811 rc
= sqlite3ApiExit(db
, rc
);
812 sqlite3_mutex_leave(db
->mutex
);
817 ** This function is invoked by the vdbe to call the xDestroy method
818 ** of the virtual table named zTab in database iDb. This occurs
819 ** when a DROP TABLE is mentioned.
821 ** This call is a no-op if zTab is not a virtual table.
823 int sqlite3VtabCallDestroy(sqlite3
*db
, int iDb
, const char *zTab
){
827 pTab
= sqlite3FindTable(db
, zTab
, db
->aDb
[iDb
].zDbSName
);
828 if( pTab
!=0 && ALWAYS(pTab
->pVTable
!=0) ){
830 int (*xDestroy
)(sqlite3_vtab
*);
831 for(p
=pTab
->pVTable
; p
; p
=p
->pNext
){
833 if( p
->pVtab
->nRef
>0 ){
834 return SQLITE_LOCKED
;
837 p
= vtabDisconnectAll(db
, pTab
);
838 xDestroy
= p
->pMod
->pModule
->xDestroy
;
839 assert( xDestroy
!=0 ); /* Checked before the virtual table is created */
840 rc
= xDestroy(p
->pVtab
);
841 /* Remove the sqlite3_vtab* from the aVTrans[] array, if applicable */
843 assert( pTab
->pVTable
==p
&& p
->pNext
==0 );
846 sqlite3VtabUnlock(p
);
854 ** This function invokes either the xRollback or xCommit method
855 ** of each of the virtual tables in the sqlite3.aVTrans array. The method
856 ** called is identified by the second argument, "offset", which is
857 ** the offset of the method to call in the sqlite3_module structure.
859 ** The array is cleared after invoking the callbacks.
861 static void callFinaliser(sqlite3
*db
, int offset
){
864 VTable
**aVTrans
= db
->aVTrans
;
866 for(i
=0; i
<db
->nVTrans
; i
++){
867 VTable
*pVTab
= aVTrans
[i
];
868 sqlite3_vtab
*p
= pVTab
->pVtab
;
870 int (*x
)(sqlite3_vtab
*);
871 x
= *(int (**)(sqlite3_vtab
*))((char *)p
->pModule
+ offset
);
874 pVTab
->iSavepoint
= 0;
875 sqlite3VtabUnlock(pVTab
);
877 sqlite3DbFree(db
, aVTrans
);
883 ** Invoke the xSync method of all virtual tables in the sqlite3.aVTrans
884 ** array. Return the error code for the first error that occurs, or
885 ** SQLITE_OK if all xSync operations are successful.
887 ** If an error message is available, leave it in p->zErrMsg.
889 int sqlite3VtabSync(sqlite3
*db
, Vdbe
*p
){
892 VTable
**aVTrans
= db
->aVTrans
;
895 for(i
=0; rc
==SQLITE_OK
&& i
<db
->nVTrans
; i
++){
896 int (*x
)(sqlite3_vtab
*);
897 sqlite3_vtab
*pVtab
= aVTrans
[i
]->pVtab
;
898 if( pVtab
&& (x
= pVtab
->pModule
->xSync
)!=0 ){
900 sqlite3VtabImportErrmsg(p
, pVtab
);
903 db
->aVTrans
= aVTrans
;
908 ** Invoke the xRollback method of all virtual tables in the
909 ** sqlite3.aVTrans array. Then clear the array itself.
911 int sqlite3VtabRollback(sqlite3
*db
){
912 callFinaliser(db
, offsetof(sqlite3_module
,xRollback
));
917 ** Invoke the xCommit method of all virtual tables in the
918 ** sqlite3.aVTrans array. Then clear the array itself.
920 int sqlite3VtabCommit(sqlite3
*db
){
921 callFinaliser(db
, offsetof(sqlite3_module
,xCommit
));
926 ** If the virtual table pVtab supports the transaction interface
927 ** (xBegin/xRollback/xCommit and optionally xSync) and a transaction is
928 ** not currently open, invoke the xBegin method now.
930 ** If the xBegin call is successful, place the sqlite3_vtab pointer
931 ** in the sqlite3.aVTrans array.
933 int sqlite3VtabBegin(sqlite3
*db
, VTable
*pVTab
){
935 const sqlite3_module
*pModule
;
937 /* Special case: If db->aVTrans is NULL and db->nVTrans is greater
938 ** than zero, then this function is being called from within a
939 ** virtual module xSync() callback. It is illegal to write to
940 ** virtual module tables in this case, so return SQLITE_LOCKED.
942 if( sqlite3VtabInSync(db
) ){
943 return SQLITE_LOCKED
;
948 pModule
= pVTab
->pVtab
->pModule
;
950 if( pModule
->xBegin
){
953 /* If pVtab is already in the aVTrans array, return early */
954 for(i
=0; i
<db
->nVTrans
; i
++){
955 if( db
->aVTrans
[i
]==pVTab
){
960 /* Invoke the xBegin method. If successful, add the vtab to the
961 ** sqlite3.aVTrans[] array. */
964 rc
= pModule
->xBegin(pVTab
->pVtab
);
966 int iSvpt
= db
->nStatement
+ db
->nSavepoint
;
967 addToVTrans(db
, pVTab
);
968 if( iSvpt
&& pModule
->xSavepoint
){
969 pVTab
->iSavepoint
= iSvpt
;
970 rc
= pModule
->xSavepoint(pVTab
->pVtab
, iSvpt
-1);
979 ** Invoke either the xSavepoint, xRollbackTo or xRelease method of all
980 ** virtual tables that currently have an open transaction. Pass iSavepoint
981 ** as the second argument to the virtual table method invoked.
983 ** If op is SAVEPOINT_BEGIN, the xSavepoint method is invoked. If it is
984 ** SAVEPOINT_ROLLBACK, the xRollbackTo method. Otherwise, if op is
985 ** SAVEPOINT_RELEASE, then the xRelease method of each virtual table with
986 ** an open transaction is invoked.
988 ** If any virtual table method returns an error code other than SQLITE_OK,
989 ** processing is abandoned and the error returned to the caller of this
990 ** function immediately. If all calls to virtual table methods are successful,
991 ** SQLITE_OK is returned.
993 int sqlite3VtabSavepoint(sqlite3
*db
, int op
, int iSavepoint
){
996 assert( op
==SAVEPOINT_RELEASE
||op
==SAVEPOINT_ROLLBACK
||op
==SAVEPOINT_BEGIN
);
997 assert( iSavepoint
>=-1 );
1000 for(i
=0; rc
==SQLITE_OK
&& i
<db
->nVTrans
; i
++){
1001 VTable
*pVTab
= db
->aVTrans
[i
];
1002 const sqlite3_module
*pMod
= pVTab
->pMod
->pModule
;
1003 if( pVTab
->pVtab
&& pMod
->iVersion
>=2 ){
1004 int (*xMethod
)(sqlite3_vtab
*, int);
1006 case SAVEPOINT_BEGIN
:
1007 xMethod
= pMod
->xSavepoint
;
1008 pVTab
->iSavepoint
= iSavepoint
+1;
1010 case SAVEPOINT_ROLLBACK
:
1011 xMethod
= pMod
->xRollbackTo
;
1014 xMethod
= pMod
->xRelease
;
1017 if( xMethod
&& pVTab
->iSavepoint
>iSavepoint
){
1018 rc
= xMethod(pVTab
->pVtab
, iSavepoint
);
1027 ** The first parameter (pDef) is a function implementation. The
1028 ** second parameter (pExpr) is the first argument to this function.
1029 ** If pExpr is a column in a virtual table, then let the virtual
1030 ** table implementation have an opportunity to overload the function.
1032 ** This routine is used to allow virtual table implementations to
1033 ** overload MATCH, LIKE, GLOB, and REGEXP operators.
1035 ** Return either the pDef argument (indicating no change) or a
1036 ** new FuncDef structure that is marked as ephemeral using the
1037 ** SQLITE_FUNC_EPHEM flag.
1039 FuncDef
*sqlite3VtabOverloadFunction(
1040 sqlite3
*db
, /* Database connection for reporting malloc problems */
1041 FuncDef
*pDef
, /* Function to possibly overload */
1042 int nArg
, /* Number of arguments to the function */
1043 Expr
*pExpr
/* First argument to the function */
1046 sqlite3_vtab
*pVtab
;
1047 sqlite3_module
*pMod
;
1048 void (*xSFunc
)(sqlite3_context
*,int,sqlite3_value
**) = 0;
1056 /* Check to see the left operand is a column in a virtual table */
1057 if( NEVER(pExpr
==0) ) return pDef
;
1058 if( pExpr
->op
!=TK_COLUMN
) return pDef
;
1060 if( pTab
==0 ) return pDef
;
1061 if( !IsVirtual(pTab
) ) return pDef
;
1062 pVtab
= sqlite3GetVTable(db
, pTab
)->pVtab
;
1064 assert( pVtab
->pModule
!=0 );
1065 pMod
= (sqlite3_module
*)pVtab
->pModule
;
1066 if( pMod
->xFindFunction
==0 ) return pDef
;
1068 /* Call the xFindFunction method on the virtual table implementation
1069 ** to see if the implementation wants to overload this function
1071 zLowerName
= sqlite3DbStrDup(db
, pDef
->zName
);
1073 for(z
=(unsigned char*)zLowerName
; *z
; z
++){
1074 *z
= sqlite3UpperToLower
[*z
];
1076 rc
= pMod
->xFindFunction(pVtab
, nArg
, zLowerName
, &xSFunc
, &pArg
);
1077 sqlite3DbFree(db
, zLowerName
);
1083 /* Create a new ephemeral function definition for the overloaded
1085 pNew
= sqlite3DbMallocZero(db
, sizeof(*pNew
)
1086 + sqlite3Strlen30(pDef
->zName
) + 1);
1091 pNew
->zName
= (const char*)&pNew
[1];
1092 memcpy((char*)&pNew
[1], pDef
->zName
, sqlite3Strlen30(pDef
->zName
)+1);
1093 pNew
->xSFunc
= xSFunc
;
1094 pNew
->pUserData
= pArg
;
1095 pNew
->funcFlags
|= SQLITE_FUNC_EPHEM
;
1100 ** Make sure virtual table pTab is contained in the pParse->apVirtualLock[]
1101 ** array so that an OP_VBegin will get generated for it. Add pTab to the
1102 ** array if it is missing. If pTab is already in the array, this routine
1105 void sqlite3VtabMakeWritable(Parse
*pParse
, Table
*pTab
){
1106 Parse
*pToplevel
= sqlite3ParseToplevel(pParse
);
1110 assert( IsVirtual(pTab
) );
1111 for(i
=0; i
<pToplevel
->nVtabLock
; i
++){
1112 if( pTab
==pToplevel
->apVtabLock
[i
] ) return;
1114 n
= (pToplevel
->nVtabLock
+1)*sizeof(pToplevel
->apVtabLock
[0]);
1115 apVtabLock
= sqlite3_realloc64(pToplevel
->apVtabLock
, n
);
1117 pToplevel
->apVtabLock
= apVtabLock
;
1118 pToplevel
->apVtabLock
[pToplevel
->nVtabLock
++] = pTab
;
1120 sqlite3OomFault(pToplevel
->db
);
1125 ** Check to see if virtual table module pMod can be have an eponymous
1126 ** virtual table instance. If it can, create one if one does not already
1127 ** exist. Return non-zero if the eponymous virtual table instance exists
1128 ** when this routine returns, and return zero if it does not exist.
1130 ** An eponymous virtual table instance is one that is named after its
1131 ** module, and more importantly, does not require a CREATE VIRTUAL TABLE
1132 ** statement in order to come into existance. Eponymous virtual table
1133 ** instances always exist. They cannot be DROP-ed.
1135 ** Any virtual table module for which xConnect and xCreate are the same
1136 ** method can have an eponymous virtual table instance.
1138 int sqlite3VtabEponymousTableInit(Parse
*pParse
, Module
*pMod
){
1139 const sqlite3_module
*pModule
= pMod
->pModule
;
1143 sqlite3
*db
= pParse
->db
;
1144 if( pMod
->pEpoTab
) return 1;
1145 if( pModule
->xCreate
!=0 && pModule
->xCreate
!=pModule
->xConnect
) return 0;
1146 pTab
= sqlite3DbMallocZero(db
, sizeof(Table
));
1147 if( pTab
==0 ) return 0;
1148 pTab
->zName
= sqlite3DbStrDup(db
, pMod
->zName
);
1149 if( pTab
->zName
==0 ){
1150 sqlite3DbFree(db
, pTab
);
1153 pMod
->pEpoTab
= pTab
;
1155 pTab
->pSchema
= db
->aDb
[0].pSchema
;
1156 assert( pTab
->nModuleArg
==0 );
1158 addModuleArgument(db
, pTab
, sqlite3DbStrDup(db
, pTab
->zName
));
1159 addModuleArgument(db
, pTab
, 0);
1160 addModuleArgument(db
, pTab
, sqlite3DbStrDup(db
, pTab
->zName
));
1161 rc
= vtabCallConstructor(db
, pTab
, pMod
, pModule
->xConnect
, &zErr
);
1163 sqlite3ErrorMsg(pParse
, "%s", zErr
);
1164 sqlite3DbFree(db
, zErr
);
1165 sqlite3VtabEponymousTableClear(db
, pMod
);
1172 ** Erase the eponymous virtual table instance associated with
1173 ** virtual table module pMod, if it exists.
1175 void sqlite3VtabEponymousTableClear(sqlite3
*db
, Module
*pMod
){
1176 Table
*pTab
= pMod
->pEpoTab
;
1178 /* Mark the table as Ephemeral prior to deleting it, so that the
1179 ** sqlite3DeleteTable() routine will know that it is not stored in
1181 pTab
->tabFlags
|= TF_Ephemeral
;
1182 sqlite3DeleteTable(db
, pTab
);
1188 ** Return the ON CONFLICT resolution mode in effect for the virtual
1189 ** table update operation currently in progress.
1191 ** The results of this routine are undefined unless it is called from
1192 ** within an xUpdate method.
1194 int sqlite3_vtab_on_conflict(sqlite3
*db
){
1195 static const unsigned char aMap
[] = {
1196 SQLITE_ROLLBACK
, SQLITE_ABORT
, SQLITE_FAIL
, SQLITE_IGNORE
, SQLITE_REPLACE
1198 #ifdef SQLITE_ENABLE_API_ARMOR
1199 if( !sqlite3SafetyCheckOk(db
) ) return SQLITE_MISUSE_BKPT
;
1201 assert( OE_Rollback
==1 && OE_Abort
==2 && OE_Fail
==3 );
1202 assert( OE_Ignore
==4 && OE_Replace
==5 );
1203 assert( db
->vtabOnConflict
>=1 && db
->vtabOnConflict
<=5 );
1204 return (int)aMap
[db
->vtabOnConflict
-1];
1208 ** Call from within the xCreate() or xConnect() methods to provide
1209 ** the SQLite core with additional information about the behavior
1210 ** of the virtual table being implemented.
1212 int sqlite3_vtab_config(sqlite3
*db
, int op
, ...){
1216 #ifdef SQLITE_ENABLE_API_ARMOR
1217 if( !sqlite3SafetyCheckOk(db
) ) return SQLITE_MISUSE_BKPT
;
1219 sqlite3_mutex_enter(db
->mutex
);
1222 case SQLITE_VTAB_CONSTRAINT_SUPPORT
: {
1223 VtabCtx
*p
= db
->pVtabCtx
;
1225 rc
= SQLITE_MISUSE_BKPT
;
1227 assert( p
->pTab
==0 || IsVirtual(p
->pTab
) );
1228 p
->pVTable
->bConstraint
= (u8
)va_arg(ap
, int);
1233 rc
= SQLITE_MISUSE_BKPT
;
1238 if( rc
!=SQLITE_OK
) sqlite3Error(db
, rc
);
1239 sqlite3_mutex_leave(db
->mutex
);
1243 #endif /* SQLITE_OMIT_VIRTUALTABLE */