1 // Copyright (c) 2012 The Chromium Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef SQL_CONNECTION_H_ 6 #define SQL_CONNECTION_H_ 7 8 #include <map> 9 #include <set> 10 #include <string> 11 #include <vector> 12 13 #include "base/basictypes.h" 14 #include "base/callback.h" 15 #include "base/compiler_specific.h" 16 #include "base/memory/ref_counted.h" 17 #include "base/memory/scoped_ptr.h" 18 #include "base/threading/thread_restrictions.h" 19 #include "base/time/time.h" 20 #include "sql/sql_export.h" 21 22 struct sqlite3; 23 struct sqlite3_stmt; 24 25 namespace base { 26 class FilePath; 27 } 28 29 namespace sql { 30 31 class Recovery; 32 class Statement; 33 34 // Uniquely identifies a statement. There are two modes of operation: 35 // 36 // - In the most common mode, you will use the source file and line number to 37 // identify your statement. This is a convienient way to get uniqueness for 38 // a statement that is only used in one place. Use the SQL_FROM_HERE macro 39 // to generate a StatementID. 40 // 41 // - In the "custom" mode you may use the statement from different places or 42 // need to manage it yourself for whatever reason. In this case, you should 43 // make up your own unique name and pass it to the StatementID. This name 44 // must be a static string, since this object only deals with pointers and 45 // assumes the underlying string doesn't change or get deleted. 46 // 47 // This object is copyable and assignable using the compiler-generated 48 // operator= and copy constructor. 49 class StatementID { 50 public: 51 // Creates a uniquely named statement with the given file ane line number. 52 // Normally you will use SQL_FROM_HERE instead of calling yourself. 53 StatementID(const char* file, int line) 54 : number_(line), 55 str_(file) { 56 } 57 58 // Creates a uniquely named statement with the given user-defined name. 59 explicit StatementID(const char* unique_name) 60 : number_(-1), 61 str_(unique_name) { 62 } 63 64 // This constructor is unimplemented and will generate a linker error if 65 // called. It is intended to try to catch people dynamically generating 66 // a statement name that will be deallocated and will cause a crash later. 67 // All strings must be static and unchanging! 68 explicit StatementID(const std::string& dont_ever_do_this); 69 70 // We need this to insert into our map. 71 bool operator<(const StatementID& other) const; 72 73 private: 74 int number_; 75 const char* str_; 76 }; 77 78 #define SQL_FROM_HERE sql::StatementID(__FILE__, __LINE__) 79 80 class Connection; 81 82 class SQL_EXPORT Connection { 83 private: 84 class StatementRef; // Forward declaration, see real one below. 85 86 public: 87 // The database is opened by calling Open[InMemory](). Any uncommitted 88 // transactions will be rolled back when this object is deleted. 89 Connection(); 90 ~Connection(); 91 92 // Pre-init configuration ---------------------------------------------------- 93 94 // Sets the page size that will be used when creating a new database. This 95 // must be called before Init(), and will only have an effect on new 96 // databases. 97 // 98 // From sqlite.org: "The page size must be a power of two greater than or 99 // equal to 512 and less than or equal to SQLITE_MAX_PAGE_SIZE. The maximum 100 // value for SQLITE_MAX_PAGE_SIZE is 32768." 101 void set_page_size(int page_size) { page_size_ = page_size; } 102 103 // Sets the number of pages that will be cached in memory by sqlite. The 104 // total cache size in bytes will be page_size * cache_size. This must be 105 // called before Open() to have an effect. 106 void set_cache_size(int cache_size) { cache_size_ = cache_size; } 107 108 // Call to put the database in exclusive locking mode. There is no "back to 109 // normal" flag because of some additional requirements sqlite puts on this 110 // transaition (requires another access to the DB) and because we don't 111 // actually need it. 112 // 113 // Exclusive mode means that the database is not unlocked at the end of each 114 // transaction, which means there may be less time spent initializing the 115 // next transaction because it doesn't have to re-aquire locks. 116 // 117 // This must be called before Open() to have an effect. 118 void set_exclusive_locking() { exclusive_locking_ = true; } 119 120 // Call to cause Open() to restrict access permissions of the 121 // database file to only the owner. 122 // TODO(shess): Currently only supported on OS_POSIX, is a noop on 123 // other platforms. 124 void set_restrict_to_user() { restrict_to_user_ = true; } 125 126 // Set an error-handling callback. On errors, the error number (and 127 // statement, if available) will be passed to the callback. 128 // 129 // If no callback is set, the default action is to crash in debug 130 // mode or return failure in release mode. 131 typedef base::Callback<void(int, Statement*)> ErrorCallback; 132 void set_error_callback(const ErrorCallback& callback) { 133 error_callback_ = callback; 134 } 135 bool has_error_callback() const { 136 return !error_callback_.is_null(); 137 } 138 void reset_error_callback() { 139 error_callback_.Reset(); 140 } 141 142 // Set this tag to enable additional connection-type histogramming 143 // for SQLite error codes and database version numbers. 144 void set_histogram_tag(const std::string& tag) { 145 histogram_tag_ = tag; 146 } 147 148 // Record a sparse UMA histogram sample under 149 // |name|+"."+|histogram_tag_|. If |histogram_tag_| is empty, no 150 // histogram is recorded. 151 void AddTaggedHistogram(const std::string& name, size_t sample) const; 152 153 // Run "PRAGMA integrity_check" and post each line of results into 154 // |messages|. Returns the success of running the statement - per 155 // the SQLite documentation, if no errors are found the call should 156 // succeed, and a single value "ok" should be in messages. 157 bool IntegrityCheck(std::vector<std::string>* messages); 158 159 // Initialization ------------------------------------------------------------ 160 161 // Initializes the SQL connection for the given file, returning true if the 162 // file could be opened. You can call this or OpenInMemory. 163 bool Open(const base::FilePath& path) WARN_UNUSED_RESULT; 164 165 // Initializes the SQL connection for a temporary in-memory database. There 166 // will be no associated file on disk, and the initial database will be 167 // empty. You can call this or Open. 168 bool OpenInMemory() WARN_UNUSED_RESULT; 169 170 // Create a temporary on-disk database. The database will be 171 // deleted after close. This kind of database is similar to 172 // OpenInMemory() for small databases, but can page to disk if the 173 // database becomes large. 174 bool OpenTemporary() WARN_UNUSED_RESULT; 175 176 // Returns true if the database has been successfully opened. 177 bool is_open() const { return !!db_; } 178 179 // Closes the database. This is automatically performed on destruction for 180 // you, but this allows you to close the database early. You must not call 181 // any other functions after closing it. It is permissable to call Close on 182 // an uninitialized or already-closed database. 183 void Close(); 184 185 // Pre-loads the first <cache-size> pages into the cache from the file. 186 // If you expect to soon use a substantial portion of the database, this 187 // is much more efficient than allowing the pages to be populated organically 188 // since there is no per-page hard drive seeking. If the file is larger than 189 // the cache, the last part that doesn't fit in the cache will be brought in 190 // organically. 191 // 192 // This function assumes your class is using a meta table on the current 193 // database, as it openes a transaction on the meta table to force the 194 // database to be initialized. You should feel free to initialize the meta 195 // table after calling preload since the meta table will already be in the 196 // database if it exists, and if it doesn't exist, the database won't 197 // generally exist either. 198 void Preload(); 199 200 // Try to trim the cache memory used by the database. If |aggressively| is 201 // true, this function will try to free all of the cache memory it can. If 202 // |aggressively| is false, this function will try to cut cache memory 203 // usage by half. 204 void TrimMemory(bool aggressively); 205 206 // Raze the database to the ground. This approximates creating a 207 // fresh database from scratch, within the constraints of SQLite's 208 // locking protocol (locks and open handles can make doing this with 209 // filesystem operations problematic). Returns true if the database 210 // was razed. 211 // 212 // false is returned if the database is locked by some other 213 // process. RazeWithTimeout() may be used if appropriate. 214 // 215 // NOTE(shess): Raze() will DCHECK in the following situations: 216 // - database is not open. 217 // - the connection has a transaction open. 218 // - a SQLite issue occurs which is structural in nature (like the 219 // statements used are broken). 220 // Since Raze() is expected to be called in unexpected situations, 221 // these all return false, since it is unlikely that the caller 222 // could fix them. 223 // 224 // The database's page size is taken from |page_size_|. The 225 // existing database's |auto_vacuum| setting is lost (the 226 // possibility of corruption makes it unreliable to pull it from the 227 // existing database). To re-enable on the empty database requires 228 // running "PRAGMA auto_vacuum = 1;" then "VACUUM". 229 // 230 // NOTE(shess): For Android, SQLITE_DEFAULT_AUTOVACUUM is set to 1, 231 // so Raze() sets auto_vacuum to 1. 232 // 233 // TODO(shess): Raze() needs a connection so cannot clear SQLITE_NOTADB. 234 // TODO(shess): Bake auto_vacuum into Connection's API so it can 235 // just pick up the default. 236 bool Raze(); 237 bool RazeWithTimout(base::TimeDelta timeout); 238 239 // Breaks all outstanding transactions (as initiated by 240 // BeginTransaction()), closes the SQLite database, and poisons the 241 // object so that all future operations against the Connection (or 242 // its Statements) fail safely, without side effects. 243 // 244 // This is intended as an alternative to Close() in error callbacks. 245 // Close() should still be called at some point. 246 void Poison(); 247 248 // Raze() the database and Poison() the handle. Returns the return 249 // value from Raze(). 250 // TODO(shess): Rename to RazeAndPoison(). 251 bool RazeAndClose(); 252 253 // Delete the underlying database files associated with |path|. 254 // This should be used on a database which has no existing 255 // connections. If any other connections are open to the same 256 // database, this could cause odd results or corruption (for 257 // instance if a hot journal is deleted but the associated database 258 // is not). 259 // 260 // Returns true if the database file and associated journals no 261 // longer exist, false otherwise. If the database has never 262 // existed, this will return true. 263 static bool Delete(const base::FilePath& path); 264 265 // Transactions -------------------------------------------------------------- 266 267 // Transaction management. We maintain a virtual transaction stack to emulate 268 // nested transactions since sqlite can't do nested transactions. The 269 // limitation is you can't roll back a sub transaction: if any transaction 270 // fails, all transactions open will also be rolled back. Any nested 271 // transactions after one has rolled back will return fail for Begin(). If 272 // Begin() fails, you must not call Commit or Rollback(). 273 // 274 // Normally you should use sql::Transaction to manage a transaction, which 275 // will scope it to a C++ context. 276 bool BeginTransaction(); 277 void RollbackTransaction(); 278 bool CommitTransaction(); 279 280 // Rollback all outstanding transactions. Use with care, there may 281 // be scoped transactions on the stack. 282 void RollbackAllTransactions(); 283 284 // Returns the current transaction nesting, which will be 0 if there are 285 // no open transactions. 286 int transaction_nesting() const { return transaction_nesting_; } 287 288 // Attached databases--------------------------------------------------------- 289 290 // SQLite supports attaching multiple database files to a single 291 // handle. Attach the database in |other_db_path| to the current 292 // handle under |attachment_point|. |attachment_point| should only 293 // contain characters from [a-zA-Z0-9_]. 294 // 295 // Note that calling attach or detach with an open transaction is an 296 // error. 297 bool AttachDatabase(const base::FilePath& other_db_path, 298 const char* attachment_point); 299 bool DetachDatabase(const char* attachment_point); 300 301 // Statements ---------------------------------------------------------------- 302 303 // Executes the given SQL string, returning true on success. This is 304 // normally used for simple, 1-off statements that don't take any bound 305 // parameters and don't return any data (e.g. CREATE TABLE). 306 // 307 // This will DCHECK if the |sql| contains errors. 308 // 309 // Do not use ignore_result() to ignore all errors. Use 310 // ExecuteAndReturnErrorCode() and ignore only specific errors. 311 bool Execute(const char* sql) WARN_UNUSED_RESULT; 312 313 // Like Execute(), but returns the error code given by SQLite. 314 int ExecuteAndReturnErrorCode(const char* sql) WARN_UNUSED_RESULT; 315 316 // Returns true if we have a statement with the given identifier already 317 // cached. This is normally not necessary to call, but can be useful if the 318 // caller has to dynamically build up SQL to avoid doing so if it's already 319 // cached. 320 bool HasCachedStatement(const StatementID& id) const; 321 322 // Returns a statement for the given SQL using the statement cache. It can 323 // take a nontrivial amount of work to parse and compile a statement, so 324 // keeping commonly-used ones around for future use is important for 325 // performance. 326 // 327 // If the |sql| has an error, an invalid, inert StatementRef is returned (and 328 // the code will crash in debug). The caller must deal with this eventuality, 329 // either by checking validity of the |sql| before calling, by correctly 330 // handling the return of an inert statement, or both. 331 // 332 // The StatementID and the SQL must always correspond to one-another. The 333 // ID is the lookup into the cache, so crazy things will happen if you use 334 // different SQL with the same ID. 335 // 336 // You will normally use the SQL_FROM_HERE macro to generate a statement 337 // ID associated with the current line of code. This gives uniqueness without 338 // you having to manage unique names. See StatementID above for more. 339 // 340 // Example: 341 // sql::Statement stmt(connection_.GetCachedStatement( 342 // SQL_FROM_HERE, "SELECT * FROM foo")); 343 // if (!stmt) 344 // return false; // Error creating statement. 345 scoped_refptr<StatementRef> GetCachedStatement(const StatementID& id, 346 const char* sql); 347 348 // Used to check a |sql| statement for syntactic validity. If the statement is 349 // valid SQL, returns true. 350 bool IsSQLValid(const char* sql); 351 352 // Returns a non-cached statement for the given SQL. Use this for SQL that 353 // is only executed once or only rarely (there is overhead associated with 354 // keeping a statement cached). 355 // 356 // See GetCachedStatement above for examples and error information. 357 scoped_refptr<StatementRef> GetUniqueStatement(const char* sql); 358 359 // Info querying ------------------------------------------------------------- 360 361 // Returns true if the given table exists. 362 bool DoesTableExist(const char* table_name) const; 363 364 // Returns true if the given index exists. 365 bool DoesIndexExist(const char* index_name) const; 366 367 // Returns true if a column with the given name exists in the given table. 368 bool DoesColumnExist(const char* table_name, const char* column_name) const; 369 370 // Returns sqlite's internal ID for the last inserted row. Valid only 371 // immediately after an insert. 372 int64 GetLastInsertRowId() const; 373 374 // Returns sqlite's count of the number of rows modified by the last 375 // statement executed. Will be 0 if no statement has executed or the database 376 // is closed. 377 int GetLastChangeCount() const; 378 379 // Errors -------------------------------------------------------------------- 380 381 // Returns the error code associated with the last sqlite operation. 382 int GetErrorCode() const; 383 384 // Returns the errno associated with GetErrorCode(). See 385 // SQLITE_LAST_ERRNO in SQLite documentation. 386 int GetLastErrno() const; 387 388 // Returns a pointer to a statically allocated string associated with the 389 // last sqlite operation. 390 const char* GetErrorMessage() const; 391 392 private: 393 // For recovery module. 394 friend class Recovery; 395 396 // Allow test-support code to set/reset error ignorer. 397 friend class ScopedErrorIgnorer; 398 399 // Statement accesses StatementRef which we don't want to expose to everybody 400 // (they should go through Statement). 401 friend class Statement; 402 403 // Internal initialize function used by both Init and InitInMemory. The file 404 // name is always 8 bits since we want to use the 8-bit version of 405 // sqlite3_open. The string can also be sqlite's special ":memory:" string. 406 // 407 // |retry_flag| controls retrying the open if the error callback 408 // addressed errors using RazeAndClose(). 409 enum Retry { 410 NO_RETRY = 0, 411 RETRY_ON_POISON 412 }; 413 bool OpenInternal(const std::string& file_name, Retry retry_flag); 414 415 // Internal close function used by Close() and RazeAndClose(). 416 // |forced| indicates that orderly-shutdown checks should not apply. 417 void CloseInternal(bool forced); 418 419 // Check whether the current thread is allowed to make IO calls, but only 420 // if database wasn't open in memory. Function is inlined to be a no-op in 421 // official build. 422 void AssertIOAllowed() { 423 if (!in_memory_) 424 base::ThreadRestrictions::AssertIOAllowed(); 425 } 426 427 // Internal helper for DoesTableExist and DoesIndexExist. 428 bool DoesTableOrIndexExist(const char* name, const char* type) const; 429 430 // Accessors for global error-ignorer, for injecting behavior during tests. 431 // See test/scoped_error_ignorer.h. 432 typedef base::Callback<bool(int)> ErrorIgnorerCallback; 433 static ErrorIgnorerCallback* current_ignorer_cb_; 434 static bool ShouldIgnore(int error); 435 static void SetErrorIgnorer(ErrorIgnorerCallback* ignorer); 436 static void ResetErrorIgnorer(); 437 438 // A StatementRef is a refcounted wrapper around a sqlite statement pointer. 439 // Refcounting allows us to give these statements out to sql::Statement 440 // objects while also optionally maintaining a cache of compiled statements 441 // by just keeping a refptr to these objects. 442 // 443 // A statement ref can be valid, in which case it can be used, or invalid to 444 // indicate that the statement hasn't been created yet, has an error, or has 445 // been destroyed. 446 // 447 // The Connection may revoke a StatementRef in some error cases, so callers 448 // should always check validity before using. 449 class SQL_EXPORT StatementRef : public base::RefCounted<StatementRef> { 450 public: 451 // |connection| is the sql::Connection instance associated with 452 // the statement, and is used for tracking outstanding statements 453 // and for error handling. Set to NULL for invalid or untracked 454 // refs. |stmt| is the actual statement, and should only be NULL 455 // to create an invalid ref. |was_valid| indicates whether the 456 // statement should be considered valid for diagnistic purposes. 457 // |was_valid| can be true for NULL |stmt| if the connection has 458 // been forcibly closed by an error handler. 459 StatementRef(Connection* connection, sqlite3_stmt* stmt, bool was_valid); 460 461 // When true, the statement can be used. 462 bool is_valid() const { return !!stmt_; } 463 464 // When true, the statement is either currently valid, or was 465 // previously valid but the connection was forcibly closed. Used 466 // for diagnostic checks. 467 bool was_valid() const { return was_valid_; } 468 469 // If we've not been linked to a connection, this will be NULL. 470 // TODO(shess): connection_ can be NULL in case of GetUntrackedStatement(), 471 // which prevents Statement::OnError() from forwarding errors. 472 Connection* connection() const { return connection_; } 473 474 // Returns the sqlite statement if any. If the statement is not active, 475 // this will return NULL. 476 sqlite3_stmt* stmt() const { return stmt_; } 477 478 // Destroys the compiled statement and marks it NULL. The statement will 479 // no longer be active. |forced| is used to indicate if orderly-shutdown 480 // checks should apply (see Connection::RazeAndClose()). 481 void Close(bool forced); 482 483 // Check whether the current thread is allowed to make IO calls, but only 484 // if database wasn't open in memory. 485 void AssertIOAllowed() { if (connection_) connection_->AssertIOAllowed(); } 486 487 private: 488 friend class base::RefCounted<StatementRef>; 489 490 ~StatementRef(); 491 492 Connection* connection_; 493 sqlite3_stmt* stmt_; 494 bool was_valid_; 495 496 DISALLOW_COPY_AND_ASSIGN(StatementRef); 497 }; 498 friend class StatementRef; 499 500 // Executes a rollback statement, ignoring all transaction state. Used 501 // internally in the transaction management code. 502 void DoRollback(); 503 504 // Called by a StatementRef when it's being created or destroyed. See 505 // open_statements_ below. 506 void StatementRefCreated(StatementRef* ref); 507 void StatementRefDeleted(StatementRef* ref); 508 509 // Called by Statement objects when an sqlite function returns an error. 510 // The return value is the error code reflected back to client code. 511 int OnSqliteError(int err, Statement* stmt); 512 513 // Like |Execute()|, but retries if the database is locked. 514 bool ExecuteWithTimeout(const char* sql, base::TimeDelta ms_timeout) 515 WARN_UNUSED_RESULT; 516 517 // Internal helper for const functions. Like GetUniqueStatement(), 518 // except the statement is not entered into open_statements_, 519 // allowing this function to be const. Open statements can block 520 // closing the database, so only use in cases where the last ref is 521 // released before close could be called (which should always be the 522 // case for const functions). 523 scoped_refptr<StatementRef> GetUntrackedStatement(const char* sql) const; 524 525 // The actual sqlite database. Will be NULL before Init has been called or if 526 // Init resulted in an error. 527 sqlite3* db_; 528 529 // Parameters we'll configure in sqlite before doing anything else. Zero means 530 // use the default value. 531 int page_size_; 532 int cache_size_; 533 bool exclusive_locking_; 534 bool restrict_to_user_; 535 536 // All cached statements. Keeping a reference to these statements means that 537 // they'll remain active. 538 typedef std::map<StatementID, scoped_refptr<StatementRef> > 539 CachedStatementMap; 540 CachedStatementMap statement_cache_; 541 542 // A list of all StatementRefs we've given out. Each ref must register with 543 // us when it's created or destroyed. This allows us to potentially close 544 // any open statements when we encounter an error. 545 typedef std::set<StatementRef*> StatementRefSet; 546 StatementRefSet open_statements_; 547 548 // Number of currently-nested transactions. 549 int transaction_nesting_; 550 551 // True if any of the currently nested transactions have been rolled back. 552 // When we get to the outermost transaction, this will determine if we do 553 // a rollback instead of a commit. 554 bool needs_rollback_; 555 556 // True if database is open with OpenInMemory(), False if database is open 557 // with Open(). 558 bool in_memory_; 559 560 // |true| if the connection was closed using RazeAndClose(). Used 561 // to enable diagnostics to distinguish calls to never-opened 562 // databases (incorrect use of the API) from calls to once-valid 563 // databases. 564 bool poisoned_; 565 566 ErrorCallback error_callback_; 567 568 // Tag for auxiliary histograms. 569 std::string histogram_tag_; 570 571 DISALLOW_COPY_AND_ASSIGN(Connection); 572 }; 573 574 } // namespace sql 575 576 #endif // SQL_CONNECTION_H_ 577