Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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> |
Torne (Richard Coles) | 90dce4d | 2013-05-29 14:40:03 +0100 | [diff] [blame] | 11 | #include <vector> |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 12 | |
| 13 | #include "base/basictypes.h" |
Torne (Richard Coles) | 90dce4d | 2013-05-29 14:40:03 +0100 | [diff] [blame] | 14 | #include "base/callback.h" |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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" |
Ben Murdoch | eb525c5 | 2013-07-10 11:40:50 +0100 | [diff] [blame] | 19 | #include "base/time/time.h" |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 20 | #include "sql/sql_export.h" |
| 21 | |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 22 | struct sqlite3; |
| 23 | struct sqlite3_stmt; |
| 24 | |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 25 | namespace base { |
| 26 | class FilePath; |
| 27 | } |
| 28 | |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 29 | namespace sql { |
| 30 | |
Ben Murdoch | ca12bfa | 2013-07-23 11:17:05 +0100 | [diff] [blame] | 31 | class Recovery; |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | |
Ben Murdoch | 9ab5563 | 2013-07-18 11:57:30 +0100 | [diff] [blame] | 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 | |
Torne (Richard Coles) | 90dce4d | 2013-05-29 14:40:03 +0100 | [diff] [blame] | 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. |
Torne (Richard Coles) | 90dce4d | 2013-05-29 14:40:03 +0100 | [diff] [blame] | 131 | typedef base::Callback<void(int, Statement*)> ErrorCallback; |
| 132 | void set_error_callback(const ErrorCallback& callback) { |
| 133 | error_callback_ = callback; |
| 134 | } |
Ben Murdoch | 7dbb3d5 | 2013-07-17 14:55:54 +0100 | [diff] [blame] | 135 | bool has_error_callback() const { |
| 136 | return !error_callback_.is_null(); |
| 137 | } |
Torne (Richard Coles) | 90dce4d | 2013-05-29 14:40:03 +0100 | [diff] [blame] | 138 | void reset_error_callback() { |
| 139 | error_callback_.Reset(); |
| 140 | } |
| 141 | |
Torne (Richard Coles) | 90dce4d | 2013-05-29 14:40:03 +0100 | [diff] [blame] | 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; |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 146 | } |
| 147 | |
Torne (Richard Coles) | 90dce4d | 2013-05-29 14:40:03 +0100 | [diff] [blame] | 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 | |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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. |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 163 | bool Open(const base::FilePath& path) WARN_UNUSED_RESULT; |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | |
Ben Murdoch | ca12bfa | 2013-07-23 11:17:05 +0100 | [diff] [blame] | 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 | |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 176 | // Returns true if the database has been successfully opened. |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | |
Ben Murdoch | ca12bfa | 2013-07-23 11:17:05 +0100 | [diff] [blame] | 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 | |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 239 | // Breaks all outstanding transactions (as initiated by |
Ben Murdoch | ca12bfa | 2013-07-23 11:17:05 +0100 | [diff] [blame] | 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. |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 243 | // |
Ben Murdoch | ca12bfa | 2013-07-23 11:17:05 +0100 | [diff] [blame] | 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(). |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 251 | bool RazeAndClose(); |
| 252 | |
Ben Murdoch | eb525c5 | 2013-07-10 11:40:50 +0100 | [diff] [blame] | 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 | |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | |
Ben Murdoch | ca12bfa | 2013-07-23 11:17:05 +0100 | [diff] [blame] | 280 | // Rollback all outstanding transactions. Use with care, there may |
| 281 | // be scoped transactions on the stack. |
| 282 | void RollbackAllTransactions(); |
| 283 | |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | |
Ben Murdoch | ca12bfa | 2013-07-23 11:17:05 +0100 | [diff] [blame] | 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 | |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | |
Torne (Richard Coles) | 3551c9c | 2013-08-23 16:39:15 +0100 | [diff] [blame] | 392 | // Return a reproducible representation of the schema equivalent to |
| 393 | // running the following statement at a sqlite3 command-line: |
| 394 | // SELECT type, name, tbl_name, sql FROM sqlite_master ORDER BY 1, 2, 3, 4; |
| 395 | std::string GetSchema() const; |
| 396 | |
Torne (Richard Coles) | 68043e1 | 2013-09-26 13:24:57 +0100 | [diff] [blame] | 397 | // Clients which provide an error_callback don't see the |
| 398 | // error-handling at the end of OnSqliteError(). Expose to allow |
| 399 | // those clients to work appropriately with ScopedErrorIgnorer in |
| 400 | // tests. |
| 401 | static bool ShouldIgnoreSqliteError(int error); |
| 402 | |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 403 | private: |
Ben Murdoch | ca12bfa | 2013-07-23 11:17:05 +0100 | [diff] [blame] | 404 | // For recovery module. |
| 405 | friend class Recovery; |
| 406 | |
Torne (Richard Coles) | 7d4cd47 | 2013-06-19 11:58:07 +0100 | [diff] [blame] | 407 | // Allow test-support code to set/reset error ignorer. |
| 408 | friend class ScopedErrorIgnorer; |
| 409 | |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 410 | // Statement accesses StatementRef which we don't want to expose to everybody |
| 411 | // (they should go through Statement). |
| 412 | friend class Statement; |
| 413 | |
| 414 | // Internal initialize function used by both Init and InitInMemory. The file |
| 415 | // name is always 8 bits since we want to use the 8-bit version of |
| 416 | // sqlite3_open. The string can also be sqlite's special ":memory:" string. |
Ben Murdoch | 7dbb3d5 | 2013-07-17 14:55:54 +0100 | [diff] [blame] | 417 | // |
| 418 | // |retry_flag| controls retrying the open if the error callback |
| 419 | // addressed errors using RazeAndClose(). |
| 420 | enum Retry { |
| 421 | NO_RETRY = 0, |
| 422 | RETRY_ON_POISON |
| 423 | }; |
| 424 | bool OpenInternal(const std::string& file_name, Retry retry_flag); |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 425 | |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 426 | // Internal close function used by Close() and RazeAndClose(). |
| 427 | // |forced| indicates that orderly-shutdown checks should not apply. |
| 428 | void CloseInternal(bool forced); |
| 429 | |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 430 | // Check whether the current thread is allowed to make IO calls, but only |
| 431 | // if database wasn't open in memory. Function is inlined to be a no-op in |
| 432 | // official build. |
| 433 | void AssertIOAllowed() { |
| 434 | if (!in_memory_) |
| 435 | base::ThreadRestrictions::AssertIOAllowed(); |
| 436 | } |
| 437 | |
| 438 | // Internal helper for DoesTableExist and DoesIndexExist. |
| 439 | bool DoesTableOrIndexExist(const char* name, const char* type) const; |
| 440 | |
Torne (Richard Coles) | 7d4cd47 | 2013-06-19 11:58:07 +0100 | [diff] [blame] | 441 | // Accessors for global error-ignorer, for injecting behavior during tests. |
| 442 | // See test/scoped_error_ignorer.h. |
| 443 | typedef base::Callback<bool(int)> ErrorIgnorerCallback; |
| 444 | static ErrorIgnorerCallback* current_ignorer_cb_; |
Torne (Richard Coles) | 7d4cd47 | 2013-06-19 11:58:07 +0100 | [diff] [blame] | 445 | static void SetErrorIgnorer(ErrorIgnorerCallback* ignorer); |
| 446 | static void ResetErrorIgnorer(); |
| 447 | |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 448 | // A StatementRef is a refcounted wrapper around a sqlite statement pointer. |
| 449 | // Refcounting allows us to give these statements out to sql::Statement |
| 450 | // objects while also optionally maintaining a cache of compiled statements |
| 451 | // by just keeping a refptr to these objects. |
| 452 | // |
| 453 | // A statement ref can be valid, in which case it can be used, or invalid to |
| 454 | // indicate that the statement hasn't been created yet, has an error, or has |
| 455 | // been destroyed. |
| 456 | // |
| 457 | // The Connection may revoke a StatementRef in some error cases, so callers |
| 458 | // should always check validity before using. |
| 459 | class SQL_EXPORT StatementRef : public base::RefCounted<StatementRef> { |
| 460 | public: |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 461 | // |connection| is the sql::Connection instance associated with |
| 462 | // the statement, and is used for tracking outstanding statements |
| 463 | // and for error handling. Set to NULL for invalid or untracked |
| 464 | // refs. |stmt| is the actual statement, and should only be NULL |
| 465 | // to create an invalid ref. |was_valid| indicates whether the |
| 466 | // statement should be considered valid for diagnistic purposes. |
| 467 | // |was_valid| can be true for NULL |stmt| if the connection has |
| 468 | // been forcibly closed by an error handler. |
| 469 | StatementRef(Connection* connection, sqlite3_stmt* stmt, bool was_valid); |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 470 | |
| 471 | // When true, the statement can be used. |
| 472 | bool is_valid() const { return !!stmt_; } |
| 473 | |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 474 | // When true, the statement is either currently valid, or was |
| 475 | // previously valid but the connection was forcibly closed. Used |
| 476 | // for diagnostic checks. |
| 477 | bool was_valid() const { return was_valid_; } |
| 478 | |
| 479 | // If we've not been linked to a connection, this will be NULL. |
| 480 | // TODO(shess): connection_ can be NULL in case of GetUntrackedStatement(), |
| 481 | // which prevents Statement::OnError() from forwarding errors. |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 482 | Connection* connection() const { return connection_; } |
| 483 | |
| 484 | // Returns the sqlite statement if any. If the statement is not active, |
| 485 | // this will return NULL. |
| 486 | sqlite3_stmt* stmt() const { return stmt_; } |
| 487 | |
| 488 | // Destroys the compiled statement and marks it NULL. The statement will |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 489 | // no longer be active. |forced| is used to indicate if orderly-shutdown |
| 490 | // checks should apply (see Connection::RazeAndClose()). |
| 491 | void Close(bool forced); |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 492 | |
| 493 | // Check whether the current thread is allowed to make IO calls, but only |
| 494 | // if database wasn't open in memory. |
| 495 | void AssertIOAllowed() { if (connection_) connection_->AssertIOAllowed(); } |
| 496 | |
| 497 | private: |
| 498 | friend class base::RefCounted<StatementRef>; |
| 499 | |
| 500 | ~StatementRef(); |
| 501 | |
| 502 | Connection* connection_; |
| 503 | sqlite3_stmt* stmt_; |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 504 | bool was_valid_; |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 505 | |
| 506 | DISALLOW_COPY_AND_ASSIGN(StatementRef); |
| 507 | }; |
| 508 | friend class StatementRef; |
| 509 | |
| 510 | // Executes a rollback statement, ignoring all transaction state. Used |
| 511 | // internally in the transaction management code. |
| 512 | void DoRollback(); |
| 513 | |
| 514 | // Called by a StatementRef when it's being created or destroyed. See |
| 515 | // open_statements_ below. |
| 516 | void StatementRefCreated(StatementRef* ref); |
| 517 | void StatementRefDeleted(StatementRef* ref); |
| 518 | |
Torne (Richard Coles) | 4e180b6 | 2013-10-18 15:46:22 +0100 | [diff] [blame] | 519 | // Called when a sqlite function returns an error, which is passed |
| 520 | // as |err|. The return value is the error code to be reflected |
| 521 | // back to client code. |stmt| is non-NULL if the error relates to |
| 522 | // an sql::Statement instance. |sql| is non-NULL if the error |
| 523 | // relates to non-statement sql code (Execute, for instance). Both |
| 524 | // can be NULL, but both should never be set. |
| 525 | // NOTE(shess): Originally, the return value was intended to allow |
| 526 | // error handlers to transparently convert errors into success. |
| 527 | // Unfortunately, transactions are not generally restartable, so |
| 528 | // this did not work out. |
| 529 | int OnSqliteError(int err, Statement* stmt, const char* sql); |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 530 | |
| 531 | // Like |Execute()|, but retries if the database is locked. |
| 532 | bool ExecuteWithTimeout(const char* sql, base::TimeDelta ms_timeout) |
| 533 | WARN_UNUSED_RESULT; |
| 534 | |
| 535 | // Internal helper for const functions. Like GetUniqueStatement(), |
| 536 | // except the statement is not entered into open_statements_, |
| 537 | // allowing this function to be const. Open statements can block |
| 538 | // closing the database, so only use in cases where the last ref is |
| 539 | // released before close could be called (which should always be the |
| 540 | // case for const functions). |
| 541 | scoped_refptr<StatementRef> GetUntrackedStatement(const char* sql) const; |
| 542 | |
| 543 | // The actual sqlite database. Will be NULL before Init has been called or if |
| 544 | // Init resulted in an error. |
| 545 | sqlite3* db_; |
| 546 | |
| 547 | // Parameters we'll configure in sqlite before doing anything else. Zero means |
| 548 | // use the default value. |
| 549 | int page_size_; |
| 550 | int cache_size_; |
| 551 | bool exclusive_locking_; |
Ben Murdoch | 9ab5563 | 2013-07-18 11:57:30 +0100 | [diff] [blame] | 552 | bool restrict_to_user_; |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 553 | |
| 554 | // All cached statements. Keeping a reference to these statements means that |
| 555 | // they'll remain active. |
| 556 | typedef std::map<StatementID, scoped_refptr<StatementRef> > |
| 557 | CachedStatementMap; |
| 558 | CachedStatementMap statement_cache_; |
| 559 | |
| 560 | // A list of all StatementRefs we've given out. Each ref must register with |
| 561 | // us when it's created or destroyed. This allows us to potentially close |
| 562 | // any open statements when we encounter an error. |
| 563 | typedef std::set<StatementRef*> StatementRefSet; |
| 564 | StatementRefSet open_statements_; |
| 565 | |
| 566 | // Number of currently-nested transactions. |
| 567 | int transaction_nesting_; |
| 568 | |
| 569 | // True if any of the currently nested transactions have been rolled back. |
| 570 | // When we get to the outermost transaction, this will determine if we do |
| 571 | // a rollback instead of a commit. |
| 572 | bool needs_rollback_; |
| 573 | |
| 574 | // True if database is open with OpenInMemory(), False if database is open |
| 575 | // with Open(). |
| 576 | bool in_memory_; |
| 577 | |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 578 | // |true| if the connection was closed using RazeAndClose(). Used |
| 579 | // to enable diagnostics to distinguish calls to never-opened |
| 580 | // databases (incorrect use of the API) from calls to once-valid |
| 581 | // databases. |
| 582 | bool poisoned_; |
| 583 | |
Torne (Richard Coles) | 90dce4d | 2013-05-29 14:40:03 +0100 | [diff] [blame] | 584 | ErrorCallback error_callback_; |
| 585 | |
Torne (Richard Coles) | 90dce4d | 2013-05-29 14:40:03 +0100 | [diff] [blame] | 586 | // Tag for auxiliary histograms. |
| 587 | std::string histogram_tag_; |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 588 | |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 589 | DISALLOW_COPY_AND_ASSIGN(Connection); |
| 590 | }; |
| 591 | |
| 592 | } // namespace sql |
| 593 | |
| 594 | #endif // SQL_CONNECTION_H_ |