blob: 959a1b1848110161aa353abaaeab2099a2b246e0 [file] [log] [blame]
[email protected]2eec0a22012-07-24 01:59:581// Copyright (c) 2012 The Chromium Authors. All rights reserved.
[email protected]e5ffd0e42009-09-11 21:30:562// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
[email protected]f0a54b22011-07-19 18:40:215#ifndef SQL_CONNECTION_H_
6#define SQL_CONNECTION_H_
[email protected]e5ffd0e42009-09-11 21:30:567
avi0b519202015-12-21 07:25:198#include <stddef.h>
tfarina720d4f32015-05-11 22:31:269#include <stdint.h>
[email protected]e5ffd0e42009-09-11 21:30:5610#include <map>
mostynbd82cd9952016-04-11 20:05:3411#include <memory>
[email protected]e5ffd0e42009-09-11 21:30:5612#include <set>
[email protected]7d6aee4e2009-09-12 01:12:3313#include <string>
[email protected]80abf152013-05-22 12:42:4214#include <vector>
[email protected]e5ffd0e42009-09-11 21:30:5615
[email protected]c3881b372013-05-17 08:39:4616#include "base/callback.h"
[email protected]9fe37552011-12-23 17:07:2017#include "base/compiler_specific.h"
shessc8cd2a162015-10-22 20:30:4618#include "base/gtest_prod_util.h"
tfarina720d4f32015-05-11 22:31:2619#include "base/macros.h"
[email protected]3b63f8f42011-03-28 01:54:1520#include "base/memory/ref_counted.h"
[email protected]35f7e5392012-07-27 19:54:5021#include "base/threading/thread_restrictions.h"
[email protected]2b59d682013-06-28 15:22:0322#include "base/time/time.h"
[email protected]d4526962011-11-10 21:40:2823#include "sql/sql_export.h"
[email protected]e5ffd0e42009-09-11 21:30:5624
[email protected]e5ffd0e42009-09-11 21:30:5625struct sqlite3;
26struct sqlite3_stmt;
27
[email protected]a3ef4832013-02-02 05:12:3328namespace base {
29class FilePath;
shess58b8df82015-06-03 00:19:3230class HistogramBase;
[email protected]a3ef4832013-02-02 05:12:3331}
32
[email protected]e5ffd0e42009-09-11 21:30:5633namespace sql {
34
ssid3be5b1ec2016-01-13 14:21:5735class ConnectionMemoryDumpProvider;
[email protected]8d409412013-07-19 18:25:3036class Recovery;
[email protected]e5ffd0e42009-09-11 21:30:5637class Statement;
38
shess58b8df82015-06-03 00:19:3239// To allow some test classes to be friended.
40namespace test {
41class ScopedCommitHook;
42class ScopedScalarFunction;
43class ScopedMockTimeSource;
44}
45
[email protected]e5ffd0e42009-09-11 21:30:5646// Uniquely identifies a statement. There are two modes of operation:
47//
48// - In the most common mode, you will use the source file and line number to
49// identify your statement. This is a convienient way to get uniqueness for
50// a statement that is only used in one place. Use the SQL_FROM_HERE macro
51// to generate a StatementID.
52//
53// - In the "custom" mode you may use the statement from different places or
54// need to manage it yourself for whatever reason. In this case, you should
55// make up your own unique name and pass it to the StatementID. This name
56// must be a static string, since this object only deals with pointers and
57// assumes the underlying string doesn't change or get deleted.
58//
59// This object is copyable and assignable using the compiler-generated
60// operator= and copy constructor.
61class StatementID {
62 public:
63 // Creates a uniquely named statement with the given file ane line number.
64 // Normally you will use SQL_FROM_HERE instead of calling yourself.
65 StatementID(const char* file, int line)
66 : number_(line),
67 str_(file) {
68 }
69
70 // Creates a uniquely named statement with the given user-defined name.
71 explicit StatementID(const char* unique_name)
72 : number_(-1),
73 str_(unique_name) {
74 }
75
76 // This constructor is unimplemented and will generate a linker error if
77 // called. It is intended to try to catch people dynamically generating
78 // a statement name that will be deallocated and will cause a crash later.
79 // All strings must be static and unchanging!
80 explicit StatementID(const std::string& dont_ever_do_this);
81
82 // We need this to insert into our map.
83 bool operator<(const StatementID& other) const;
84
85 private:
86 int number_;
87 const char* str_;
88};
89
90#define SQL_FROM_HERE sql::StatementID(__FILE__, __LINE__)
91
[email protected]faa604e2009-09-25 22:38:5992class Connection;
93
shess58b8df82015-06-03 00:19:3294// Abstract the source of timing information for metrics (RecordCommitTime, etc)
95// to allow testing control.
96class SQL_EXPORT TimeSource {
97 public:
98 TimeSource() {}
99 virtual ~TimeSource() {}
100
101 // Return the current time (by default base::TimeTicks::Now()).
102 virtual base::TimeTicks Now();
103
104 private:
105 DISALLOW_COPY_AND_ASSIGN(TimeSource);
106};
107
ssid3be5b1ec2016-01-13 14:21:57108class SQL_EXPORT Connection {
[email protected]e5ffd0e42009-09-11 21:30:56109 private:
110 class StatementRef; // Forward declaration, see real one below.
111
112 public:
[email protected]765b44502009-10-02 05:01:42113 // The database is opened by calling Open[InMemory](). Any uncommitted
114 // transactions will be rolled back when this object is deleted.
[email protected]e5ffd0e42009-09-11 21:30:56115 Connection();
ssid3be5b1ec2016-01-13 14:21:57116 ~Connection();
[email protected]e5ffd0e42009-09-11 21:30:56117
118 // Pre-init configuration ----------------------------------------------------
119
[email protected]765b44502009-10-02 05:01:42120 // Sets the page size that will be used when creating a new database. This
[email protected]e5ffd0e42009-09-11 21:30:56121 // must be called before Init(), and will only have an effect on new
122 // databases.
123 //
124 // From sqlite.org: "The page size must be a power of two greater than or
125 // equal to 512 and less than or equal to SQLITE_MAX_PAGE_SIZE. The maximum
126 // value for SQLITE_MAX_PAGE_SIZE is 32768."
127 void set_page_size(int page_size) { page_size_ = page_size; }
128
129 // Sets the number of pages that will be cached in memory by sqlite. The
130 // total cache size in bytes will be page_size * cache_size. This must be
[email protected]765b44502009-10-02 05:01:42131 // called before Open() to have an effect.
[email protected]e5ffd0e42009-09-11 21:30:56132 void set_cache_size(int cache_size) { cache_size_ = cache_size; }
133
134 // Call to put the database in exclusive locking mode. There is no "back to
135 // normal" flag because of some additional requirements sqlite puts on this
[email protected]4ab952f2014-04-01 20:18:16136 // transaction (requires another access to the DB) and because we don't
[email protected]e5ffd0e42009-09-11 21:30:56137 // actually need it.
138 //
139 // Exclusive mode means that the database is not unlocked at the end of each
140 // transaction, which means there may be less time spent initializing the
141 // next transaction because it doesn't have to re-aquire locks.
142 //
[email protected]765b44502009-10-02 05:01:42143 // This must be called before Open() to have an effect.
[email protected]e5ffd0e42009-09-11 21:30:56144 void set_exclusive_locking() { exclusive_locking_ = true; }
145
[email protected]81a2a602013-07-17 19:10:36146 // Call to cause Open() to restrict access permissions of the
147 // database file to only the owner.
148 // TODO(shess): Currently only supported on OS_POSIX, is a noop on
149 // other platforms.
150 void set_restrict_to_user() { restrict_to_user_ = true; }
151
kerz42ff2a012016-04-27 04:50:06152 // Call to opt out of memory-mapped file I/O.
shess7dbd4dee2015-10-06 17:39:16153 void set_mmap_disabled() { mmap_disabled_ = true; }
154
[email protected]c3881b372013-05-17 08:39:46155 // Set an error-handling callback. On errors, the error number (and
156 // statement, if available) will be passed to the callback.
157 //
158 // If no callback is set, the default action is to crash in debug
159 // mode or return failure in release mode.
[email protected]c3881b372013-05-17 08:39:46160 typedef base::Callback<void(int, Statement*)> ErrorCallback;
161 void set_error_callback(const ErrorCallback& callback) {
162 error_callback_ = callback;
163 }
[email protected]98cf3002013-07-12 01:38:56164 bool has_error_callback() const {
165 return !error_callback_.is_null();
166 }
[email protected]c3881b372013-05-17 08:39:46167 void reset_error_callback() {
168 error_callback_.Reset();
169 }
170
shess58b8df82015-06-03 00:19:32171 // Set this to enable additional per-connection histogramming. Must be called
172 // before Open().
173 void set_histogram_tag(const std::string& tag);
[email protected]c088e3a32013-01-03 23:59:14174
[email protected]210ce0af2013-05-15 09:10:39175 // Record a sparse UMA histogram sample under
176 // |name|+"."+|histogram_tag_|. If |histogram_tag_| is empty, no
177 // histogram is recorded.
178 void AddTaggedHistogram(const std::string& name, size_t sample) const;
179
shess58b8df82015-06-03 00:19:32180 // Track various API calls and results. Values corrospond to UMA
181 // histograms, do not modify, or add or delete other than directly
182 // before EVENT_MAX_VALUE.
183 enum Events {
184 // Number of statements run, either with sql::Statement or Execute*().
185 EVENT_STATEMENT_RUN = 0,
186
187 // Number of rows returned by statements run.
188 EVENT_STATEMENT_ROWS,
189
190 // Number of statements successfully run (all steps returned SQLITE_DONE or
191 // SQLITE_ROW).
192 EVENT_STATEMENT_SUCCESS,
193
194 // Number of statements run by Execute() or ExecuteAndReturnErrorCode().
195 EVENT_EXECUTE,
196
197 // Number of rows changed by autocommit statements.
198 EVENT_CHANGES_AUTOCOMMIT,
199
200 // Number of rows changed by statements in transactions.
201 EVENT_CHANGES,
202
203 // Count actual SQLite transaction statements (not including nesting).
204 EVENT_BEGIN,
205 EVENT_COMMIT,
206 EVENT_ROLLBACK,
207
shessd90aeea82015-11-13 02:24:31208 // Track success and failure in GetAppropriateMmapSize().
209 // GetAppropriateMmapSize() should record at most one of these per run. The
210 // case of mapping everything is not recorded.
211 EVENT_MMAP_META_MISSING, // No meta table present.
212 EVENT_MMAP_META_FAILURE_READ, // Failed reading meta table.
213 EVENT_MMAP_META_FAILURE_UPDATE, // Failed updating meta table.
214 EVENT_MMAP_VFS_FAILURE, // Failed to access VFS.
215 EVENT_MMAP_FAILED, // Failure from past run.
216 EVENT_MMAP_FAILED_NEW, // Read error in this run.
217 EVENT_MMAP_SUCCESS_NEW, // Read to EOF in this run.
218 EVENT_MMAP_SUCCESS_PARTIAL, // Read but did not reach EOF.
219 EVENT_MMAP_SUCCESS_NO_PROGRESS, // Read quota exhausted.
220
shess58b8df82015-06-03 00:19:32221 // Leave this at the end.
222 // TODO(shess): |EVENT_MAX| causes compile fail on Windows.
223 EVENT_MAX_VALUE
224 };
225 void RecordEvent(Events event, size_t count);
226 void RecordOneEvent(Events event) {
227 RecordEvent(event, 1);
228 }
229
[email protected]579446c2013-12-16 18:36:52230 // Run "PRAGMA integrity_check" and post each line of
231 // results into |messages|. Returns the success of running the
232 // statement - per the SQLite documentation, if no errors are found the
233 // call should succeed, and a single value "ok" should be in messages.
234 bool FullIntegrityCheck(std::vector<std::string>* messages);
235
236 // Runs "PRAGMA quick_check" and, unlike the FullIntegrityCheck method,
237 // interprets the results returning true if the the statement executes
238 // without error and results in a single "ok" value.
239 bool QuickIntegrityCheck() WARN_UNUSED_RESULT;
[email protected]80abf152013-05-22 12:42:42240
[email protected]e5ffd0e42009-09-11 21:30:56241 // Initialization ------------------------------------------------------------
242
243 // Initializes the SQL connection for the given file, returning true if the
[email protected]35f2094c2009-12-29 22:46:55244 // file could be opened. You can call this or OpenInMemory.
[email protected]a3ef4832013-02-02 05:12:33245 bool Open(const base::FilePath& path) WARN_UNUSED_RESULT;
[email protected]765b44502009-10-02 05:01:42246
247 // Initializes the SQL connection for a temporary in-memory database. There
248 // will be no associated file on disk, and the initial database will be
[email protected]35f2094c2009-12-29 22:46:55249 // empty. You can call this or Open.
[email protected]9fe37552011-12-23 17:07:20250 bool OpenInMemory() WARN_UNUSED_RESULT;
[email protected]765b44502009-10-02 05:01:42251
[email protected]8d409412013-07-19 18:25:30252 // Create a temporary on-disk database. The database will be
253 // deleted after close. This kind of database is similar to
254 // OpenInMemory() for small databases, but can page to disk if the
255 // database becomes large.
256 bool OpenTemporary() WARN_UNUSED_RESULT;
257
[email protected]41a97c812013-02-07 02:35:38258 // Returns true if the database has been successfully opened.
[email protected]765b44502009-10-02 05:01:42259 bool is_open() const { return !!db_; }
[email protected]e5ffd0e42009-09-11 21:30:56260
261 // Closes the database. This is automatically performed on destruction for
262 // you, but this allows you to close the database early. You must not call
263 // any other functions after closing it. It is permissable to call Close on
264 // an uninitialized or already-closed database.
265 void Close();
266
[email protected]8ada10f2013-12-21 00:42:34267 // Reads the first <cache-size>*<page-size> bytes of the file to prime the
268 // filesystem cache. This can be more efficient than faulting pages
269 // individually. Since this involves blocking I/O, it should only be used if
270 // the caller will immediately read a substantial amount of data from the
271 // database.
[email protected]e5ffd0e42009-09-11 21:30:56272 //
[email protected]8ada10f2013-12-21 00:42:34273 // TODO(shess): Design a set of histograms or an experiment to inform this
274 // decision. Preloading should almost always improve later performance
275 // numbers for this database simply because it pulls operations forward, but
276 // if the data isn't actually used soon then preloading just slows down
277 // everything else.
[email protected]e5ffd0e42009-09-11 21:30:56278 void Preload();
279
[email protected]be7995f12013-07-18 18:49:14280 // Try to trim the cache memory used by the database. If |aggressively| is
281 // true, this function will try to free all of the cache memory it can. If
282 // |aggressively| is false, this function will try to cut cache memory
283 // usage by half.
284 void TrimMemory(bool aggressively);
285
[email protected]8e0c01282012-04-06 19:36:49286 // Raze the database to the ground. This approximates creating a
287 // fresh database from scratch, within the constraints of SQLite's
288 // locking protocol (locks and open handles can make doing this with
289 // filesystem operations problematic). Returns true if the database
290 // was razed.
291 //
292 // false is returned if the database is locked by some other
293 // process. RazeWithTimeout() may be used if appropriate.
294 //
295 // NOTE(shess): Raze() will DCHECK in the following situations:
296 // - database is not open.
297 // - the connection has a transaction open.
298 // - a SQLite issue occurs which is structural in nature (like the
299 // statements used are broken).
300 // Since Raze() is expected to be called in unexpected situations,
301 // these all return false, since it is unlikely that the caller
302 // could fix them.
[email protected]6d42f152012-11-10 00:38:24303 //
304 // The database's page size is taken from |page_size_|. The
305 // existing database's |auto_vacuum| setting is lost (the
306 // possibility of corruption makes it unreliable to pull it from the
307 // existing database). To re-enable on the empty database requires
308 // running "PRAGMA auto_vacuum = 1;" then "VACUUM".
309 //
310 // NOTE(shess): For Android, SQLITE_DEFAULT_AUTOVACUUM is set to 1,
311 // so Raze() sets auto_vacuum to 1.
312 //
313 // TODO(shess): Raze() needs a connection so cannot clear SQLITE_NOTADB.
314 // TODO(shess): Bake auto_vacuum into Connection's API so it can
315 // just pick up the default.
[email protected]8e0c01282012-04-06 19:36:49316 bool Raze();
317 bool RazeWithTimout(base::TimeDelta timeout);
318
[email protected]41a97c812013-02-07 02:35:38319 // Breaks all outstanding transactions (as initiated by
[email protected]8d409412013-07-19 18:25:30320 // BeginTransaction()), closes the SQLite database, and poisons the
321 // object so that all future operations against the Connection (or
322 // its Statements) fail safely, without side effects.
[email protected]41a97c812013-02-07 02:35:38323 //
[email protected]8d409412013-07-19 18:25:30324 // This is intended as an alternative to Close() in error callbacks.
325 // Close() should still be called at some point.
326 void Poison();
327
328 // Raze() the database and Poison() the handle. Returns the return
329 // value from Raze().
330 // TODO(shess): Rename to RazeAndPoison().
[email protected]41a97c812013-02-07 02:35:38331 bool RazeAndClose();
332
[email protected]8d2e39e2013-06-24 05:55:08333 // Delete the underlying database files associated with |path|.
334 // This should be used on a database which has no existing
335 // connections. If any other connections are open to the same
336 // database, this could cause odd results or corruption (for
337 // instance if a hot journal is deleted but the associated database
338 // is not).
339 //
340 // Returns true if the database file and associated journals no
341 // longer exist, false otherwise. If the database has never
342 // existed, this will return true.
343 static bool Delete(const base::FilePath& path);
344
[email protected]e5ffd0e42009-09-11 21:30:56345 // Transactions --------------------------------------------------------------
346
347 // Transaction management. We maintain a virtual transaction stack to emulate
348 // nested transactions since sqlite can't do nested transactions. The
349 // limitation is you can't roll back a sub transaction: if any transaction
350 // fails, all transactions open will also be rolled back. Any nested
351 // transactions after one has rolled back will return fail for Begin(). If
352 // Begin() fails, you must not call Commit or Rollback().
353 //
354 // Normally you should use sql::Transaction to manage a transaction, which
355 // will scope it to a C++ context.
356 bool BeginTransaction();
357 void RollbackTransaction();
358 bool CommitTransaction();
359
[email protected]8d409412013-07-19 18:25:30360 // Rollback all outstanding transactions. Use with care, there may
361 // be scoped transactions on the stack.
362 void RollbackAllTransactions();
363
[email protected]e5ffd0e42009-09-11 21:30:56364 // Returns the current transaction nesting, which will be 0 if there are
365 // no open transactions.
366 int transaction_nesting() const { return transaction_nesting_; }
367
[email protected]8d409412013-07-19 18:25:30368 // Attached databases---------------------------------------------------------
369
370 // SQLite supports attaching multiple database files to a single
371 // handle. Attach the database in |other_db_path| to the current
372 // handle under |attachment_point|. |attachment_point| should only
373 // contain characters from [a-zA-Z0-9_].
374 //
375 // Note that calling attach or detach with an open transaction is an
376 // error.
377 bool AttachDatabase(const base::FilePath& other_db_path,
378 const char* attachment_point);
379 bool DetachDatabase(const char* attachment_point);
380
[email protected]e5ffd0e42009-09-11 21:30:56381 // Statements ----------------------------------------------------------------
382
383 // Executes the given SQL string, returning true on success. This is
384 // normally used for simple, 1-off statements that don't take any bound
385 // parameters and don't return any data (e.g. CREATE TABLE).
[email protected]9fe37552011-12-23 17:07:20386 //
[email protected]eff1fa522011-12-12 23:50:59387 // This will DCHECK if the |sql| contains errors.
[email protected]9fe37552011-12-23 17:07:20388 //
389 // Do not use ignore_result() to ignore all errors. Use
390 // ExecuteAndReturnErrorCode() and ignore only specific errors.
391 bool Execute(const char* sql) WARN_UNUSED_RESULT;
[email protected]e5ffd0e42009-09-11 21:30:56392
[email protected]eff1fa522011-12-12 23:50:59393 // Like Execute(), but returns the error code given by SQLite.
[email protected]9fe37552011-12-23 17:07:20394 int ExecuteAndReturnErrorCode(const char* sql) WARN_UNUSED_RESULT;
[email protected]eff1fa522011-12-12 23:50:59395
[email protected]e5ffd0e42009-09-11 21:30:56396 // Returns true if we have a statement with the given identifier already
397 // cached. This is normally not necessary to call, but can be useful if the
398 // caller has to dynamically build up SQL to avoid doing so if it's already
399 // cached.
400 bool HasCachedStatement(const StatementID& id) const;
401
402 // Returns a statement for the given SQL using the statement cache. It can
403 // take a nontrivial amount of work to parse and compile a statement, so
404 // keeping commonly-used ones around for future use is important for
405 // performance.
406 //
[email protected]eff1fa522011-12-12 23:50:59407 // If the |sql| has an error, an invalid, inert StatementRef is returned (and
408 // the code will crash in debug). The caller must deal with this eventuality,
409 // either by checking validity of the |sql| before calling, by correctly
410 // handling the return of an inert statement, or both.
[email protected]e5ffd0e42009-09-11 21:30:56411 //
412 // The StatementID and the SQL must always correspond to one-another. The
413 // ID is the lookup into the cache, so crazy things will happen if you use
414 // different SQL with the same ID.
415 //
416 // You will normally use the SQL_FROM_HERE macro to generate a statement
417 // ID associated with the current line of code. This gives uniqueness without
418 // you having to manage unique names. See StatementID above for more.
419 //
420 // Example:
[email protected]3273dce2010-01-27 16:08:08421 // sql::Statement stmt(connection_.GetCachedStatement(
422 // SQL_FROM_HERE, "SELECT * FROM foo"));
[email protected]e5ffd0e42009-09-11 21:30:56423 // if (!stmt)
424 // return false; // Error creating statement.
425 scoped_refptr<StatementRef> GetCachedStatement(const StatementID& id,
426 const char* sql);
427
[email protected]eff1fa522011-12-12 23:50:59428 // Used to check a |sql| statement for syntactic validity. If the statement is
429 // valid SQL, returns true.
430 bool IsSQLValid(const char* sql);
431
[email protected]e5ffd0e42009-09-11 21:30:56432 // Returns a non-cached statement for the given SQL. Use this for SQL that
433 // is only executed once or only rarely (there is overhead associated with
434 // keeping a statement cached).
435 //
436 // See GetCachedStatement above for examples and error information.
437 scoped_refptr<StatementRef> GetUniqueStatement(const char* sql);
438
439 // Info querying -------------------------------------------------------------
440
shess92a2ab12015-04-09 01:59:47441 // Returns true if the given table (or index) exists. Instead of
442 // test-then-create, callers should almost always prefer "CREATE TABLE IF NOT
443 // EXISTS" or "CREATE INDEX IF NOT EXISTS".
[email protected]765b44502009-10-02 05:01:42444 bool DoesTableExist(const char* table_name) const;
[email protected]e2cadec82011-12-13 02:00:53445 bool DoesIndexExist(const char* index_name) const;
446
[email protected]e5ffd0e42009-09-11 21:30:56447 // Returns true if a column with the given name exists in the given table.
[email protected]1ed78a32009-09-15 20:24:17448 bool DoesColumnExist(const char* table_name, const char* column_name) const;
[email protected]e5ffd0e42009-09-11 21:30:56449
450 // Returns sqlite's internal ID for the last inserted row. Valid only
451 // immediately after an insert.
tfarina720d4f32015-05-11 22:31:26452 int64_t GetLastInsertRowId() const;
[email protected]e5ffd0e42009-09-11 21:30:56453
[email protected]1ed78a32009-09-15 20:24:17454 // Returns sqlite's count of the number of rows modified by the last
455 // statement executed. Will be 0 if no statement has executed or the database
456 // is closed.
457 int GetLastChangeCount() const;
458
[email protected]e5ffd0e42009-09-11 21:30:56459 // Errors --------------------------------------------------------------------
460
461 // Returns the error code associated with the last sqlite operation.
462 int GetErrorCode() const;
463
[email protected]767718e52010-09-21 23:18:49464 // Returns the errno associated with GetErrorCode(). See
465 // SQLITE_LAST_ERRNO in SQLite documentation.
466 int GetLastErrno() const;
467
[email protected]e5ffd0e42009-09-11 21:30:56468 // Returns a pointer to a statically allocated string associated with the
469 // last sqlite operation.
470 const char* GetErrorMessage() const;
471
[email protected]92cd00a2013-08-16 11:09:58472 // Return a reproducible representation of the schema equivalent to
473 // running the following statement at a sqlite3 command-line:
474 // SELECT type, name, tbl_name, sql FROM sqlite_master ORDER BY 1, 2, 3, 4;
475 std::string GetSchema() const;
476
[email protected]74cdede2013-09-25 05:39:57477 // Clients which provide an error_callback don't see the
478 // error-handling at the end of OnSqliteError(). Expose to allow
479 // those clients to work appropriately with ScopedErrorIgnorer in
480 // tests.
481 static bool ShouldIgnoreSqliteError(int error);
482
shessc8cd2a162015-10-22 20:30:46483 // Collect various diagnostic information and post a crash dump to aid
484 // debugging. Dump rate per database is limited to prevent overwhelming the
485 // crash server.
486 void ReportDiagnosticInfo(int extended_error, Statement* stmt);
487
[email protected]e5ffd0e42009-09-11 21:30:56488 private:
[email protected]8d409412013-07-19 18:25:30489 // For recovery module.
490 friend class Recovery;
491
[email protected]4350e322013-06-18 22:18:10492 // Allow test-support code to set/reset error ignorer.
493 friend class ScopedErrorIgnorer;
494
[email protected]eff1fa522011-12-12 23:50:59495 // Statement accesses StatementRef which we don't want to expose to everybody
[email protected]e5ffd0e42009-09-11 21:30:56496 // (they should go through Statement).
497 friend class Statement;
498
shess58b8df82015-06-03 00:19:32499 friend class test::ScopedCommitHook;
500 friend class test::ScopedScalarFunction;
501 friend class test::ScopedMockTimeSource;
502
shessc8cd2a162015-10-22 20:30:46503 FRIEND_TEST_ALL_PREFIXES(SQLConnectionTest, CollectDiagnosticInfo);
shess9bf2c672015-12-18 01:18:08504 FRIEND_TEST_ALL_PREFIXES(SQLConnectionTest, GetAppropriateMmapSize);
ssid3be5b1ec2016-01-13 14:21:57505 FRIEND_TEST_ALL_PREFIXES(SQLConnectionTest, OnMemoryDump);
shessc8cd2a162015-10-22 20:30:46506 FRIEND_TEST_ALL_PREFIXES(SQLConnectionTest, RegisterIntentToUpload);
507
[email protected]765b44502009-10-02 05:01:42508 // Internal initialize function used by both Init and InitInMemory. The file
509 // name is always 8 bits since we want to use the 8-bit version of
510 // sqlite3_open. The string can also be sqlite's special ":memory:" string.
[email protected]fed734a2013-07-17 04:45:13511 //
512 // |retry_flag| controls retrying the open if the error callback
513 // addressed errors using RazeAndClose().
514 enum Retry {
515 NO_RETRY = 0,
516 RETRY_ON_POISON
517 };
518 bool OpenInternal(const std::string& file_name, Retry retry_flag);
[email protected]765b44502009-10-02 05:01:42519
[email protected]41a97c812013-02-07 02:35:38520 // Internal close function used by Close() and RazeAndClose().
521 // |forced| indicates that orderly-shutdown checks should not apply.
522 void CloseInternal(bool forced);
523
[email protected]35f7e5392012-07-27 19:54:50524 // Check whether the current thread is allowed to make IO calls, but only
525 // if database wasn't open in memory. Function is inlined to be a no-op in
526 // official build.
shessc8cd2a162015-10-22 20:30:46527 void AssertIOAllowed() const {
[email protected]35f7e5392012-07-27 19:54:50528 if (!in_memory_)
529 base::ThreadRestrictions::AssertIOAllowed();
530 }
531
[email protected]e2cadec82011-12-13 02:00:53532 // Internal helper for DoesTableExist and DoesIndexExist.
533 bool DoesTableOrIndexExist(const char* name, const char* type) const;
534
[email protected]4350e322013-06-18 22:18:10535 // Accessors for global error-ignorer, for injecting behavior during tests.
536 // See test/scoped_error_ignorer.h.
537 typedef base::Callback<bool(int)> ErrorIgnorerCallback;
538 static ErrorIgnorerCallback* current_ignorer_cb_;
[email protected]4350e322013-06-18 22:18:10539 static void SetErrorIgnorer(ErrorIgnorerCallback* ignorer);
540 static void ResetErrorIgnorer();
541
[email protected]e5ffd0e42009-09-11 21:30:56542 // A StatementRef is a refcounted wrapper around a sqlite statement pointer.
543 // Refcounting allows us to give these statements out to sql::Statement
544 // objects while also optionally maintaining a cache of compiled statements
545 // by just keeping a refptr to these objects.
546 //
547 // A statement ref can be valid, in which case it can be used, or invalid to
548 // indicate that the statement hasn't been created yet, has an error, or has
549 // been destroyed.
550 //
551 // The Connection may revoke a StatementRef in some error cases, so callers
552 // should always check validity before using.
[email protected]601dc6a2011-11-12 01:14:23553 class SQL_EXPORT StatementRef : public base::RefCounted<StatementRef> {
[email protected]e5ffd0e42009-09-11 21:30:56554 public:
[email protected]41a97c812013-02-07 02:35:38555 // |connection| is the sql::Connection instance associated with
556 // the statement, and is used for tracking outstanding statements
557 // and for error handling. Set to NULL for invalid or untracked
558 // refs. |stmt| is the actual statement, and should only be NULL
559 // to create an invalid ref. |was_valid| indicates whether the
560 // statement should be considered valid for diagnistic purposes.
561 // |was_valid| can be true for NULL |stmt| if the connection has
562 // been forcibly closed by an error handler.
563 StatementRef(Connection* connection, sqlite3_stmt* stmt, bool was_valid);
[email protected]e5ffd0e42009-09-11 21:30:56564
565 // When true, the statement can be used.
566 bool is_valid() const { return !!stmt_; }
567
[email protected]41a97c812013-02-07 02:35:38568 // When true, the statement is either currently valid, or was
569 // previously valid but the connection was forcibly closed. Used
570 // for diagnostic checks.
571 bool was_valid() const { return was_valid_; }
572
[email protected]b4c363b2013-01-17 13:11:17573 // If we've not been linked to a connection, this will be NULL.
574 // TODO(shess): connection_ can be NULL in case of GetUntrackedStatement(),
575 // which prevents Statement::OnError() from forwarding errors.
[email protected]e5ffd0e42009-09-11 21:30:56576 Connection* connection() const { return connection_; }
577
578 // Returns the sqlite statement if any. If the statement is not active,
579 // this will return NULL.
580 sqlite3_stmt* stmt() const { return stmt_; }
581
582 // Destroys the compiled statement and marks it NULL. The statement will
[email protected]41a97c812013-02-07 02:35:38583 // no longer be active. |forced| is used to indicate if orderly-shutdown
584 // checks should apply (see Connection::RazeAndClose()).
585 void Close(bool forced);
[email protected]e5ffd0e42009-09-11 21:30:56586
[email protected]35f7e5392012-07-27 19:54:50587 // Check whether the current thread is allowed to make IO calls, but only
588 // if database wasn't open in memory.
589 void AssertIOAllowed() { if (connection_) connection_->AssertIOAllowed(); }
590
[email protected]e5ffd0e42009-09-11 21:30:56591 private:
[email protected]877d55d2009-11-05 21:53:08592 friend class base::RefCounted<StatementRef>;
593
594 ~StatementRef();
595
[email protected]e5ffd0e42009-09-11 21:30:56596 Connection* connection_;
597 sqlite3_stmt* stmt_;
[email protected]41a97c812013-02-07 02:35:38598 bool was_valid_;
[email protected]e5ffd0e42009-09-11 21:30:56599
600 DISALLOW_COPY_AND_ASSIGN(StatementRef);
601 };
602 friend class StatementRef;
603
604 // Executes a rollback statement, ignoring all transaction state. Used
605 // internally in the transaction management code.
606 void DoRollback();
607
608 // Called by a StatementRef when it's being created or destroyed. See
609 // open_statements_ below.
610 void StatementRefCreated(StatementRef* ref);
611 void StatementRefDeleted(StatementRef* ref);
612
[email protected]2f496b42013-09-26 18:36:58613 // Called when a sqlite function returns an error, which is passed
614 // as |err|. The return value is the error code to be reflected
615 // back to client code. |stmt| is non-NULL if the error relates to
616 // an sql::Statement instance. |sql| is non-NULL if the error
617 // relates to non-statement sql code (Execute, for instance). Both
618 // can be NULL, but both should never be set.
619 // NOTE(shess): Originally, the return value was intended to allow
620 // error handlers to transparently convert errors into success.
621 // Unfortunately, transactions are not generally restartable, so
622 // this did not work out.
shess9e77283d2016-06-13 23:53:20623 int OnSqliteError(int err, Statement* stmt, const char* sql) const;
[email protected]faa604e2009-09-25 22:38:59624
[email protected]5b96f3772010-09-28 16:30:57625 // Like |Execute()|, but retries if the database is locked.
[email protected]9fe37552011-12-23 17:07:20626 bool ExecuteWithTimeout(const char* sql, base::TimeDelta ms_timeout)
627 WARN_UNUSED_RESULT;
[email protected]5b96f3772010-09-28 16:30:57628
shess9e77283d2016-06-13 23:53:20629 // Implementation helper for GetUniqueStatement() and GetUntrackedStatement().
630 // |tracking_db| is the db the resulting ref should register with for
631 // outstanding statement tracking, which should be |this| to track or NULL to
632 // not track.
633 scoped_refptr<StatementRef> GetStatementImpl(
634 sql::Connection* tracking_db, const char* sql) const;
635
636 // Helper for implementing const member functions. Like GetUniqueStatement(),
637 // except the StatementRef is not entered into |open_statements_|, so an
638 // outstanding StatementRef from this function can block closing the database.
639 // The StatementRef will not call OnSqliteError(), because that can call
640 // |error_callback_| which can close the database.
[email protected]2eec0a22012-07-24 01:59:58641 scoped_refptr<StatementRef> GetUntrackedStatement(const char* sql) const;
642
[email protected]579446c2013-12-16 18:36:52643 bool IntegrityCheckHelper(
644 const char* pragma_sql,
645 std::vector<std::string>* messages) WARN_UNUSED_RESULT;
646
shess58b8df82015-06-03 00:19:32647 // Record time spent executing explicit COMMIT statements.
648 void RecordCommitTime(const base::TimeDelta& delta);
649
650 // Record time in DML (Data Manipulation Language) statements such as INSERT
651 // or UPDATE outside of an explicit transaction. Due to implementation
652 // limitations time spent on DDL (Data Definition Language) statements such as
653 // ALTER and CREATE is not included.
654 void RecordAutoCommitTime(const base::TimeDelta& delta);
655
656 // Record all time spent on updating the database. This includes CommitTime()
657 // and AutoCommitTime(), plus any time spent spilling to the journal if
658 // transactions do not fit in cache.
659 void RecordUpdateTime(const base::TimeDelta& delta);
660
661 // Record all time spent running statements, including time spent doing
662 // updates and time spent on read-only queries.
663 void RecordQueryTime(const base::TimeDelta& delta);
664
665 // Record |delta| as query time if |read_only| (from sqlite3_stmt_readonly) is
666 // true, autocommit time if the database is not in a transaction, or update
667 // time if the database is in a transaction. Also records change count to
668 // EVENT_CHANGES_AUTOCOMMIT or EVENT_CHANGES_COMMIT.
669 void RecordTimeAndChanges(const base::TimeDelta& delta, bool read_only);
670
671 // Helper to return the current time from the time source.
672 base::TimeTicks Now() {
673 return clock_->Now();
674 }
675
shess7dbd4dee2015-10-06 17:39:16676 // Release page-cache memory if memory-mapped I/O is enabled and the database
677 // was changed. Passing true for |implicit_change_performed| allows
678 // overriding the change detection for cases like DDL (CREATE, DROP, etc),
679 // which do not participate in the total-rows-changed tracking.
680 void ReleaseCacheMemoryIfNeeded(bool implicit_change_performed);
681
shessc8cd2a162015-10-22 20:30:46682 // Returns the results of sqlite3_db_filename(), which should match the path
683 // passed to Open().
684 base::FilePath DbPath() const;
685
686 // Helper to prevent uploading too many diagnostic dumps for a given database,
687 // since every dump will likely show the same problem. Returns |true| if this
688 // function was not previously called for this database, and the persistent
689 // storage which tracks state was updated.
690 //
691 // |false| is returned if the function was previously called for this
692 // database, even across restarts. |false| is also returned if the persistent
693 // storage cannot be updated, possibly indicating problems requiring user or
694 // admin intervention, such as filesystem corruption or disk full. |false| is
695 // also returned if the persistent storage contains invalid data or is not
696 // readable.
697 //
698 // TODO(shess): It would make sense to reset the persistent state if the
699 // database is razed or recovered, or if the diagnostic code adds new
700 // capabilities.
701 bool RegisterIntentToUpload() const;
702
703 // Helper to collect diagnostic info for a corrupt database.
704 std::string CollectCorruptionInfo();
705
706 // Helper to collect diagnostic info for errors.
707 std::string CollectErrorInfo(int error, Statement* stmt) const;
708
shessd90aeea82015-11-13 02:24:31709 // Calculates a value appropriate to pass to "PRAGMA mmap_size = ". So errors
710 // can make it unsafe to map a file, so the file is read using regular I/O,
711 // with any errors causing 0 (don't map anything) to be returned. If the
712 // entire file is read without error, a large value is returned which will
713 // allow the entire file to be mapped in most cases.
714 //
715 // Results are recorded in the database's meta table for future reference, so
716 // the file should only be read through once.
717 size_t GetAppropriateMmapSize();
718
[email protected]e5ffd0e42009-09-11 21:30:56719 // The actual sqlite database. Will be NULL before Init has been called or if
720 // Init resulted in an error.
721 sqlite3* db_;
722
723 // Parameters we'll configure in sqlite before doing anything else. Zero means
724 // use the default value.
725 int page_size_;
726 int cache_size_;
727 bool exclusive_locking_;
[email protected]81a2a602013-07-17 19:10:36728 bool restrict_to_user_;
[email protected]e5ffd0e42009-09-11 21:30:56729
730 // All cached statements. Keeping a reference to these statements means that
731 // they'll remain active.
732 typedef std::map<StatementID, scoped_refptr<StatementRef> >
733 CachedStatementMap;
734 CachedStatementMap statement_cache_;
735
736 // A list of all StatementRefs we've given out. Each ref must register with
737 // us when it's created or destroyed. This allows us to potentially close
738 // any open statements when we encounter an error.
739 typedef std::set<StatementRef*> StatementRefSet;
740 StatementRefSet open_statements_;
741
742 // Number of currently-nested transactions.
743 int transaction_nesting_;
744
745 // True if any of the currently nested transactions have been rolled back.
746 // When we get to the outermost transaction, this will determine if we do
747 // a rollback instead of a commit.
748 bool needs_rollback_;
749
[email protected]35f7e5392012-07-27 19:54:50750 // True if database is open with OpenInMemory(), False if database is open
751 // with Open().
752 bool in_memory_;
753
[email protected]41a97c812013-02-07 02:35:38754 // |true| if the connection was closed using RazeAndClose(). Used
755 // to enable diagnostics to distinguish calls to never-opened
756 // databases (incorrect use of the API) from calls to once-valid
757 // databases.
758 bool poisoned_;
759
shess7dbd4dee2015-10-06 17:39:16760 // |true| if SQLite memory-mapped I/O is not desired for this connection.
761 bool mmap_disabled_;
762
763 // |true| if SQLite memory-mapped I/O was enabled for this connection.
764 // Used by ReleaseCacheMemoryIfNeeded().
765 bool mmap_enabled_;
766
767 // Used by ReleaseCacheMemoryIfNeeded() to track if new changes have happened
768 // since memory was last released.
769 int total_changes_at_last_release_;
770
[email protected]c3881b372013-05-17 08:39:46771 ErrorCallback error_callback_;
772
[email protected]210ce0af2013-05-15 09:10:39773 // Tag for auxiliary histograms.
774 std::string histogram_tag_;
[email protected]c088e3a32013-01-03 23:59:14775
shess58b8df82015-06-03 00:19:32776 // Linear histogram for RecordEvent().
777 base::HistogramBase* stats_histogram_;
778
779 // Histogram for tracking time taken in commit.
780 base::HistogramBase* commit_time_histogram_;
781
782 // Histogram for tracking time taken in autocommit updates.
783 base::HistogramBase* autocommit_time_histogram_;
784
785 // Histogram for tracking time taken in updates (including commit and
786 // autocommit).
787 base::HistogramBase* update_time_histogram_;
788
789 // Histogram for tracking time taken in all queries.
790 base::HistogramBase* query_time_histogram_;
791
792 // Source for timing information, provided to allow tests to inject time
793 // changes.
mostynbd82cd9952016-04-11 20:05:34794 std::unique_ptr<TimeSource> clock_;
shess58b8df82015-06-03 00:19:32795
ssid3be5b1ec2016-01-13 14:21:57796 // Stores the dump provider object when db is open.
mostynbd82cd9952016-04-11 20:05:34797 std::unique_ptr<ConnectionMemoryDumpProvider> memory_dump_provider_;
ssid3be5b1ec2016-01-13 14:21:57798
[email protected]e5ffd0e42009-09-11 21:30:56799 DISALLOW_COPY_AND_ASSIGN(Connection);
800};
801
802} // namespace sql
803
[email protected]f0a54b22011-07-19 18:40:21804#endif // SQL_CONNECTION_H_