Getting rid of GetDefaultProfile
[chromium-blink-merge.git] / sql / connection.h
blob54c3f8b7b8e672cf50749dc4c4673eb0cae99bfb
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.
5 #ifndef SQL_CONNECTION_H_
6 #define SQL_CONNECTION_H_
8 #include <map>
9 #include <set>
10 #include <string>
11 #include <vector>
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"
22 struct sqlite3;
23 struct sqlite3_stmt;
25 namespace base {
26 class FilePath;
29 namespace sql {
31 class Recovery;
32 class Statement;
34 // Uniquely identifies a statement. There are two modes of operation:
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.
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.
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) {
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) {
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);
70 // We need this to insert into our map.
71 bool operator<(const StatementID& other) const;
73 private:
74 int number_;
75 const char* str_;
78 #define SQL_FROM_HERE sql::StatementID(__FILE__, __LINE__)
80 class Connection;
82 class SQL_EXPORT Connection {
83 private:
84 class StatementRef; // Forward declaration, see real one below.
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();
92 // Pre-init configuration ----------------------------------------------------
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.
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; }
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; }
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.
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.
117 // This must be called before Open() to have an effect.
118 void set_exclusive_locking() { exclusive_locking_ = true; }
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; }
126 // Set an error-handling callback. On errors, the error number (and
127 // statement, if available) will be passed to the callback.
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;
135 bool has_error_callback() const {
136 return !error_callback_.is_null();
138 void reset_error_callback() {
139 error_callback_.Reset();
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;
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;
153 // Run "PRAGMA integrity_check" and post each line of
154 // results into |messages|. Returns the success of running the
155 // statement - per the SQLite documentation, if no errors are found the
156 // call should succeed, and a single value "ok" should be in messages.
157 bool FullIntegrityCheck(std::vector<std::string>* messages);
159 // Runs "PRAGMA quick_check" and, unlike the FullIntegrityCheck method,
160 // interprets the results returning true if the the statement executes
161 // without error and results in a single "ok" value.
162 bool QuickIntegrityCheck() WARN_UNUSED_RESULT;
164 // Initialization ------------------------------------------------------------
166 // Initializes the SQL connection for the given file, returning true if the
167 // file could be opened. You can call this or OpenInMemory.
168 bool Open(const base::FilePath& path) WARN_UNUSED_RESULT;
170 // Initializes the SQL connection for a temporary in-memory database. There
171 // will be no associated file on disk, and the initial database will be
172 // empty. You can call this or Open.
173 bool OpenInMemory() WARN_UNUSED_RESULT;
175 // Create a temporary on-disk database. The database will be
176 // deleted after close. This kind of database is similar to
177 // OpenInMemory() for small databases, but can page to disk if the
178 // database becomes large.
179 bool OpenTemporary() WARN_UNUSED_RESULT;
181 // Returns true if the database has been successfully opened.
182 bool is_open() const { return !!db_; }
184 // Closes the database. This is automatically performed on destruction for
185 // you, but this allows you to close the database early. You must not call
186 // any other functions after closing it. It is permissable to call Close on
187 // an uninitialized or already-closed database.
188 void Close();
190 // Pre-loads the first <cache-size> pages into the cache from the file.
191 // If you expect to soon use a substantial portion of the database, this
192 // is much more efficient than allowing the pages to be populated organically
193 // since there is no per-page hard drive seeking. If the file is larger than
194 // the cache, the last part that doesn't fit in the cache will be brought in
195 // organically.
197 // This function assumes your class is using a meta table on the current
198 // database, as it openes a transaction on the meta table to force the
199 // database to be initialized. You should feel free to initialize the meta
200 // table after calling preload since the meta table will already be in the
201 // database if it exists, and if it doesn't exist, the database won't
202 // generally exist either.
203 void Preload();
205 // Try to trim the cache memory used by the database. If |aggressively| is
206 // true, this function will try to free all of the cache memory it can. If
207 // |aggressively| is false, this function will try to cut cache memory
208 // usage by half.
209 void TrimMemory(bool aggressively);
211 // Raze the database to the ground. This approximates creating a
212 // fresh database from scratch, within the constraints of SQLite's
213 // locking protocol (locks and open handles can make doing this with
214 // filesystem operations problematic). Returns true if the database
215 // was razed.
217 // false is returned if the database is locked by some other
218 // process. RazeWithTimeout() may be used if appropriate.
220 // NOTE(shess): Raze() will DCHECK in the following situations:
221 // - database is not open.
222 // - the connection has a transaction open.
223 // - a SQLite issue occurs which is structural in nature (like the
224 // statements used are broken).
225 // Since Raze() is expected to be called in unexpected situations,
226 // these all return false, since it is unlikely that the caller
227 // could fix them.
229 // The database's page size is taken from |page_size_|. The
230 // existing database's |auto_vacuum| setting is lost (the
231 // possibility of corruption makes it unreliable to pull it from the
232 // existing database). To re-enable on the empty database requires
233 // running "PRAGMA auto_vacuum = 1;" then "VACUUM".
235 // NOTE(shess): For Android, SQLITE_DEFAULT_AUTOVACUUM is set to 1,
236 // so Raze() sets auto_vacuum to 1.
238 // TODO(shess): Raze() needs a connection so cannot clear SQLITE_NOTADB.
239 // TODO(shess): Bake auto_vacuum into Connection's API so it can
240 // just pick up the default.
241 bool Raze();
242 bool RazeWithTimout(base::TimeDelta timeout);
244 // Breaks all outstanding transactions (as initiated by
245 // BeginTransaction()), closes the SQLite database, and poisons the
246 // object so that all future operations against the Connection (or
247 // its Statements) fail safely, without side effects.
249 // This is intended as an alternative to Close() in error callbacks.
250 // Close() should still be called at some point.
251 void Poison();
253 // Raze() the database and Poison() the handle. Returns the return
254 // value from Raze().
255 // TODO(shess): Rename to RazeAndPoison().
256 bool RazeAndClose();
258 // Delete the underlying database files associated with |path|.
259 // This should be used on a database which has no existing
260 // connections. If any other connections are open to the same
261 // database, this could cause odd results or corruption (for
262 // instance if a hot journal is deleted but the associated database
263 // is not).
265 // Returns true if the database file and associated journals no
266 // longer exist, false otherwise. If the database has never
267 // existed, this will return true.
268 static bool Delete(const base::FilePath& path);
270 // Transactions --------------------------------------------------------------
272 // Transaction management. We maintain a virtual transaction stack to emulate
273 // nested transactions since sqlite can't do nested transactions. The
274 // limitation is you can't roll back a sub transaction: if any transaction
275 // fails, all transactions open will also be rolled back. Any nested
276 // transactions after one has rolled back will return fail for Begin(). If
277 // Begin() fails, you must not call Commit or Rollback().
279 // Normally you should use sql::Transaction to manage a transaction, which
280 // will scope it to a C++ context.
281 bool BeginTransaction();
282 void RollbackTransaction();
283 bool CommitTransaction();
285 // Rollback all outstanding transactions. Use with care, there may
286 // be scoped transactions on the stack.
287 void RollbackAllTransactions();
289 // Returns the current transaction nesting, which will be 0 if there are
290 // no open transactions.
291 int transaction_nesting() const { return transaction_nesting_; }
293 // Attached databases---------------------------------------------------------
295 // SQLite supports attaching multiple database files to a single
296 // handle. Attach the database in |other_db_path| to the current
297 // handle under |attachment_point|. |attachment_point| should only
298 // contain characters from [a-zA-Z0-9_].
300 // Note that calling attach or detach with an open transaction is an
301 // error.
302 bool AttachDatabase(const base::FilePath& other_db_path,
303 const char* attachment_point);
304 bool DetachDatabase(const char* attachment_point);
306 // Statements ----------------------------------------------------------------
308 // Executes the given SQL string, returning true on success. This is
309 // normally used for simple, 1-off statements that don't take any bound
310 // parameters and don't return any data (e.g. CREATE TABLE).
312 // This will DCHECK if the |sql| contains errors.
314 // Do not use ignore_result() to ignore all errors. Use
315 // ExecuteAndReturnErrorCode() and ignore only specific errors.
316 bool Execute(const char* sql) WARN_UNUSED_RESULT;
318 // Like Execute(), but returns the error code given by SQLite.
319 int ExecuteAndReturnErrorCode(const char* sql) WARN_UNUSED_RESULT;
321 // Returns true if we have a statement with the given identifier already
322 // cached. This is normally not necessary to call, but can be useful if the
323 // caller has to dynamically build up SQL to avoid doing so if it's already
324 // cached.
325 bool HasCachedStatement(const StatementID& id) const;
327 // Returns a statement for the given SQL using the statement cache. It can
328 // take a nontrivial amount of work to parse and compile a statement, so
329 // keeping commonly-used ones around for future use is important for
330 // performance.
332 // If the |sql| has an error, an invalid, inert StatementRef is returned (and
333 // the code will crash in debug). The caller must deal with this eventuality,
334 // either by checking validity of the |sql| before calling, by correctly
335 // handling the return of an inert statement, or both.
337 // The StatementID and the SQL must always correspond to one-another. The
338 // ID is the lookup into the cache, so crazy things will happen if you use
339 // different SQL with the same ID.
341 // You will normally use the SQL_FROM_HERE macro to generate a statement
342 // ID associated with the current line of code. This gives uniqueness without
343 // you having to manage unique names. See StatementID above for more.
345 // Example:
346 // sql::Statement stmt(connection_.GetCachedStatement(
347 // SQL_FROM_HERE, "SELECT * FROM foo"));
348 // if (!stmt)
349 // return false; // Error creating statement.
350 scoped_refptr<StatementRef> GetCachedStatement(const StatementID& id,
351 const char* sql);
353 // Used to check a |sql| statement for syntactic validity. If the statement is
354 // valid SQL, returns true.
355 bool IsSQLValid(const char* sql);
357 // Returns a non-cached statement for the given SQL. Use this for SQL that
358 // is only executed once or only rarely (there is overhead associated with
359 // keeping a statement cached).
361 // See GetCachedStatement above for examples and error information.
362 scoped_refptr<StatementRef> GetUniqueStatement(const char* sql);
364 // Info querying -------------------------------------------------------------
366 // Returns true if the given table exists.
367 bool DoesTableExist(const char* table_name) const;
369 // Returns true if the given index exists.
370 bool DoesIndexExist(const char* index_name) const;
372 // Returns true if a column with the given name exists in the given table.
373 bool DoesColumnExist(const char* table_name, const char* column_name) const;
375 // Returns sqlite's internal ID for the last inserted row. Valid only
376 // immediately after an insert.
377 int64 GetLastInsertRowId() const;
379 // Returns sqlite's count of the number of rows modified by the last
380 // statement executed. Will be 0 if no statement has executed or the database
381 // is closed.
382 int GetLastChangeCount() const;
384 // Errors --------------------------------------------------------------------
386 // Returns the error code associated with the last sqlite operation.
387 int GetErrorCode() const;
389 // Returns the errno associated with GetErrorCode(). See
390 // SQLITE_LAST_ERRNO in SQLite documentation.
391 int GetLastErrno() const;
393 // Returns a pointer to a statically allocated string associated with the
394 // last sqlite operation.
395 const char* GetErrorMessage() const;
397 // Return a reproducible representation of the schema equivalent to
398 // running the following statement at a sqlite3 command-line:
399 // SELECT type, name, tbl_name, sql FROM sqlite_master ORDER BY 1, 2, 3, 4;
400 std::string GetSchema() const;
402 // Clients which provide an error_callback don't see the
403 // error-handling at the end of OnSqliteError(). Expose to allow
404 // those clients to work appropriately with ScopedErrorIgnorer in
405 // tests.
406 static bool ShouldIgnoreSqliteError(int error);
408 private:
409 // For recovery module.
410 friend class Recovery;
412 // Allow test-support code to set/reset error ignorer.
413 friend class ScopedErrorIgnorer;
415 // Statement accesses StatementRef which we don't want to expose to everybody
416 // (they should go through Statement).
417 friend class Statement;
419 // Internal initialize function used by both Init and InitInMemory. The file
420 // name is always 8 bits since we want to use the 8-bit version of
421 // sqlite3_open. The string can also be sqlite's special ":memory:" string.
423 // |retry_flag| controls retrying the open if the error callback
424 // addressed errors using RazeAndClose().
425 enum Retry {
426 NO_RETRY = 0,
427 RETRY_ON_POISON
429 bool OpenInternal(const std::string& file_name, Retry retry_flag);
431 // Internal close function used by Close() and RazeAndClose().
432 // |forced| indicates that orderly-shutdown checks should not apply.
433 void CloseInternal(bool forced);
435 // Check whether the current thread is allowed to make IO calls, but only
436 // if database wasn't open in memory. Function is inlined to be a no-op in
437 // official build.
438 void AssertIOAllowed() {
439 if (!in_memory_)
440 base::ThreadRestrictions::AssertIOAllowed();
443 // Internal helper for DoesTableExist and DoesIndexExist.
444 bool DoesTableOrIndexExist(const char* name, const char* type) const;
446 // Accessors for global error-ignorer, for injecting behavior during tests.
447 // See test/scoped_error_ignorer.h.
448 typedef base::Callback<bool(int)> ErrorIgnorerCallback;
449 static ErrorIgnorerCallback* current_ignorer_cb_;
450 static void SetErrorIgnorer(ErrorIgnorerCallback* ignorer);
451 static void ResetErrorIgnorer();
453 // A StatementRef is a refcounted wrapper around a sqlite statement pointer.
454 // Refcounting allows us to give these statements out to sql::Statement
455 // objects while also optionally maintaining a cache of compiled statements
456 // by just keeping a refptr to these objects.
458 // A statement ref can be valid, in which case it can be used, or invalid to
459 // indicate that the statement hasn't been created yet, has an error, or has
460 // been destroyed.
462 // The Connection may revoke a StatementRef in some error cases, so callers
463 // should always check validity before using.
464 class SQL_EXPORT StatementRef : public base::RefCounted<StatementRef> {
465 public:
466 // |connection| is the sql::Connection instance associated with
467 // the statement, and is used for tracking outstanding statements
468 // and for error handling. Set to NULL for invalid or untracked
469 // refs. |stmt| is the actual statement, and should only be NULL
470 // to create an invalid ref. |was_valid| indicates whether the
471 // statement should be considered valid for diagnistic purposes.
472 // |was_valid| can be true for NULL |stmt| if the connection has
473 // been forcibly closed by an error handler.
474 StatementRef(Connection* connection, sqlite3_stmt* stmt, bool was_valid);
476 // When true, the statement can be used.
477 bool is_valid() const { return !!stmt_; }
479 // When true, the statement is either currently valid, or was
480 // previously valid but the connection was forcibly closed. Used
481 // for diagnostic checks.
482 bool was_valid() const { return was_valid_; }
484 // If we've not been linked to a connection, this will be NULL.
485 // TODO(shess): connection_ can be NULL in case of GetUntrackedStatement(),
486 // which prevents Statement::OnError() from forwarding errors.
487 Connection* connection() const { return connection_; }
489 // Returns the sqlite statement if any. If the statement is not active,
490 // this will return NULL.
491 sqlite3_stmt* stmt() const { return stmt_; }
493 // Destroys the compiled statement and marks it NULL. The statement will
494 // no longer be active. |forced| is used to indicate if orderly-shutdown
495 // checks should apply (see Connection::RazeAndClose()).
496 void Close(bool forced);
498 // Check whether the current thread is allowed to make IO calls, but only
499 // if database wasn't open in memory.
500 void AssertIOAllowed() { if (connection_) connection_->AssertIOAllowed(); }
502 private:
503 friend class base::RefCounted<StatementRef>;
505 ~StatementRef();
507 Connection* connection_;
508 sqlite3_stmt* stmt_;
509 bool was_valid_;
511 DISALLOW_COPY_AND_ASSIGN(StatementRef);
513 friend class StatementRef;
515 // Executes a rollback statement, ignoring all transaction state. Used
516 // internally in the transaction management code.
517 void DoRollback();
519 // Called by a StatementRef when it's being created or destroyed. See
520 // open_statements_ below.
521 void StatementRefCreated(StatementRef* ref);
522 void StatementRefDeleted(StatementRef* ref);
524 // Called when a sqlite function returns an error, which is passed
525 // as |err|. The return value is the error code to be reflected
526 // back to client code. |stmt| is non-NULL if the error relates to
527 // an sql::Statement instance. |sql| is non-NULL if the error
528 // relates to non-statement sql code (Execute, for instance). Both
529 // can be NULL, but both should never be set.
530 // NOTE(shess): Originally, the return value was intended to allow
531 // error handlers to transparently convert errors into success.
532 // Unfortunately, transactions are not generally restartable, so
533 // this did not work out.
534 int OnSqliteError(int err, Statement* stmt, const char* sql);
536 // Like |Execute()|, but retries if the database is locked.
537 bool ExecuteWithTimeout(const char* sql, base::TimeDelta ms_timeout)
538 WARN_UNUSED_RESULT;
540 // Internal helper for const functions. Like GetUniqueStatement(),
541 // except the statement is not entered into open_statements_,
542 // allowing this function to be const. Open statements can block
543 // closing the database, so only use in cases where the last ref is
544 // released before close could be called (which should always be the
545 // case for const functions).
546 scoped_refptr<StatementRef> GetUntrackedStatement(const char* sql) const;
548 bool IntegrityCheckHelper(
549 const char* pragma_sql,
550 std::vector<std::string>* messages) WARN_UNUSED_RESULT;
552 // The actual sqlite database. Will be NULL before Init has been called or if
553 // Init resulted in an error.
554 sqlite3* db_;
556 // Parameters we'll configure in sqlite before doing anything else. Zero means
557 // use the default value.
558 int page_size_;
559 int cache_size_;
560 bool exclusive_locking_;
561 bool restrict_to_user_;
563 // All cached statements. Keeping a reference to these statements means that
564 // they'll remain active.
565 typedef std::map<StatementID, scoped_refptr<StatementRef> >
566 CachedStatementMap;
567 CachedStatementMap statement_cache_;
569 // A list of all StatementRefs we've given out. Each ref must register with
570 // us when it's created or destroyed. This allows us to potentially close
571 // any open statements when we encounter an error.
572 typedef std::set<StatementRef*> StatementRefSet;
573 StatementRefSet open_statements_;
575 // Number of currently-nested transactions.
576 int transaction_nesting_;
578 // True if any of the currently nested transactions have been rolled back.
579 // When we get to the outermost transaction, this will determine if we do
580 // a rollback instead of a commit.
581 bool needs_rollback_;
583 // True if database is open with OpenInMemory(), False if database is open
584 // with Open().
585 bool in_memory_;
587 // |true| if the connection was closed using RazeAndClose(). Used
588 // to enable diagnostics to distinguish calls to never-opened
589 // databases (incorrect use of the API) from calls to once-valid
590 // databases.
591 bool poisoned_;
593 ErrorCallback error_callback_;
595 // Tag for auxiliary histograms.
596 std::string histogram_tag_;
598 DISALLOW_COPY_AND_ASSIGN(Connection);
601 } // namespace sql
603 #endif // SQL_CONNECTION_H_