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