src/vdbeblob.c

   1 /*
   2 ** 2007 May 1
   3 **
   4 ** The author disclaims copyright to this source code.  In place of
   5 ** a legal notice, here is a blessing:
   6 **
   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.
  10 **
  11 *************************************************************************
  12 **
  13 ** This file contains code used to implement incremental BLOB I/O.
  14 */
  15
  16 #include "sqliteInt.h"
  17 #include "vdbeInt.h"
  18
  19 #ifndef SQLITE_OMIT_INCRBLOB
  20
  21 /*
  22 ** Valid sqlite3_blob* handles point to Incrblob structures.
  23 */
  24 typedef struct Incrblob Incrblob;
  25 struct Incrblob {
  26   int nByte;              /* Size of open blob, in bytes */
  27   int iOffset;            /* Byte offset of blob in cursor data */
  28   u16 iCol;               /* Table column this handle is open on */
  29   BtCursor *pCsr;         /* Cursor pointing at blob row */
  30   sqlite3_stmt *pStmt;    /* Statement holding cursor open */
  31   sqlite3 *db;            /* The associated database */
  32   char *zDb;              /* Database name */
  33   Table *pTab;            /* Table object */
  34 };
  35
  36
  37 /*
  38 ** This function is used by both blob_open() and blob_reopen(). It seeks
  39 ** the b-tree cursor associated with blob handle p to point to row iRow.
  40 ** If successful, SQLITE_OK is returned and subsequent calls to
  41 ** sqlite3_blob_read() or sqlite3_blob_write() access the specified row.
  42 **
  43 ** If an error occurs, or if the specified row does not exist or does not
  44 ** contain a value of type TEXT or BLOB in the column nominated when the
  45 ** blob handle was opened, then an error code is returned and *pzErr may
  46 ** be set to point to a buffer containing an error message. It is the
  47 ** responsibility of the caller to free the error message buffer using
  48 ** sqlite3DbFree().
  49 **
  50 ** If an error does occur, then the b-tree cursor is closed. All subsequent
  51 ** calls to sqlite3_blob_read(), blob_write() or blob_reopen() will
  52 ** immediately return SQLITE_ABORT.
  53 */
  54 static int blobSeekToRow(Incrblob *p, sqlite3_int64 iRow, char **pzErr){
  55   int rc;                         /* Error code */
  56   char *zErr = 0;                 /* Error message */
  57   Vdbe *v = (Vdbe *)p->pStmt;
  58
  59   /* Set the value of register r[1] in the SQL statement to integer iRow.
  60   ** This is done directly as a performance optimization
  61   */
  62   v->aMem[1].flags = MEM_Int;
  63   v->aMem[1].u.i = iRow;
  64
  65   /* If the statement has been run before (and is paused at the OP_ResultRow)
  66   ** then back it up to the point where it does the OP_NotExists.  This could
  67   ** have been down with an extra OP_Goto, but simply setting the program
  68   ** counter is faster. */
  69   if( v->pc>4 ){
  70     v->pc = 4;
  71     assert( v->aOp[v->pc].opcode==OP_NotExists );
  72     rc = sqlite3VdbeExec(v);
  73   }else{
  74     rc = sqlite3_step(p->pStmt);
  75   }
  76   if( rc==SQLITE_ROW ){
  77     VdbeCursor *pC = v->apCsr[0];
  78     u32 type;
  79     assert( pC!=0 );
  80     assert( pC->eCurType==CURTYPE_BTREE );
  81     type = pC->nHdrParsed>p->iCol ? pC->aType[p->iCol] : 0;
  82     testcase( pC->nHdrParsed==p->iCol );
  83     testcase( pC->nHdrParsed==p->iCol+1 );
  84     if( type<12 ){
  85       zErr = sqlite3MPrintf(p->db, "cannot open value of type %s",
  86           type==0?"null": type==7?"real": "integer"
  87       );
  88       rc = SQLITE_ERROR;
  89       sqlite3_finalize(p->pStmt);
  90       p->pStmt = 0;
  91     }else{
  92       p->iOffset = pC->aType[p->iCol + pC->nField];
  93       p->nByte = sqlite3VdbeSerialTypeLen(type);
  94       p->pCsr =  pC->uc.pCursor;
  95       sqlite3BtreeIncrblobCursor(p->pCsr);
  96     }
  97   }
  98
  99   if( rc==SQLITE_ROW ){
 100     rc = SQLITE_OK;
 101   }else if( p->pStmt ){
 102     rc = sqlite3_finalize(p->pStmt);
 103     p->pStmt = 0;
 104     if( rc==SQLITE_OK ){
 105       zErr = sqlite3MPrintf(p->db, "no such rowid: %lld", iRow);
 106       rc = SQLITE_ERROR;
 107     }else{
 108       zErr = sqlite3MPrintf(p->db, "%s", sqlite3_errmsg(p->db));
 109     }
 110   }
 111
 112   assert( rc!=SQLITE_OK || zErr==0 );
 113   assert( rc!=SQLITE_ROW && rc!=SQLITE_DONE );
 114
 115   *pzErr = zErr;
 116   return rc;
 117 }
 118
 119 /*
 120 ** Open a blob handle.
 121 */
 122 int sqlite3_blob_open(
 123   sqlite3* db,            /* The database connection */
 124   const char *zDb,        /* The attached database containing the blob */
 125   const char *zTable,     /* The table containing the blob */
 126   const char *zColumn,    /* The column containing the blob */
 127   sqlite_int64 iRow,      /* The row containing the glob */
 128   int wrFlag,             /* True -> read/write access, false -> read-only */
 129   sqlite3_blob **ppBlob   /* Handle for accessing the blob returned here */
 130 ){
 131   int nAttempt = 0;
 132   int iCol;               /* Index of zColumn in row-record */
 133   int rc = SQLITE_OK;
 134   char *zErr = 0;
 135   Table *pTab;
 136   Incrblob *pBlob = 0;
 137   Parse sParse;
 138
 139 #ifdef SQLITE_ENABLE_API_ARMOR
 140   if( ppBlob==0 ){
 141     return SQLITE_MISUSE_BKPT;
 142   }
 143 #endif
 144   *ppBlob = 0;
 145 #ifdef SQLITE_ENABLE_API_ARMOR
 146   if( !sqlite3SafetyCheckOk(db) || zTable==0 ){
 147     return SQLITE_MISUSE_BKPT;
 148   }
 149 #endif
 150   wrFlag = !!wrFlag;                /* wrFlag = (wrFlag ? 1 : 0); */
 151
 152   sqlite3_mutex_enter(db->mutex);
 153
 154   pBlob = (Incrblob *)sqlite3DbMallocZero(db, sizeof(Incrblob));
 155   while(1){
 156     sqlite3ParseObjectInit(&sParse,db);
 157     if( !pBlob ) goto blob_open_out;
 158     sqlite3DbFree(db, zErr);
 159     zErr = 0;
 160
 161     sqlite3BtreeEnterAll(db);
 162     pTab = sqlite3LocateTable(&sParse, 0, zTable, zDb);
 163     if( pTab && IsVirtual(pTab) ){
 164       pTab = 0;
 165       sqlite3ErrorMsg(&sParse, "cannot open virtual table: %s", zTable);
 166     }
 167     if( pTab && !HasRowid(pTab) ){
 168       pTab = 0;
 169       sqlite3ErrorMsg(&sParse, "cannot open table without rowid: %s", zTable);
 170     }
 171 #ifndef SQLITE_OMIT_VIEW
 172     if( pTab && IsView(pTab) ){
 173       pTab = 0;
 174       sqlite3ErrorMsg(&sParse, "cannot open view: %s", zTable);
 175     }
 176 #endif
 177     if( !pTab ){
 178       if( sParse.zErrMsg ){
 179         sqlite3DbFree(db, zErr);
 180         zErr = sParse.zErrMsg;
 181         sParse.zErrMsg = 0;
 182       }
 183       rc = SQLITE_ERROR;
 184       sqlite3BtreeLeaveAll(db);
 185       goto blob_open_out;
 186     }
 187     pBlob->pTab = pTab;
 188     pBlob->zDb = db->aDb[sqlite3SchemaToIndex(db, pTab->pSchema)].zDbSName;
 189
 190     /* Now search pTab for the exact column. */
 191     for(iCol=0; iCol<pTab->nCol; iCol++) {
 192       if( sqlite3StrICmp(pTab->aCol[iCol].zCnName, zColumn)==0 ){
 193         break;
 194       }
 195     }
 196     if( iCol==pTab->nCol ){
 197       sqlite3DbFree(db, zErr);
 198       zErr = sqlite3MPrintf(db, "no such column: \"%s\"", zColumn);
 199       rc = SQLITE_ERROR;
 200       sqlite3BtreeLeaveAll(db);
 201       goto blob_open_out;
 202     }
 203
 204     /* If the value is being opened for writing, check that the
 205     ** column is not indexed, and that it is not part of a foreign key.
 206     */
 207     if( wrFlag ){
 208       const char *zFault = 0;
 209       Index *pIdx;
 210 #ifndef SQLITE_OMIT_FOREIGN_KEY
 211       if( db->flags&SQLITE_ForeignKeys ){
 212         /* Check that the column is not part of an FK child key definition. It
 213         ** is not necessary to check if it is part of a parent key, as parent
 214         ** key columns must be indexed. The check below will pick up this
 215         ** case.  */
 216         FKey *pFKey;
 217         assert( IsOrdinaryTable(pTab) );
 218         for(pFKey=pTab->u.tab.pFKey; pFKey; pFKey=pFKey->pNextFrom){
 219           int j;
 220           for(j=0; j<pFKey->nCol; j++){
 221             if( pFKey->aCol[j].iFrom==iCol ){
 222               zFault = "foreign key";
 223             }
 224           }
 225         }
 226       }
 227 #endif
 228       for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
 229         int j;
 230         for(j=0; j<pIdx->nKeyCol; j++){
 231           /* FIXME: Be smarter about indexes that use expressions */
 232           if( pIdx->aiColumn[j]==iCol || pIdx->aiColumn[j]==XN_EXPR ){
 233             zFault = "indexed";
 234           }
 235         }
 236       }
 237       if( zFault ){
 238         sqlite3DbFree(db, zErr);
 239         zErr = sqlite3MPrintf(db, "cannot open %s column for writing", zFault);
 240         rc = SQLITE_ERROR;
 241         sqlite3BtreeLeaveAll(db);
 242         goto blob_open_out;
 243       }
 244     }
 245
 246     pBlob->pStmt = (sqlite3_stmt *)sqlite3VdbeCreate(&sParse);
 247     assert( pBlob->pStmt || db->mallocFailed );
 248     if( pBlob->pStmt ){
 249
 250       /* This VDBE program seeks a btree cursor to the identified
 251       ** db/table/row entry. The reason for using a vdbe program instead
 252       ** of writing code to use the b-tree layer directly is that the
 253       ** vdbe program will take advantage of the various transaction,
 254       ** locking and error handling infrastructure built into the vdbe.
 255       **
 256       ** After seeking the cursor, the vdbe executes an OP_ResultRow.
 257       ** Code external to the Vdbe then "borrows" the b-tree cursor and
 258       ** uses it to implement the blob_read(), blob_write() and
 259       ** blob_bytes() functions.
 260       **
 261       ** The sqlite3_blob_close() function finalizes the vdbe program,
 262       ** which closes the b-tree cursor and (possibly) commits the
 263       ** transaction.
 264       */
 265       static const int iLn = VDBE_OFFSET_LINENO(2);
 266       static const VdbeOpList openBlob[] = {
 267         {OP_TableLock,      0, 0, 0},  /* 0: Acquire a read or write lock */
 268         {OP_OpenRead,       0, 0, 0},  /* 1: Open a cursor */
 269         /* blobSeekToRow() will initialize r[1] to the desired rowid */
 270         {OP_NotExists,      0, 5, 1},  /* 2: Seek the cursor to rowid=r[1] */
 271         {OP_Column,         0, 0, 1},  /* 3  */
 272         {OP_ResultRow,      1, 0, 0},  /* 4  */
 273         {OP_Halt,           0, 0, 0},  /* 5  */
 274       };
 275       Vdbe *v = (Vdbe *)pBlob->pStmt;
 276       int iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
 277       VdbeOp *aOp;
 278
 279       sqlite3VdbeAddOp4Int(v, OP_Transaction, iDb, wrFlag,
 280                            pTab->pSchema->schema_cookie,
 281                            pTab->pSchema->iGeneration);
 282       sqlite3VdbeChangeP5(v, 1);
 283       assert( sqlite3VdbeCurrentAddr(v)==2 || db->mallocFailed );
 284       aOp = sqlite3VdbeAddOpList(v, ArraySize(openBlob), openBlob, iLn);
 285
 286       /* Make sure a mutex is held on the table to be accessed */
 287       sqlite3VdbeUsesBtree(v, iDb);
 288
 289       if( db->mallocFailed==0 ){
 290         assert( aOp!=0 );
 291         /* Configure the OP_TableLock instruction */
 292 #ifdef SQLITE_OMIT_SHARED_CACHE
 293         aOp[0].opcode = OP_Noop;
 294 #else
 295         aOp[0].p1 = iDb;
 296         aOp[0].p2 = pTab->tnum;
 297         aOp[0].p3 = wrFlag;
 298         sqlite3VdbeChangeP4(v, 2, pTab->zName, P4_TRANSIENT);
 299       }
 300       if( db->mallocFailed==0 ){
 301 #endif
 302
 303         /* Remove either the OP_OpenWrite or OpenRead. Set the P2
 304         ** parameter of the other to pTab->tnum.  */
 305         if( wrFlag ) aOp[1].opcode = OP_OpenWrite;
 306         aOp[1].p2 = pTab->tnum;
 307         aOp[1].p3 = iDb;
 308
 309         /* Configure the number of columns. Configure the cursor to
 310         ** think that the table has one more column than it really
 311         ** does. An OP_Column to retrieve this imaginary column will
 312         ** always return an SQL NULL. This is useful because it means
 313         ** we can invoke OP_Column to fill in the vdbe cursors type
 314         ** and offset cache without causing any IO.
 315         */
 316         aOp[1].p4type = P4_INT32;
 317         aOp[1].p4.i = pTab->nCol+1;
 318         aOp[3].p2 = pTab->nCol;
 319
 320         sParse.nVar = 0;
 321         sParse.nMem = 1;
 322         sParse.nTab = 1;
 323         sqlite3VdbeMakeReady(v, &sParse);
 324       }
 325     }
 326
 327     pBlob->iCol = iCol;
 328     pBlob->db = db;
 329     sqlite3BtreeLeaveAll(db);
 330     if( db->mallocFailed ){
 331       goto blob_open_out;
 332     }
 333     rc = blobSeekToRow(pBlob, iRow, &zErr);
 334     if( (++nAttempt)>=SQLITE_MAX_SCHEMA_RETRY || rc!=SQLITE_SCHEMA ) break;
 335     sqlite3ParseObjectReset(&sParse);
 336   }
 337
 338 blob_open_out:
 339   if( rc==SQLITE_OK && db->mallocFailed==0 ){
 340     *ppBlob = (sqlite3_blob *)pBlob;
 341   }else{
 342     if( pBlob && pBlob->pStmt ) sqlite3VdbeFinalize((Vdbe *)pBlob->pStmt);
 343     sqlite3DbFree(db, pBlob);
 344   }
 345   sqlite3ErrorWithMsg(db, rc, (zErr ? "%s" : (char*)0), zErr);
 346   sqlite3DbFree(db, zErr);
 347   sqlite3ParseObjectReset(&sParse);
 348   rc = sqlite3ApiExit(db, rc);
 349   sqlite3_mutex_leave(db->mutex);
 350   return rc;
 351 }
 352
 353 /*
 354 ** Close a blob handle that was previously created using
 355 ** sqlite3_blob_open().
 356 */
 357 int sqlite3_blob_close(sqlite3_blob *pBlob){
 358   Incrblob *p = (Incrblob *)pBlob;
 359   int rc;
 360   sqlite3 *db;
 361
 362   if( p ){
 363     sqlite3_stmt *pStmt = p->pStmt;
 364     db = p->db;
 365     sqlite3_mutex_enter(db->mutex);
 366     sqlite3DbFree(db, p);
 367     sqlite3_mutex_leave(db->mutex);
 368     rc = sqlite3_finalize(pStmt);
 369   }else{
 370     rc = SQLITE_OK;
 371   }
 372   return rc;
 373 }
 374
 375 /*
 376 ** Perform a read or write operation on a blob
 377 */
 378 static int blobReadWrite(
 379   sqlite3_blob *pBlob,
 380   void *z,
 381   int n,
 382   int iOffset,
 383   int (*xCall)(BtCursor*, u32, u32, void*)
 384 ){
 385   int rc;
 386   Incrblob *p = (Incrblob *)pBlob;
 387   Vdbe *v;
 388   sqlite3 *db;
 389
 390   if( p==0 ) return SQLITE_MISUSE_BKPT;
 391   db = p->db;
 392   sqlite3_mutex_enter(db->mutex);
 393   v = (Vdbe*)p->pStmt;
 394
 395   if( n<0 || iOffset<0 || ((sqlite3_int64)iOffset+n)>p->nByte ){
 396     /* Request is out of range. Return a transient error. */
 397     rc = SQLITE_ERROR;
 398   }else if( v==0 ){
 399     /* If there is no statement handle, then the blob-handle has
 400     ** already been invalidated. Return SQLITE_ABORT in this case.
 401     */
 402     rc = SQLITE_ABORT;
 403   }else{
 404     /* Call either BtreeData() or BtreePutData(). If SQLITE_ABORT is
 405     ** returned, clean-up the statement handle.
 406     */
 407     assert( db == v->db );
 408     sqlite3BtreeEnterCursor(p->pCsr);
 409
 410 #ifdef SQLITE_ENABLE_PREUPDATE_HOOK
 411     if( xCall==sqlite3BtreePutData && db->xPreUpdateCallback ){
 412       /* If a pre-update hook is registered and this is a write cursor,
 413       ** invoke it here.
 414       **
 415       ** TODO: The preupdate-hook is passed SQLITE_DELETE, even though this
 416       ** operation should really be an SQLITE_UPDATE. This is probably
 417       ** incorrect, but is convenient because at this point the new.* values
 418       ** are not easily obtainable. And for the sessions module, an
 419       ** SQLITE_UPDATE where the PK columns do not change is handled in the
 420       ** same way as an SQLITE_DELETE (the SQLITE_DELETE code is actually
 421       ** slightly more efficient). Since you cannot write to a PK column
 422       ** using the incremental-blob API, this works. For the sessions module
 423       ** anyhow.
 424       */
 425       sqlite3_int64 iKey;
 426       iKey = sqlite3BtreeIntegerKey(p->pCsr);
 427       assert( v->apCsr[0]!=0 );
 428       assert( v->apCsr[0]->eCurType==CURTYPE_BTREE );
 429       sqlite3VdbePreUpdateHook(
 430           v, v->apCsr[0], SQLITE_DELETE, p->zDb, p->pTab, iKey, -1, p->iCol
 431       );
 432     }
 433 #endif
 434
 435     rc = xCall(p->pCsr, iOffset+p->iOffset, n, z);
 436     sqlite3BtreeLeaveCursor(p->pCsr);
 437     if( rc==SQLITE_ABORT ){
 438       sqlite3VdbeFinalize(v);
 439       p->pStmt = 0;
 440     }else{
 441       v->rc = rc;
 442     }
 443   }
 444   sqlite3Error(db, rc);
 445   rc = sqlite3ApiExit(db, rc);
 446   sqlite3_mutex_leave(db->mutex);
 447   return rc;
 448 }
 449
 450 /*
 451 ** Read data from a blob handle.
 452 */
 453 int sqlite3_blob_read(sqlite3_blob *pBlob, void *z, int n, int iOffset){
 454   return blobReadWrite(pBlob, z, n, iOffset, sqlite3BtreePayloadChecked);
 455 }
 456
 457 /*
 458 ** Write data to a blob handle.
 459 */
 460 int sqlite3_blob_write(sqlite3_blob *pBlob, const void *z, int n, int iOffset){
 461   return blobReadWrite(pBlob, (void *)z, n, iOffset, sqlite3BtreePutData);
 462 }
 463
 464 /*
 465 ** Query a blob handle for the size of the data.
 466 **
 467 ** The Incrblob.nByte field is fixed for the lifetime of the Incrblob
 468 ** so no mutex is required for access.
 469 */
 470 int sqlite3_blob_bytes(sqlite3_blob *pBlob){
 471   Incrblob *p = (Incrblob *)pBlob;
 472   return (p && p->pStmt) ? p->nByte : 0;
 473 }
 474
 475 /*
 476 ** Move an existing blob handle to point to a different row of the same
 477 ** database table.
 478 **
 479 ** If an error occurs, or if the specified row does not exist or does not
 480 ** contain a blob or text value, then an error code is returned and the
 481 ** database handle error code and message set. If this happens, then all
 482 ** subsequent calls to sqlite3_blob_xxx() functions (except blob_close())
 483 ** immediately return SQLITE_ABORT.
 484 */
 485 int sqlite3_blob_reopen(sqlite3_blob *pBlob, sqlite3_int64 iRow){
 486   int rc;
 487   Incrblob *p = (Incrblob *)pBlob;
 488   sqlite3 *db;
 489
 490   if( p==0 ) return SQLITE_MISUSE_BKPT;
 491   db = p->db;
 492   sqlite3_mutex_enter(db->mutex);
 493
 494   if( p->pStmt==0 ){
 495     /* If there is no statement handle, then the blob-handle has
 496     ** already been invalidated. Return SQLITE_ABORT in this case.
 497     */
 498     rc = SQLITE_ABORT;
 499   }else{
 500     char *zErr;
 501     ((Vdbe*)p->pStmt)->rc = SQLITE_OK;
 502     rc = blobSeekToRow(p, iRow, &zErr);
 503     if( rc!=SQLITE_OK ){
 504       sqlite3ErrorWithMsg(db, rc, (zErr ? "%s" : (char*)0), zErr);
 505       sqlite3DbFree(db, zErr);
 506     }
 507     assert( rc!=SQLITE_SCHEMA );
 508   }
 509
 510   rc = sqlite3ApiExit(db, rc);
 511   assert( rc==SQLITE_OK || p->pStmt==0 );
 512   sqlite3_mutex_leave(db->mutex);
 513   return rc;
 514 }
 515
 516 #endif /* #ifndef SQLITE_OMIT_INCRBLOB */