1 // Copyright 2012 The Chromium Authors
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_DATABASE_H_
6 #define SQL_DATABASE_H_
17 #include "base/callback.h"
18 #include "base/component_export.h"
19 #include "base/containers/flat_map.h"
20 #include "base/dcheck_is_on.h"
21 #include "base/feature_list.h"
22 #include "base/gtest_prod_util.h"
23 #include "base/memory/raw_ptr.h"
24 #include "base/memory/ref_counted.h"
25 #include "base/sequence_checker.h"
26 #include "base/strings/string_piece.h"
27 #include "base/threading/scoped_blocking_call.h"
28 #include "base/types/pass_key.h"
29 #include "sql/internal_api_token.h"
30 #include "sql/sql_features.h"
31 #include "sql/sqlite_result_code.h"
32 #include "sql/sqlite_result_code_values.h"
33 #include "sql/statement_id.h"
34 #include "third_party/abseil-cpp/absl/types/optional.h"
36 // Forward declaration for SQLite structures. Headers in the public sql:: API
37 // must NOT include sqlite3.h.
44 namespace trace_event {
45 class ProcessMemoryDump;
46 } // namespace trace_event
49 namespace perfetto::protos::pbzero {
50 class ChromeSqlDiagnostics;
55 class DatabaseMemoryDumpProvider;
60 class ScopedErrorExpecter;
63 struct COMPONENT_EXPORT(SQL) DatabaseOptions {
64 // Default page size for newly created databases.
66 // Guaranteed to match SQLITE_DEFAULT_PAGE_SIZE.
67 static constexpr int kDefaultPageSize = 4096;
69 // If true, the database can only be opened by one process at a time.
71 // SQLite supports a locking protocol that allows multiple processes to safely
72 // operate on the same database at the same time. The locking protocol is used
73 // on every transaction, and comes with a small performance penalty.
75 // Setting this to true causes the locking protocol to be used once, when the
76 // database is opened. No other process will be able to access the database at
79 // More details at https://www.sqlite.org/pragma.html#pragma_locking_mode
81 // SQLite's locking protocol is summarized at
82 // https://www.sqlite.org/c3ref/io_methods.html
84 // Exclusive mode is strongly recommended. It reduces the I/O cost of setting
85 // up a transaction. It also removes the need of handling transaction failures
86 // due to lock contention.
87 bool exclusive_locking = true;
89 // If true, enables SQLite's Write-Ahead Logging (WAL).
91 // WAL integration is under development, and should not be used in shipping
92 // Chrome features yet. In particular, our custom database recovery code does
93 // not support the WAL log file.
95 // WAL mode is currently not fully supported on FuchsiaOS. It will only be
96 // turned on if the database is also using exclusive locking mode.
97 // (https://crbug.com/1082059)
99 // Note: Changing page size is not supported when in WAL mode. So running
100 // 'PRAGMA page_size = <new-size>' will result in no-ops.
102 // More details at https://www.sqlite.org/wal.html
104 base::FeatureList::IsEnabled(sql::features::kEnableWALModeByDefault);
106 // If true, transaction commit waits for data to reach persistent media.
108 // This is currently only meaningful on macOS. All other operating systems
109 // only support flushing directly to disk.
111 // If both `flush_to_media` and `wal_mode` are false, power loss can lead to
112 // database corruption.
114 // By default, SQLite considers that transactions commit when they reach the
115 // disk controller's memory. This guarantees durability in the event of
116 // software crashes, up to and including the operating system. In the event of
117 // power loss, SQLite may lose data. If `wal_mode` is false (SQLite uses a
118 // rollback journal), power loss can lead to database corruption.
120 // When this option is enabled, committing a transaction causes SQLite to wait
121 // until the data is written to the persistent media. This guarantees
122 // durability in the event of power loss, which is needed to guarantee the
123 // integrity of non-WAL databases.
124 bool flush_to_media = false;
126 // Database page size.
128 // New Chrome features should set an explicit page size in their
129 // DatabaseOptions initializers, even if they use the default page size. This
130 // makes it easier to track the page size used by the databases on the users'
133 // The value in this option is only applied to newly created databases. In
134 // other words, changing the value doesn't impact the databases that have
135 // already been created on the users' devices. So, changing the value in the
136 // code without a lot of work (re-creating existing databases) will result in
137 // inconsistent page sizes across the fleet of user devices, which will make
138 // it (even) more difficult to reason about database performance.
140 // Larger page sizes result in shallower B-trees, because they allow an inner
141 // page to hold more keys. On the flip side, larger page sizes may result in
142 // more I/O when making small changes to existing records.
144 // Must be a power of two between 512 and 65536 inclusive.
146 // TODO(pwnall): Replace the default with an invalid value after all
147 // sql::Database users explicitly initialize page_size.
148 int page_size = kDefaultPageSize;
150 // The size of in-memory cache, in pages.
152 // New Chrome features should set an explicit cache size in their
153 // DatabaseOptions initializers, even if they use the default cache size. This
154 // makes it easier to track the cache size used by the databases on the users'
155 // devices. The default page size of 4,096 bytes results in a cache size of
158 // SQLite's database cache will take up at most (`page_size` * `cache_size`)
161 // 0 invokes SQLite's default, which is currently to size up the cache to use
162 // exactly 2,048,000 bytes of RAM.
164 // TODO(pwnall): Replace the default with an invalid value after all
165 // sql::Database users explicitly initialize page_size.
168 // Stores mmap failures in the SQL schema, instead of the meta table.
170 // This option is strongly discouraged for new databases, and will eventually
173 // If this option is true, the mmap status is stored in the database schema.
174 // Like any other schema change, changing the mmap status invalidates all
175 // pre-compiled SQL statements.
176 bool mmap_alt_status_discouraged = false;
178 // If true, enables the enforcement of foreign key constraints.
180 // The use of foreign key constraints is discouraged for Chrome code. See
181 // README.md for details and recommended replacements.
183 // If this option is false, foreign key schema operations succeed, but foreign
184 // keys are not enforced. Foreign key enforcement can still be enabled later
185 // by executing PRAGMA foreign_keys=true. sql::Database() will eventually
186 // disallow executing arbitrary PRAGMA statements.
187 bool enable_foreign_keys_discouraged = false;
189 // If true, enables SQL views (a discouraged feature) for this database.
191 // The use of views is discouraged for Chrome code. See README.md for details
192 // and recommended replacements.
194 // If this option is false, CREATE VIEW and DROP VIEW succeed, but SELECT
195 // statements targeting views fail.
196 bool enable_views_discouraged = false;
198 // If true, enables virtual tables (a discouraged feature) for this database.
200 // The use of virtual tables is discouraged for Chrome code. See README.md for
201 // details and recommended replacements.
203 // If this option is false, CREATE VIRTUAL TABLE and DROP VIRTUAL TABLE
204 // succeed, but statements targeting virtual tables fail.
205 bool enable_virtual_tables_discouraged = false;
208 // Holds database diagnostics in a structured format.
209 struct COMPONENT_EXPORT(SQL) DatabaseDiagnostics {
210 DatabaseDiagnostics();
211 ~DatabaseDiagnostics();
213 using TraceProto = perfetto::protos::pbzero::ChromeSqlDiagnostics;
214 // Write a representation of this object into tracing proto.
215 void WriteIntoTrace(perfetto::TracedProto<TraceProto> context) const;
217 // This was the original error code that triggered the error callback. Should
218 // generally match `error_code`, but this isn't guaranteed by the code.
219 int reported_sqlite_error_code = 0;
221 // Corresponds to `Database::GetErrorCode()`.
224 // Corresponds to `Database::GetLastErrno()`.
227 // Corresponds to `Statement::GetSQLStatement()` of the problematic statement.
228 // This doesn't include the bound values, and therefore is free of any PII.
229 std::string sql_statement;
231 // The 'version' value stored in the user database's meta table, if it can be
232 // read. If we fail to read the version of the user database, it's left as 0.
235 // Most rows in 'sql_schema' have a non-NULL 'sql' column. Those rows' 'sql'
236 // contents are logged here, one element per row.
237 std::vector<std::string> schema_sql_rows;
239 // Some rows of 'sql_schema' have a NULL 'sql' column. They are typically
240 // autogenerated indices, like "sqlite_autoindex_downloads_slices_1". These
241 // are also logged here by their 'name' column, one element per row.
242 std::vector<std::string> schema_other_row_names;
244 // Sanity checks used for all errors.
245 bool has_valid_header = false;
246 bool has_valid_schema = false;
248 // Corresponds to `Database::GetErrorMessage()`.
249 std::string error_message;
252 // Handle to an open SQLite database.
254 // Instances of this class are not thread-safe. After construction, a Database
255 // instance should only be accessed from one sequence.
257 // When a Database instance goes out of scope, any uncommitted transactions are
259 class COMPONENT_EXPORT(SQL) Database {
261 class StatementRef; // Forward declaration, see real one below.
264 // Creates an instance that can receive Open() / OpenInMemory() calls.
266 // Some `options` members are only applied to newly created databases.
268 // Most operations on the new instance will fail until Open() / OpenInMemory()
270 explicit Database(DatabaseOptions options);
272 // This constructor is deprecated.
274 // When transitioning away from this default constructor, consider setting
275 // DatabaseOptions::explicit_locking to true. For historical reasons, this
276 // constructor results in DatabaseOptions::explicit_locking set to false.
278 // TODO(crbug.com/1126968): Remove this constructor after migrating all
279 // uses to the explicit constructor below.
282 Database(const Database&) = delete;
283 Database& operator=(const Database&) = delete;
284 Database(Database&&) = delete;
285 Database& operator=(Database&&) = delete;
288 // Allows mmapping to be disabled globally by default in the calling process.
289 // Must be called before any threads attempt to create a Database.
291 // TODO(crbug.com/1117049): Remove this global configuration.
292 static void DisableMmapByDefault();
294 // Pre-init configuration ----------------------------------------------------
296 // The page size that will be used when creating a new database.
297 int page_size() const { return options_.page_size; }
299 // Returns whether a database will be opened in WAL mode.
300 bool UseWALMode() const;
302 // Opt out of memory-mapped file I/O.
303 void set_mmap_disabled() { mmap_disabled_ = true; }
305 // Set an error-handling callback. On errors, the error number (and
306 // statement, if available) will be passed to the callback.
308 // If no callback is set, the default error-handling behavior is invoked. The
309 // default behavior is to LOGs the error and propagate the failure.
311 // In DCHECK-enabled builds, the default error-handling behavior currently
312 // DCHECKs on errors. This is not correct, because DCHECKs are supposed to
313 // cover invariants and never fail, whereas SQLite errors can surface even on
314 // correct usage, due to I/O errors and data corruption. At some point in the
315 // future, errors will not result in DCHECKs.
317 // The callback will be called on the sequence used for database operations.
318 // The callback will never be called after the Database instance is destroyed.
319 using ErrorCallback = base::RepeatingCallback<void(int, Statement*)>;
320 void set_error_callback(ErrorCallback callback) {
321 DCHECK(!callback.is_null()) << "Use reset_error_callback() explicitly";
322 DCHECK(error_callback_.is_null())
323 << "Overwriting previously set error callback";
324 error_callback_ = std::move(callback);
326 void reset_error_callback() { error_callback_.Reset(); }
328 // Developer-friendly database ID used in logging output and memory dumps.
329 void set_histogram_tag(const std::string& tag);
331 // Asks SQLite to perform a full integrity check on the database.
333 // Returns true if the integrity check was completed successfully. Success
334 // does not necessarily entail that the database is healthy. Finding
335 // corruption and reporting it in `messages` counts as success.
337 // If the method returns true, `messages` is populated with a list of
338 // diagnostic messages. If the integrity check finds no errors, `messages`
339 // will contain exactly one "ok" string. This unusual API design is explained
340 // by the fact that SQLite exposes integrity check functionality as a PRAGMA,
341 // and the PRAGMA returns "ok" in case of success.
342 bool FullIntegrityCheck(std::vector<std::string>* messages);
344 // Meant to be called from a client error callback so that it's able to
345 // get diagnostic information about the database. `diagnostics` is an optional
346 // out parameter. If `diagnostics` is defined, this method populates all of
348 std::string GetDiagnosticInfo(int extended_error,
349 Statement* statement,
350 DatabaseDiagnostics* diagnostics = nullptr);
352 // Reports memory usage into provided memory dump with the given name.
353 bool ReportMemoryUsage(base::trace_event::ProcessMemoryDump* pmd,
354 const std::string& dump_name);
356 // Initialization ------------------------------------------------------------
358 // Opens or creates a database on disk.
360 // `db_file_path` points to the file storing database pages. Other files
361 // associated with the database (rollback journal, write-ahead log,
362 // shared-memory file) may be created.
364 // Returns true in case of success, false in case of failure.
365 [[nodiscard]] bool Open(const base::FilePath& db_file_path);
367 // Alternative to Open() that creates an in-memory database.
369 // Returns true in case of success, false in case of failure.
371 // The memory associated with the database will be released when the database
373 [[nodiscard]] bool OpenInMemory();
375 // Alternative to Open() that creates a temporary on-disk database.
377 // Returns true in case of success, false in case of failure.
379 // The files associated with the temporary database will be deleted when the
380 // database is closed.
381 [[nodiscard]] bool OpenTemporary(base::PassKey<Recovery>);
383 // Returns true if the database has been successfully opened.
384 bool is_open() const { return static_cast<bool>(db_); }
386 // Closes the database. This is automatically performed on destruction for
387 // you, but this allows you to close the database early. You must not call
388 // any other functions after closing it. It is permissable to call Close on
389 // an uninitialized or already-closed database.
392 // Hints the file system that the database will be accessed soon.
394 // This method should be called on databases that are on the critical path to
395 // Chrome startup. Informing the filesystem about our expected access pattern
396 // early on reduces the likelihood that we'll be blocked on disk I/O. This has
397 // a high impact on startup time.
399 // This method should not be used for non-critical databases. While using it
400 // will likely improve micro-benchmarks involving one specific database,
401 // overuse risks randomizing the disk I/O scheduler, slowing down Chrome
405 // Release all non-essential memory associated with this database connection.
408 // Raze the database to the ground. This approximates creating a
409 // fresh database from scratch, within the constraints of SQLite's
410 // locking protocol (locks and open handles can make doing this with
411 // filesystem operations problematic). Returns true if the database
414 // false is returned if the database is locked by some other
417 // NOTE(shess): Raze() will DCHECK in the following situations:
418 // - database is not open.
419 // - the database has a transaction open.
420 // - a SQLite issue occurs which is structural in nature (like the
421 // statements used are broken).
422 // Since Raze() is expected to be called in unexpected situations,
423 // these all return false, since it is unlikely that the caller
426 // The database's page size is taken from |options_.page_size|. The
427 // existing database's |auto_vacuum| setting is lost (the
428 // possibility of corruption makes it unreliable to pull it from the
429 // existing database). To re-enable on the empty database requires
430 // running "PRAGMA auto_vacuum = 1;" then "VACUUM".
432 // NOTE(shess): For Android, SQLITE_DEFAULT_AUTOVACUUM is set to 1,
433 // so Raze() sets auto_vacuum to 1.
435 // TODO(shess): Raze() needs a database so cannot clear SQLITE_NOTADB.
436 // TODO(shess): Bake auto_vacuum into Database's API so it can
437 // just pick up the default.
440 // Breaks all outstanding transactions (as initiated by
441 // BeginTransaction()), closes the SQLite database, and poisons the
442 // object so that all future operations against the Database (or
443 // its Statements) fail safely, without side effects.
445 // This is intended as an alternative to Close() in error callbacks.
446 // Close() should still be called at some point.
449 // Raze() the database and Poison() the handle. Returns the return
450 // value from Raze().
451 // TODO(shess): Rename to RazeAndPoison().
454 // Delete the underlying database files associated with |path|. This should be
455 // used on a database which is not opened by any Database instance. Open
456 // Database instances pointing to the database can cause odd results or
457 // corruption (for instance if a hot journal is deleted but the associated
460 // Returns true if the database file and associated journals no
461 // longer exist, false otherwise. If the database has never
462 // existed, this will return true.
463 static bool Delete(const base::FilePath& path);
465 // Transactions --------------------------------------------------------------
467 // Transaction management. We maintain a virtual transaction stack to emulate
468 // nested transactions since sqlite can't do nested transactions. The
469 // limitation is you can't roll back a sub transaction: if any transaction
470 // fails, all transactions open will also be rolled back. Any nested
471 // transactions after one has rolled back will return fail for Begin(). If
472 // Begin() fails, you must not call Commit or Rollback().
474 // Normally you should use sql::Transaction to manage a transaction, which
475 // will scope it to a C++ context.
476 bool BeginTransaction();
477 void RollbackTransaction();
478 bool CommitTransaction();
480 // Rollback all outstanding transactions. Use with care, there may
481 // be scoped transactions on the stack.
482 void RollbackAllTransactions();
484 bool HasActiveTransactions() const {
485 DCHECK_GE(transaction_nesting_, 0);
486 return transaction_nesting_ > 0;
489 // Deprecated in favor of HasActiveTransactions().
491 // Returns the current transaction nesting, which will be 0 if there are
492 // no open transactions.
493 int transaction_nesting() const { return transaction_nesting_; }
495 // Attached databases---------------------------------------------------------
497 // Attaches an existing database to this connection.
499 // `attachment_point` must only contain lowercase letters.
501 // Attachment APIs are only exposed for use in recovery. General use is
502 // discouraged in Chrome. The README has more details.
504 // On the SQLite version shipped with Chrome (3.21+, Oct 2017), databases can
505 // be attached while a transaction is opened. However, these databases cannot
506 // be detached until the transaction is committed or aborted.
507 bool AttachDatabase(const base::FilePath& other_db_path,
508 base::StringPiece attachment_point,
511 // Detaches a database that was previously attached with AttachDatabase().
513 // `attachment_point` must match the argument of a previously successsful
514 // AttachDatabase() call.
516 // Attachment APIs are only exposed for use in recovery. General use is
517 // discouraged in Chrome. The README has more details.
518 bool DetachDatabase(base::StringPiece attachment_point, InternalApiToken);
520 // Statements ----------------------------------------------------------------
522 // Executes a SQL statement. Returns true for success, and false for failure.
524 // `sql` should be a single SQL statement. Production code should not execute
525 // multiple SQL statements at once, to facilitate crash debugging. Test code
526 // should use ExecuteScriptForTesting().
528 // `sql` cannot have parameters. Statements with parameters can be handled by
529 // sql::Statement. See GetCachedStatement() and GetUniqueStatement().
530 [[nodiscard]] bool Execute(const char* sql);
532 // Executes a sequence of SQL statements.
534 // Returns true if all statements execute successfully. If a statement fails,
535 // stops and returns false. Calls should be wrapped in ASSERT_TRUE().
537 // The database's error handler is not invoked when errors occur. This method
538 // is a convenience for setting up a complex on-disk database state, such as
539 // an old schema version with test contents.
540 [[nodiscard]] bool ExecuteScriptForTesting(const char* sql_script);
542 // Returns a statement for the given SQL using the statement cache. It can
543 // take a nontrivial amount of work to parse and compile a statement, so
544 // keeping commonly-used ones around for future use is important for
547 // The SQL_FROM_HERE macro is the recommended way of generating a StatementID.
548 // Code that generates custom IDs must ensure that a StatementID is never used
549 // for different SQL statements. Failing to meet this requirement results in
550 // incorrect behavior, and should be caught by a DCHECK.
552 // The SQL statement passed in |sql| must match the SQL statement reported
553 // back by SQLite. Mismatches are caught by a DCHECK, so any code that has
554 // automated test coverage or that was manually tested on a DCHECK build will
555 // not exhibit this problem. Mismatches generally imply that the statement
556 // passed in has extra whitespace or comments surrounding it, which waste
557 // storage and CPU cycles.
559 // If the |sql| has an error, an invalid, inert StatementRef is returned (and
560 // the code will crash in debug). The caller must deal with this eventuality,
561 // either by checking validity of the |sql| before calling, by correctly
562 // handling the return of an inert statement, or both.
565 // sql::Statement stmt(database_.GetCachedStatement(
566 // SQL_FROM_HERE, "SELECT * FROM foo"));
568 // return false; // Error creating statement.
569 scoped_refptr<StatementRef> GetCachedStatement(StatementID id,
572 // Used to check a |sql| statement for syntactic validity. If the statement is
573 // valid SQL, returns true.
574 bool IsSQLValid(const char* sql);
576 // Returns a non-cached statement for the given SQL. Use this for SQL that
577 // is only executed once or only rarely (there is overhead associated with
578 // keeping a statement cached).
580 // See GetCachedStatement above for examples and error information.
581 scoped_refptr<StatementRef> GetUniqueStatement(const char* sql);
583 // Returns a non-cached statement same as `GetUniqueStatement()`, except
584 // returns an invalid statement if the statement makes direct changes to the
585 // database file. This readonly check does not include changes made by
586 // application-defined functions. See more at:
587 // https://www.sqlite.org/c3ref/stmt_readonly.html.
588 scoped_refptr<Database::StatementRef> GetReadonlyStatement(const char* sql);
590 // Performs a passive checkpoint on the main attached database if it is in
591 // WAL mode. Returns true if the checkpoint was successful and false in case
592 // of an error. It is a no-op if the database is not in WAL mode.
594 // Note: Checkpointing is a very slow operation and will block any writes
595 // until it is finished. Please use with care.
596 bool CheckpointDatabase();
598 // Info querying -------------------------------------------------------------
600 // Returns true if the given structure exists. Instead of test-then-create,
601 // callers should almost always prefer the "IF NOT EXISTS" version of the
603 bool DoesIndexExist(base::StringPiece index_name);
604 bool DoesTableExist(base::StringPiece table_name);
605 bool DoesViewExist(base::StringPiece table_name);
607 // Returns true if a column with the given name exists in the given table.
609 // Calling this method on a VIEW returns an unspecified result.
611 // This should only be used by migration code for legacy features that do not
612 // use MetaTable, and need an alternative way of figuring out the database's
614 bool DoesColumnExist(const char* table_name, const char* column_name);
616 // Returns sqlite's internal ID for the last inserted row. Valid only
617 // immediately after an insert.
618 int64_t GetLastInsertRowId() const;
620 // Returns sqlite's count of the number of rows modified by the last
621 // statement executed. Will be 0 if no statement has executed or the database
623 int64_t GetLastChangeCount();
625 // Approximates the amount of memory used by SQLite for this database.
627 // This measures the memory used for the page cache (most likely the biggest
628 // consumer), database schema, and prepared statements.
630 // The memory used by the page cache can be recovered by calling TrimMemory(),
631 // which will cause SQLite to drop the page cache.
632 int GetMemoryUsage();
634 // Errors --------------------------------------------------------------------
636 // Returns the error code associated with the last sqlite operation.
637 int GetErrorCode() const;
639 // Returns the errno associated with GetErrorCode(). See
640 // SQLITE_LAST_ERRNO in SQLite documentation.
641 int GetLastErrno() const;
643 // Returns a pointer to a statically allocated string associated with the
644 // last sqlite operation.
645 const char* GetErrorMessage() const;
647 // Return a reproducible representation of the schema equivalent to
648 // running the following statement at a sqlite3 command-line:
649 // SELECT type, name, tbl_name, sql FROM sqlite_schema ORDER BY 1, 2, 3, 4;
650 std::string GetSchema();
652 // Returns |true| if there is an error expecter (see SetErrorExpecter), and
653 // that expecter returns |true| when passed |error|. Clients which provide an
654 // |error_callback| should use IsExpectedSqliteError() to check for unexpected
655 // errors; if one is detected, DLOG(DCHECK) is generally appropriate (see
656 // OnSqliteError implementation).
657 static bool IsExpectedSqliteError(int sqlite_error_code);
659 // Computes the path of a database's rollback journal.
661 // The journal file is created at the beginning of the database's first
662 // transaction. The file may be removed and re-created between transactions,
663 // depending on whether the database is opened in exclusive mode, and on
664 // configuration options. The journal file does not exist when the database
665 // operates in WAL mode.
667 // This is intended for internal use and tests. To preserve our ability to
668 // iterate on our SQLite configuration, features must avoid relying on
669 // the existence of specific files.
670 static base::FilePath JournalPath(const base::FilePath& db_path);
672 // Computes the path of a database's write-ahead log (WAL).
674 // The WAL file exists while a database is opened in WAL mode.
676 // This is intended for internal use and tests. To preserve our ability to
677 // iterate on our SQLite configuration, features must avoid relying on
678 // the existence of specific files.
679 static base::FilePath WriteAheadLogPath(const base::FilePath& db_path);
681 // Computes the path of a database's shared memory (SHM) file.
683 // The SHM file is used to coordinate between multiple processes using the
684 // same database in WAL mode. Thus, this file only exists for databases using
685 // WAL and not opened in exclusive mode.
687 // This is intended for internal use and tests. To preserve our ability to
688 // iterate on our SQLite configuration, features must avoid relying on
689 // the existence of specific files.
690 static base::FilePath SharedMemoryFilePath(const base::FilePath& db_path);
692 // Internal state accessed by other classes in //sql.
693 sqlite3* db(InternalApiToken) const { return db_; }
694 bool poisoned(InternalApiToken) const { return poisoned_; }
696 // Interface with sql::test::ScopedErrorExpecter.
697 using ScopedErrorExpecterCallback = base::RepeatingCallback<bool(int)>;
698 static void SetScopedErrorExpecter(ScopedErrorExpecterCallback* expecter,
699 base::PassKey<test::ScopedErrorExpecter>);
700 static void ResetScopedErrorExpecter(
701 base::PassKey<test::ScopedErrorExpecter>);
704 // Statement accesses StatementRef which we don't want to expose to everybody
705 // (they should go through Statement).
706 friend class Statement;
708 FRIEND_TEST_ALL_PREFIXES(SQLDatabaseTest, CachedStatement);
709 FRIEND_TEST_ALL_PREFIXES(SQLDatabaseTest, CollectDiagnosticInfo);
710 FRIEND_TEST_ALL_PREFIXES(SQLDatabaseTest, ComputeMmapSizeForOpen);
711 FRIEND_TEST_ALL_PREFIXES(SQLDatabaseTest, ComputeMmapSizeForOpenAltStatus);
712 FRIEND_TEST_ALL_PREFIXES(SQLDatabaseTest, OnMemoryDump);
713 FRIEND_TEST_ALL_PREFIXES(SQLDatabaseTest, RegisterIntentToUpload);
714 FRIEND_TEST_ALL_PREFIXES(SQLiteFeaturesTest, WALNoClose);
715 FRIEND_TEST_ALL_PREFIXES(SQLEmptyPathDatabaseTest, EmptyPathTest);
717 // Enables a special behavior for OpenInternal().
718 enum class OpenMode {
719 // No special behavior.
722 // Retry if the database error handler is invoked and closes the database.
723 // Database error handlers that call RazeAndClose() take advantage of this.
726 // Open an in-memory database. Used by OpenInMemory().
729 // Open a temporary database. Used by OpenTemporary().
733 // Implements Open(), OpenInMemory(), and OpenTemporary().
735 // `db_file_path` is a UTF-8 path to the file storing the database pages. The
736 // path must be empty if `mode` is kTemporary. The path must be the SQLite
737 // magic memory path string if `mode` is kMemory.
738 bool OpenInternal(const std::string& file_name, OpenMode mode);
740 // Configures the underlying sqlite3* object via sqlite3_db_config().
742 // To minimize the number of possible SQLite code paths executed in Chrome,
743 // this method must be called right after the underlying sqlite3* object is
744 // obtained from sqlite3_open*(), before any other sqlite3_*() methods are
745 // called on the object.
746 void ConfigureSqliteDatabaseObject();
748 // Internal close function used by Close() and RazeAndClose().
749 // |forced| indicates that orderly-shutdown checks should not apply.
750 void CloseInternal(bool forced);
752 // Construct a ScopedBlockingCall to annotate IO calls, but only if
753 // database wasn't open in memory. ScopedBlockingCall uses |from_here| to
754 // declare its blocking execution scope (see https://www.crbug/934302).
755 void InitScopedBlockingCall(
756 const base::Location& from_here,
757 absl::optional<base::ScopedBlockingCall>* scoped_blocking_call) const {
759 scoped_blocking_call->emplace(from_here, base::BlockingType::MAY_BLOCK);
762 // Internal helper for Does*Exist() functions.
763 bool DoesSchemaItemExist(base::StringPiece name, base::StringPiece type);
765 // Used to implement the interface with sql::test::ScopedErrorExpecter.
766 static ScopedErrorExpecterCallback* current_expecter_cb_;
768 // A StatementRef is a refcounted wrapper around a sqlite statement pointer.
769 // Refcounting allows us to give these statements out to sql::Statement
770 // objects while also optionally maintaining a cache of compiled statements
771 // by just keeping a refptr to these objects.
773 // A statement ref can be valid, in which case it can be used, or invalid to
774 // indicate that the statement hasn't been created yet, has an error, or has
777 // The Database may revoke a StatementRef in some error cases, so callers
778 // should always check validity before using.
779 class COMPONENT_EXPORT(SQL) StatementRef
780 : public base::RefCounted<StatementRef> {
782 REQUIRE_ADOPTION_FOR_REFCOUNTED_TYPE();
784 // |database| is the sql::Database instance associated with
785 // the statement, and is used for tracking outstanding statements
786 // and for error handling. Set to nullptr for invalid refs.
787 // |stmt| is the actual statement, and should only be null
788 // to create an invalid ref. |was_valid| indicates whether the
789 // statement should be considered valid for diagnostic purposes.
790 // |was_valid| can be true for a null |stmt| if the Database has
791 // been forcibly closed by an error handler.
792 StatementRef(Database* database, sqlite3_stmt* stmt, bool was_valid);
794 StatementRef(const StatementRef&) = delete;
795 StatementRef& operator=(const StatementRef&) = delete;
796 StatementRef(StatementRef&&) = delete;
797 StatementRef& operator=(StatementRef&&) = delete;
799 // When true, the statement can be used.
800 bool is_valid() const { return !!stmt_; }
802 // When true, the statement is either currently valid, or was
803 // previously valid but the database was forcibly closed. Used
804 // for diagnostic checks.
805 bool was_valid() const { return was_valid_; }
807 // If we've not been linked to a database, this will be null.
808 Database* database() const { return database_; }
810 // Returns the sqlite statement if any. If the statement is not active,
811 // this will return nullptr.
812 sqlite3_stmt* stmt() const { return stmt_; }
814 // Destroys the compiled statement and sets it to nullptr. The statement
815 // will no longer be active. |forced| is used to indicate if
816 // orderly-shutdown checks should apply (see Database::RazeAndClose()).
817 void Close(bool forced);
819 // Construct a ScopedBlockingCall to annotate IO calls, but only if
820 // database wasn't open in memory. ScopedBlockingCall uses |from_here| to
821 // declare its blocking execution scope (see https://www.crbug/934302).
822 void InitScopedBlockingCall(
823 const base::Location& from_here,
824 absl::optional<base::ScopedBlockingCall>* scoped_blocking_call) const {
826 database_->InitScopedBlockingCall(from_here, scoped_blocking_call);
830 friend class base::RefCounted<StatementRef>;
834 raw_ptr<Database> database_;
835 raw_ptr<sqlite3_stmt> stmt_;
838 friend class StatementRef;
840 // Executes a rollback statement, ignoring all transaction state. Used
841 // internally in the transaction management code.
844 // Called by a StatementRef when it's being created or destroyed. See
845 // open_statements_ below.
846 void StatementRefCreated(StatementRef* ref);
847 void StatementRefDeleted(StatementRef* ref);
849 // Used by sql:: internals to report a SQLite error related to this database.
851 // `sqlite_error_code` contains the error code reported by SQLite. Possible
852 // values are documented at https://www.sqlite.org/rescode.html
854 // `statement` is non-null if the error is associated with a sql::Statement.
855 // Otherwise, `sql_statement` will be a non-null string pointing to a
856 // statically-allocated (valid for the entire duration of the process) buffer
857 // pointing to either a SQL statement or a SQL comment (starting with "-- ")
858 // pointing to a "sqlite3_" function name.
859 void OnSqliteError(SqliteErrorCode sqlite_error_code,
860 Statement* statement,
861 const char* sql_statement);
863 // Like Execute(), but returns a SQLite result code.
865 // This method returns SqliteResultCode::kOk or a SQLite error code. In other
866 // words, it never returns SqliteResultCode::{kDone, kRow}.
868 // This method is only exposed to the Database implementation. Code that uses
869 // sql::Database should not be concerned with SQLite result codes.
870 [[nodiscard]] SqliteResultCode ExecuteAndReturnResultCode(const char* sql);
872 // Like |Execute()|, but retries if the database is locked.
873 [[nodiscard]] bool ExecuteWithTimeout(const char* sql,
874 base::TimeDelta ms_timeout);
876 // Implementation helper for GetUniqueStatement() and GetCachedStatement().
877 scoped_refptr<StatementRef> GetStatementImpl(const char* sql,
880 // Release page-cache memory if memory-mapped I/O is enabled and the database
881 // was changed. Passing true for |implicit_change_performed| allows
882 // overriding the change detection for cases like DDL (CREATE, DROP, etc),
883 // which do not participate in the total-rows-changed tracking.
884 void ReleaseCacheMemoryIfNeeded(bool implicit_change_performed);
886 // Returns the results of sqlite3_db_filename(), which should match the path
888 base::FilePath DbPath() const;
890 // Helper to collect diagnostic info for a corrupt database.
891 std::string CollectCorruptionInfo();
893 // Helper to collect diagnostic info for errors. `diagnostics` is an optional
894 // out parameter. If `diagnostics` is defined, this method populates SOME of
895 // its fields. Some of the fields are left unmodified for the caller.
896 std::string CollectErrorInfo(int sqlite_error_code,
898 DatabaseDiagnostics* diagnostics) const;
900 // The size of the memory mapping that SQLite should use for this database.
902 // The return value follows the semantics of "PRAGMA mmap_size". In
903 // particular, zero (0) means memory-mapping should be disabled, and the value
904 // is capped by SQLITE_MAX_MMAP_SIZE. More details at
905 // https://www.sqlite.org/pragma.html#pragma_mmap_size
907 // "Memory-mapped access" is usually shortened to "mmap", which is the name of
908 // the POSIX system call used to implement. The same principles apply on
909 // Windows, but its more-descriptive API names don't make for good shorthands.
911 // When mmap is enabled, SQLite attempts to use the memory-mapped area (by
912 // calling xFetch() in the VFS file API) instead of requesting a database page
913 // buffer from the pager and reading (via xRead() in the VFS API) into it.
914 // When this works out, the database page cache ends up only storing pages
915 // whose contents has been modified. More details at
916 // https://sqlite.org/mmap.html
918 // I/O errors on memory-mapped files result in crashes in Chrome. POSIX
919 // systems signal SIGSEGV or SIGBUS on I/O errors in mmap-ed files. Windows
920 // raises the EXECUTE_IN_PAGE_ERROR strucuted exception in this case. Chrome
921 // does not catch signals or structured exceptions.
923 // In order to avoid crashes, this method attempts to read the file using
924 // regular I/O, and returns 0 (no mmap) if it encounters any error.
925 size_t ComputeMmapSizeForOpen();
927 // Helpers for ComputeMmapSizeForOpen().
928 bool GetMmapAltStatus(int64_t* status);
929 bool SetMmapAltStatus(int64_t status);
931 // sqlite3_prepare_v3() flags for this database.
932 int SqlitePrepareFlags() const;
934 // Returns a SQLite VFS interface pointer to the file storing database pages.
936 // Returns null if the database is not backed by a VFS file. This is always
937 // the case for in-memory databases. Temporary databases (only used by sq
938 // ::Recovery) start without a backing VFS file, and only get a file when they
939 // outgrow their page cache.
941 // This method must only be called while the database is successfully opened.
942 sqlite3_file* GetSqliteVfsFile();
944 // Will eventually be checked on all methods. See https://crbug.com/1306694
945 SEQUENCE_CHECKER(sequence_checker_);
947 // The actual sqlite database. Will be null before Init has been called or if
948 // Init resulted in an error.
949 sqlite3* db_ = nullptr;
951 // TODO(shuagga@microsoft.com): Make `options_` const after removing all
953 DatabaseOptions options_;
955 // Holds references to all cached statements so they remain active.
957 // flat_map is appropriate here because the codebase has ~400 cached
958 // statements, and each statement is at most one insertion in the map
959 // throughout a process' lifetime.
960 base::flat_map<StatementID, scoped_refptr<StatementRef>> statement_cache_;
962 // A list of all StatementRefs we've given out. Each ref must register with
963 // us when it's created or destroyed. This allows us to potentially close
964 // any open statements when we encounter an error.
965 std::set<StatementRef*> open_statements_;
967 // Number of currently-nested transactions.
968 int transaction_nesting_ = 0;
970 // True if any of the currently nested transactions have been rolled back.
971 // When we get to the outermost transaction, this will determine if we do
972 // a rollback instead of a commit.
973 bool needs_rollback_ = false;
975 // True if database is open with OpenInMemory(), False if database is open
977 bool in_memory_ = false;
979 // |true| if the Database was closed using RazeAndClose(). Used
980 // to enable diagnostics to distinguish calls to never-opened
981 // databases (incorrect use of the API) from calls to once-valid
983 bool poisoned_ = false;
985 // |true| if SQLite memory-mapped I/O is not desired for this database.
988 // |true| if SQLite memory-mapped I/O was enabled for this database.
989 // Used by ReleaseCacheMemoryIfNeeded().
990 bool mmap_enabled_ = false;
992 // Used by ReleaseCacheMemoryIfNeeded() to track if new changes have happened
993 // since memory was last released.
994 int64_t total_changes_at_last_release_ = 0;
996 // Called when a SQLite error occurs.
998 // This callback may be null, in which case errors are handled using a default
1001 // This callback must never be exposed outside this Database instance. This is
1002 // a straight-forward way to guarantee that this callback will not be called
1003 // after the Database instance goes out of scope. set_error_callback() makes
1005 ErrorCallback error_callback_;
1007 // Developer-friendly database ID used in logging output and memory dumps.
1008 std::string histogram_tag_;
1010 // Stores the dump provider object when db is open.
1011 std::unique_ptr<DatabaseMemoryDumpProvider> memory_dump_provider_;
1016 #endif // SQL_DATABASE_H_