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/component_export.h"
18 #include "base/containers/flat_map.h"
19 #include "base/dcheck_is_on.h"
20 #include "base/feature_list.h"
21 #include "base/files/file_path.h"
22 #include "base/functional/callback.h"
23 #include "base/gtest_prod_util.h"
24 #include "base/memory/raw_ptr.h"
25 #include "base/memory/raw_ptr_exclusion.h"
26 #include "base/memory/ref_counted.h"
27 #include "base/sequence_checker.h"
28 #include "base/strings/string_piece.h"
29 #include "base/threading/scoped_blocking_call.h"
30 #include "base/types/pass_key.h"
31 #include "sql/internal_api_token.h"
32 #include "sql/sql_features.h"
33 #include "sql/sqlite_result_code.h"
34 #include "sql/sqlite_result_code_values.h"
35 #include "sql/statement_id.h"
36 #include "third_party/abseil-cpp/absl/types/optional.h"
38 // Forward declaration for SQLite structures. Headers in the public sql:: API
39 // must NOT include sqlite3.h.
44 namespace base::trace_event {
45 class ProcessMemoryDump;
46 } // namespace base::trace_event
48 namespace perfetto::protos::pbzero {
49 class ChromeSqlDiagnostics;
54 class DatabaseMemoryDumpProvider;
59 class ScopedErrorExpecter;
62 struct COMPONENT_EXPORT(SQL) DatabaseOptions {
63 // Default page size for newly created databases.
65 // Guaranteed to match SQLITE_DEFAULT_PAGE_SIZE.
66 static constexpr int kDefaultPageSize = 4096;
68 // If true, the database can only be opened by one process at a time.
70 // SQLite supports a locking protocol that allows multiple processes to safely
71 // operate on the same database at the same time. The locking protocol is used
72 // on every transaction, and comes with a small performance penalty.
74 // Setting this to true causes the locking protocol to be used once, when the
75 // database is opened. No other SQLite process will be able to access the
76 // database at the same time. Note that this uses OS-level
77 // advisory/cooperative locking, so this does not protect the database file
78 // from uncooperative processes.
80 // More details at https://www.sqlite.org/pragma.html#pragma_locking_mode
82 // SQLite's locking protocol is summarized at
83 // https://www.sqlite.org/c3ref/io_methods.html
85 // Exclusive mode is strongly recommended. It reduces the I/O cost of setting
86 // up a transaction. It also removes the need of handling transaction failures
87 // due to lock contention.
88 bool exclusive_locking = true;
90 // If true, enables exclusive=true vfs URI parameter on the database file.
91 // This is only supported on Windows.
93 // If this option is true then the database file cannot be opened by any
94 // processes on the system until the database has been closed. Note, this is
95 // not the same as `exclusive_locking` above, which refers to
96 // advisory/cooperative locks. This option sets file handle sharing attributes
97 // to prevent the database files from being opened from any process including
98 // being opened a second time by the hosting process.
100 // A side effect of setting this flag is that the database cannot be
101 // preloaded. If you would like to set this flag on a preloaded database,
102 // please reach out to a //sql owner.
104 // This option is experimental and will be merged into the `exclusive_locking`
105 // option above if proven to cause no OS compatibility issues.
106 // TODO(crbug.com/1429117): Merge into above option, if possible.
107 bool exclusive_database_file_lock = false;
109 // If true, enables SQLite's Write-Ahead Logging (WAL).
111 // WAL integration is under development, and should not be used in shipping
112 // Chrome features yet. In particular, our custom database recovery code does
113 // not support the WAL log file.
115 // WAL mode is currently not fully supported on FuchsiaOS. It will only be
116 // turned on if the database is also using exclusive locking mode.
117 // (https://crbug.com/1082059)
119 // Note: Changing page size is not supported when in WAL mode. So running
120 // 'PRAGMA page_size = <new-size>' will result in no-ops.
122 // More details at https://www.sqlite.org/wal.html
124 base::FeatureList::IsEnabled(sql::features::kEnableWALModeByDefault);
126 // If true, transaction commit waits for data to reach persistent media.
128 // This is currently only meaningful on macOS. All other operating systems
129 // only support flushing directly to disk.
131 // If both `flush_to_media` and `wal_mode` are false, power loss can lead to
132 // database corruption.
134 // By default, SQLite considers that transactions commit when they reach the
135 // disk controller's memory. This guarantees durability in the event of
136 // software crashes, up to and including the operating system. In the event of
137 // power loss, SQLite may lose data. If `wal_mode` is false (SQLite uses a
138 // rollback journal), power loss can lead to database corruption.
140 // When this option is enabled, committing a transaction causes SQLite to wait
141 // until the data is written to the persistent media. This guarantees
142 // durability in the event of power loss, which is needed to guarantee the
143 // integrity of non-WAL databases.
144 bool flush_to_media = false;
146 // Database page size.
148 // New Chrome features should set an explicit page size in their
149 // DatabaseOptions initializers, even if they use the default page size. This
150 // makes it easier to track the page size used by the databases on the users'
153 // The value in this option is only applied to newly created databases. In
154 // other words, changing the value doesn't impact the databases that have
155 // already been created on the users' devices. So, changing the value in the
156 // code without a lot of work (re-creating existing databases) will result in
157 // inconsistent page sizes across the fleet of user devices, which will make
158 // it (even) more difficult to reason about database performance.
160 // Larger page sizes result in shallower B-trees, because they allow an inner
161 // page to hold more keys. On the flip side, larger page sizes may result in
162 // more I/O when making small changes to existing records.
164 // Must be a power of two between 512 and 65536 inclusive.
166 // TODO(pwnall): Replace the default with an invalid value after all
167 // sql::Database users explicitly initialize page_size.
168 int page_size = kDefaultPageSize;
170 // The size of in-memory cache, in pages.
172 // New Chrome features should set an explicit cache size in their
173 // DatabaseOptions initializers, even if they use the default cache size. This
174 // makes it easier to track the cache size used by the databases on the users'
175 // devices. The default page size of 4,096 bytes results in a cache size of
178 // SQLite's database cache will take up at most (`page_size` * `cache_size`)
181 // 0 invokes SQLite's default, which is currently to size up the cache to use
182 // exactly 2,048,000 bytes of RAM.
184 // TODO(pwnall): Replace the default with an invalid value after all
185 // sql::Database users explicitly initialize page_size.
188 // Stores mmap failures in the SQL schema, instead of the meta table.
190 // This option is strongly discouraged for new databases, and will eventually
193 // If this option is true, the mmap status is stored in the database schema.
194 // Like any other schema change, changing the mmap status invalidates all
195 // pre-compiled SQL statements.
196 bool mmap_alt_status_discouraged = false;
198 // If true, enables SQL views (a discouraged feature) for this database.
200 // The use of views is discouraged for Chrome code. See README.md for details
201 // and recommended replacements.
203 // If this option is false, CREATE VIEW and DROP VIEW succeed, but SELECT
204 // statements targeting views fail.
205 bool enable_views_discouraged = false;
207 // If true, enables virtual tables (a discouraged feature) for this database.
209 // The use of virtual tables is discouraged for Chrome code. See README.md for
210 // details and recommended replacements.
212 // If this option is false, CREATE VIRTUAL TABLE and DROP VIRTUAL TABLE
213 // succeed, but statements targeting virtual tables fail.
214 bool enable_virtual_tables_discouraged = false;
217 // Holds database diagnostics in a structured format.
218 struct COMPONENT_EXPORT(SQL) DatabaseDiagnostics {
219 DatabaseDiagnostics();
220 ~DatabaseDiagnostics();
222 using TraceProto = perfetto::protos::pbzero::ChromeSqlDiagnostics;
223 // Write a representation of this object into tracing proto.
224 void WriteIntoTrace(perfetto::TracedProto<TraceProto> context) const;
226 // This was the original error code that triggered the error callback. Should
227 // generally match `error_code`, but this isn't guaranteed by the code.
228 int reported_sqlite_error_code = 0;
230 // Corresponds to `Database::GetErrorCode()`.
233 // Corresponds to `Database::GetLastErrno()`.
236 // Corresponds to `Statement::GetSQLStatement()` of the problematic statement.
237 // This doesn't include the bound values, and therefore is free of any PII.
238 std::string sql_statement;
240 // The 'version' value stored in the user database's meta table, if it can be
241 // read. If we fail to read the version of the user database, it's left as 0.
244 // Most rows in 'sql_schema' have a non-NULL 'sql' column. Those rows' 'sql'
245 // contents are logged here, one element per row.
246 std::vector<std::string> schema_sql_rows;
248 // Some rows of 'sql_schema' have a NULL 'sql' column. They are typically
249 // autogenerated indices, like "sqlite_autoindex_downloads_slices_1". These
250 // are also logged here by their 'name' column, one element per row.
251 std::vector<std::string> schema_other_row_names;
253 // Sanity checks used for all errors.
254 bool has_valid_header = false;
255 bool has_valid_schema = false;
257 // Corresponds to `Database::GetErrorMessage()`.
258 std::string error_message;
261 // Handle to an open SQLite database.
263 // Instances of this class are not thread-safe. After construction, a Database
264 // instance should only be accessed from one sequence.
266 // When a Database instance goes out of scope, any uncommitted transactions are
268 class COMPONENT_EXPORT(SQL) Database {
270 class StatementRef; // Forward declaration, see real one below.
273 // Creates an instance that can receive Open() / OpenInMemory() calls.
275 // Some `options` members are only applied to newly created databases.
277 // Most operations on the new instance will fail until Open() / OpenInMemory()
279 explicit Database(DatabaseOptions options);
281 // This constructor is deprecated.
283 // When transitioning away from this default constructor, consider setting
284 // DatabaseOptions::explicit_locking to true. For historical reasons, this
285 // constructor results in DatabaseOptions::explicit_locking set to false.
287 // TODO(crbug.com/1126968): Remove this constructor after migrating all
288 // uses to the explicit constructor below.
291 Database(const Database&) = delete;
292 Database& operator=(const Database&) = delete;
293 Database(Database&&) = delete;
294 Database& operator=(Database&&) = delete;
297 // Allows mmapping to be disabled globally by default in the calling process.
298 // Must be called before any threads attempt to create a Database.
300 // TODO(crbug.com/1117049): Remove this global configuration.
301 static void DisableMmapByDefault();
303 // Pre-init configuration ----------------------------------------------------
305 // The page size that will be used when creating a new database.
306 int page_size() const { return options_.page_size; }
308 // Returns whether a database will be opened in WAL mode.
309 bool UseWALMode() const;
311 // Opt out of memory-mapped file I/O.
312 void set_mmap_disabled() { mmap_disabled_ = true; }
314 // Set an error-handling callback. On errors, the error number (and
315 // statement, if available) will be passed to the callback.
317 // If no callback is set, the default error-handling behavior is invoked. The
318 // default behavior is to LOGs the error and propagate the failure.
320 // In DCHECK-enabled builds, the default error-handling behavior currently
321 // DCHECKs on errors. This is not correct, because DCHECKs are supposed to
322 // cover invariants and never fail, whereas SQLite errors can surface even on
323 // correct usage, due to I/O errors and data corruption. At some point in the
324 // future, errors will not result in DCHECKs.
326 // The callback will be called on the sequence used for database operations.
327 // The callback will never be called after the Database instance is destroyed.
328 using ErrorCallback = base::RepeatingCallback<void(int, Statement*)>;
329 void set_error_callback(ErrorCallback callback) {
330 DCHECK(!callback.is_null()) << "Use reset_error_callback() explicitly";
331 DCHECK(error_callback_.is_null())
332 << "Overwriting previously set error callback";
333 error_callback_ = std::move(callback);
335 void reset_error_callback() { error_callback_.Reset(); }
336 bool has_error_callback() const { return !error_callback_.is_null(); }
338 // Developer-friendly database ID used in logging output and memory dumps.
339 void set_histogram_tag(const std::string& tag);
341 // Asks SQLite to perform a full integrity check on the database.
343 // Returns true if the integrity check was completed successfully. Success
344 // does not necessarily entail that the database is healthy. Finding
345 // corruption and reporting it in `messages` counts as success.
347 // If the method returns true, `messages` is populated with a list of
348 // diagnostic messages. If the integrity check finds no errors, `messages`
349 // will contain exactly one "ok" string. This unusual API design is explained
350 // by the fact that SQLite exposes integrity check functionality as a PRAGMA,
351 // and the PRAGMA returns "ok" in case of success.
352 bool FullIntegrityCheck(std::vector<std::string>* messages);
354 // Meant to be called from a client error callback so that it's able to
355 // get diagnostic information about the database. `diagnostics` is an optional
356 // out parameter. If `diagnostics` is defined, this method populates all of
358 std::string GetDiagnosticInfo(int extended_error,
359 Statement* statement,
360 DatabaseDiagnostics* diagnostics = nullptr);
362 // Reports memory usage into provided memory dump with the given name.
363 bool ReportMemoryUsage(base::trace_event::ProcessMemoryDump* pmd,
364 const std::string& dump_name);
366 // Initialization ------------------------------------------------------------
368 // Opens or creates a database on disk.
370 // `db_file_path` points to the file storing database pages. Other files
371 // associated with the database (rollback journal, write-ahead log,
372 // shared-memory file) may be created.
374 // Returns true in case of success, false in case of failure.
375 [[nodiscard]] bool Open(const base::FilePath& db_file_path);
377 // Alternative to Open() that creates an in-memory database.
379 // Returns true in case of success, false in case of failure.
381 // The memory associated with the database will be released when the database
383 [[nodiscard]] bool OpenInMemory();
385 // Alternative to Open() that creates a temporary on-disk database.
387 // Returns true in case of success, false in case of failure.
389 // The files associated with the temporary database will be deleted when the
390 // database is closed.
391 [[nodiscard]] bool OpenTemporary(base::PassKey<Recovery>);
393 // Returns true if the database has been successfully opened.
394 bool is_open() const;
396 // Closes the database. This is automatically performed on destruction for
397 // you, but this allows you to close the database early. You must not call
398 // any other functions after closing it. It is permissable to call Close on
399 // an uninitialized or already-closed database.
402 // Hints the file system that the database will be accessed soon.
404 // This method should be called on databases that are on the critical path to
405 // Chrome startup. Informing the filesystem about our expected access pattern
406 // early on reduces the likelihood that we'll be blocked on disk I/O. This has
407 // a high impact on startup time.
409 // This method should not be used for non-critical databases. While using it
410 // will likely improve micro-benchmarks involving one specific database,
411 // overuse risks randomizing the disk I/O scheduler, slowing down Chrome
415 // Release all non-essential memory associated with this database connection.
418 // Raze the database to the ground. This approximates creating a
419 // fresh database from scratch, within the constraints of SQLite's
420 // locking protocol (locks and open handles can make doing this with
421 // filesystem operations problematic). Returns true if the database
424 // false is returned if the database is locked by some other
427 // NOTE(shess): Raze() will DCHECK in the following situations:
428 // - database is not open.
429 // - the database has a transaction open.
430 // - a SQLite issue occurs which is structural in nature (like the
431 // statements used are broken).
432 // Since Raze() is expected to be called in unexpected situations,
433 // these all return false, since it is unlikely that the caller
436 // The database's page size is taken from |options_.page_size|. The
437 // existing database's |auto_vacuum| setting is lost (the
438 // possibility of corruption makes it unreliable to pull it from the
439 // existing database). To re-enable on the empty database requires
440 // running "PRAGMA auto_vacuum = 1;" then "VACUUM".
442 // NOTE(shess): For Android, SQLITE_DEFAULT_AUTOVACUUM is set to 1,
443 // so Raze() sets auto_vacuum to 1.
445 // TODO(shess): Raze() needs a database so cannot clear SQLITE_NOTADB.
446 // TODO(shess): Bake auto_vacuum into Database's API so it can
447 // just pick up the default.
450 // Breaks all outstanding transactions (as initiated by
451 // BeginTransaction()), closes the SQLite database, and poisons the
452 // object so that all future operations against the Database (or
453 // its Statements) fail safely, without side effects.
455 // This is intended as an alternative to Close() in error callbacks.
456 // Close() should still be called at some point.
459 // `Raze()` the database and `Poison()` the handle. Returns the return
460 // value from `Raze()`.
461 bool RazeAndPoison();
463 // Delete the underlying database files associated with |path|. This should be
464 // used on a database which is not opened by any Database instance. Open
465 // Database instances pointing to the database can cause odd results or
466 // corruption (for instance if a hot journal is deleted but the associated
469 // Returns true if the database file and associated journals no
470 // longer exist, false otherwise. If the database has never
471 // existed, this will return true.
472 static bool Delete(const base::FilePath& path);
474 // Transactions --------------------------------------------------------------
476 // Transaction management. We maintain a virtual transaction stack to emulate
477 // nested transactions since sqlite can't do nested transactions. The
478 // limitation is you can't roll back a sub transaction: if any transaction
479 // fails, all transactions open will also be rolled back. Any nested
480 // transactions after one has rolled back will return fail for Begin(). If
481 // Begin() fails, you must not call Commit or Rollback().
483 // Normally you should use sql::Transaction to manage a transaction, which
484 // will scope it to a C++ context.
485 bool BeginTransaction();
486 void RollbackTransaction();
487 bool CommitTransaction();
489 // Rollback all outstanding transactions. Use with care, there may
490 // be scoped transactions on the stack.
491 void RollbackAllTransactions();
493 bool HasActiveTransactions() const {
494 DCHECK_GE(transaction_nesting_, 0);
495 return transaction_nesting_ > 0;
498 // Deprecated in favor of HasActiveTransactions().
500 // Returns the current transaction nesting, which will be 0 if there are
501 // no open transactions.
502 int transaction_nesting() const { return transaction_nesting_; }
504 // Attached databases---------------------------------------------------------
506 // Attaches an existing database to this connection.
508 // `attachment_point` must only contain lowercase letters.
510 // Attachment APIs are only exposed for use in recovery. General use is
511 // discouraged in Chrome. The README has more details.
513 // On the SQLite version shipped with Chrome (3.21+, Oct 2017), databases can
514 // be attached while a transaction is opened. However, these databases cannot
515 // be detached until the transaction is committed or aborted.
516 bool AttachDatabase(const base::FilePath& other_db_path,
517 base::StringPiece attachment_point,
520 // Detaches a database that was previously attached with AttachDatabase().
522 // `attachment_point` must match the argument of a previously successsful
523 // AttachDatabase() call.
525 // Attachment APIs are only exposed for use in recovery. General use is
526 // discouraged in Chrome. The README has more details.
527 bool DetachDatabase(base::StringPiece attachment_point, InternalApiToken);
529 // Statements ----------------------------------------------------------------
531 // Executes a SQL statement. Returns true for success, and false for failure.
533 // `sql` should be a single SQL statement. Production code should not execute
534 // multiple SQL statements at once, to facilitate crash debugging. Test code
535 // should use ExecuteScriptForTesting().
537 // `sql` cannot have parameters. Statements with parameters can be handled by
538 // sql::Statement. See GetCachedStatement() and GetUniqueStatement().
539 [[nodiscard]] bool Execute(const char* sql);
541 // Executes a sequence of SQL statements.
543 // Returns true if all statements execute successfully. If a statement fails,
544 // stops and returns false. Calls should be wrapped in ASSERT_TRUE().
546 // The database's error handler is not invoked when errors occur. This method
547 // is a convenience for setting up a complex on-disk database state, such as
548 // an old schema version with test contents.
549 [[nodiscard]] bool ExecuteScriptForTesting(const char* sql_script);
551 // Returns a statement for the given SQL using the statement cache. It can
552 // take a nontrivial amount of work to parse and compile a statement, so
553 // keeping commonly-used ones around for future use is important for
556 // The SQL_FROM_HERE macro is the recommended way of generating a StatementID.
557 // Code that generates custom IDs must ensure that a StatementID is never used
558 // for different SQL statements. Failing to meet this requirement results in
559 // incorrect behavior, and should be caught by a DCHECK.
561 // The SQL statement passed in |sql| must match the SQL statement reported
562 // back by SQLite. Mismatches are caught by a DCHECK, so any code that has
563 // automated test coverage or that was manually tested on a DCHECK build will
564 // not exhibit this problem. Mismatches generally imply that the statement
565 // passed in has extra whitespace or comments surrounding it, which waste
566 // storage and CPU cycles.
568 // If the |sql| has an error, an invalid, inert StatementRef is returned (and
569 // the code will crash in debug). The caller must deal with this eventuality,
570 // either by checking validity of the |sql| before calling, by correctly
571 // handling the return of an inert statement, or both.
574 // sql::Statement stmt(database_.GetCachedStatement(
575 // SQL_FROM_HERE, "SELECT * FROM foo"));
577 // return false; // Error creating statement.
578 scoped_refptr<StatementRef> GetCachedStatement(StatementID id,
581 // Used to check a |sql| statement for syntactic validity. If the statement is
582 // valid SQL, returns true.
583 bool IsSQLValid(const char* sql);
585 // Returns a non-cached statement for the given SQL. Use this for SQL that
586 // is only executed once or only rarely (there is overhead associated with
587 // keeping a statement cached).
589 // See GetCachedStatement above for examples and error information.
590 scoped_refptr<StatementRef> GetUniqueStatement(const char* sql);
592 // Returns a non-cached statement same as `GetUniqueStatement()`, except
593 // returns an invalid statement if the statement makes direct changes to the
594 // database file. This readonly check does not include changes made by
595 // application-defined functions. See more at:
596 // https://www.sqlite.org/c3ref/stmt_readonly.html.
597 scoped_refptr<Database::StatementRef> GetReadonlyStatement(const char* sql);
599 // Performs a passive checkpoint on the main attached database if it is in
600 // WAL mode. Returns true if the checkpoint was successful and false in case
601 // of an error. It is a no-op if the database is not in WAL mode.
603 // Note: Checkpointing is a very slow operation and will block any writes
604 // until it is finished. Please use with care.
605 bool CheckpointDatabase();
607 // Info querying -------------------------------------------------------------
609 // Returns true if the given structure exists. Instead of test-then-create,
610 // callers should almost always prefer the "IF NOT EXISTS" version of the
612 bool DoesIndexExist(base::StringPiece index_name);
613 bool DoesTableExist(base::StringPiece table_name);
614 bool DoesViewExist(base::StringPiece table_name);
616 // Returns true if a column with the given name exists in the given table.
618 // Calling this method on a VIEW returns an unspecified result.
620 // This should only be used by migration code for legacy features that do not
621 // use MetaTable, and need an alternative way of figuring out the database's
623 bool DoesColumnExist(const char* table_name, const char* column_name);
625 // Returns sqlite's internal ID for the last inserted row. Valid only
626 // immediately after an insert.
627 int64_t GetLastInsertRowId() const;
629 // Returns sqlite's count of the number of rows modified by the last
630 // statement executed. Will be 0 if no statement has executed or the database
632 int64_t GetLastChangeCount();
634 // Approximates the amount of memory used by SQLite for this database.
636 // This measures the memory used for the page cache (most likely the biggest
637 // consumer), database schema, and prepared statements.
639 // The memory used by the page cache can be recovered by calling TrimMemory(),
640 // which will cause SQLite to drop the page cache.
641 int GetMemoryUsage();
643 // Errors --------------------------------------------------------------------
645 // Returns the error code associated with the last sqlite operation.
646 int GetErrorCode() const;
648 // Returns the errno associated with GetErrorCode(). See
649 // SQLITE_LAST_ERRNO in SQLite documentation.
650 int GetLastErrno() const;
652 // Returns a pointer to a statically allocated string associated with the
653 // last sqlite operation.
654 const char* GetErrorMessage() const;
656 // Return a reproducible representation of the schema equivalent to
657 // running the following statement at a sqlite3 command-line:
658 // SELECT type, name, tbl_name, sql FROM sqlite_schema ORDER BY 1, 2, 3, 4;
659 std::string GetSchema();
661 // Returns |true| if there is an error expecter (see SetErrorExpecter), and
662 // that expecter returns |true| when passed |error|. Clients which provide an
663 // |error_callback| should use IsExpectedSqliteError() to check for unexpected
664 // errors; if one is detected, DLOG(DCHECK) is generally appropriate (see
665 // OnSqliteError implementation).
666 static bool IsExpectedSqliteError(int sqlite_error_code);
668 // Computes the path of a database's rollback journal.
670 // The journal file is created at the beginning of the database's first
671 // transaction. The file may be removed and re-created between transactions,
672 // depending on whether the database is opened in exclusive mode, and on
673 // configuration options. The journal file does not exist when the database
674 // operates 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 JournalPath(const base::FilePath& db_path);
681 // Computes the path of a database's write-ahead log (WAL).
683 // The WAL file exists while a database is opened in WAL mode.
685 // This is intended for internal use and tests. To preserve our ability to
686 // iterate on our SQLite configuration, features must avoid relying on
687 // the existence of specific files.
688 static base::FilePath WriteAheadLogPath(const base::FilePath& db_path);
690 // Computes the path of a database's shared memory (SHM) file.
692 // The SHM file is used to coordinate between multiple processes using the
693 // same database in WAL mode. Thus, this file only exists for databases using
694 // WAL and not opened in exclusive mode.
696 // This is intended for internal use and tests. To preserve our ability to
697 // iterate on our SQLite configuration, features must avoid relying on
698 // the existence of specific files.
699 static base::FilePath SharedMemoryFilePath(const base::FilePath& db_path);
701 // Internal state accessed by other classes in //sql.
702 sqlite3* db(InternalApiToken) const { return db_; }
703 bool poisoned(InternalApiToken) const { return poisoned_; }
704 base::FilePath DbPath(InternalApiToken) const { return DbPath(); }
706 // Interface with sql::test::ScopedErrorExpecter.
707 using ScopedErrorExpecterCallback = base::RepeatingCallback<bool(int)>;
708 static void SetScopedErrorExpecter(ScopedErrorExpecterCallback* expecter,
709 base::PassKey<test::ScopedErrorExpecter>);
710 static void ResetScopedErrorExpecter(
711 base::PassKey<test::ScopedErrorExpecter>);
714 // Statement accesses StatementRef which we don't want to expose to everybody
715 // (they should go through Statement).
716 friend class Statement;
718 FRIEND_TEST_ALL_PREFIXES(SQLDatabaseTest, CachedStatement);
719 FRIEND_TEST_ALL_PREFIXES(SQLDatabaseTest, CollectDiagnosticInfo);
720 FRIEND_TEST_ALL_PREFIXES(SQLDatabaseTest, ComputeMmapSizeForOpen);
721 FRIEND_TEST_ALL_PREFIXES(SQLDatabaseTest, ComputeMmapSizeForOpenAltStatus);
722 FRIEND_TEST_ALL_PREFIXES(SQLDatabaseTest, OnMemoryDump);
723 FRIEND_TEST_ALL_PREFIXES(SQLDatabaseTest, RegisterIntentToUpload);
724 FRIEND_TEST_ALL_PREFIXES(SQLiteFeaturesTest, WALNoClose);
725 FRIEND_TEST_ALL_PREFIXES(SQLEmptyPathDatabaseTest, EmptyPathTest);
727 // Enables a special behavior for OpenInternal().
728 enum class OpenMode {
729 // No special behavior.
732 // Retry if the database error handler is invoked and closes the database.
733 // Database error handlers that call RazeAndPoison() take advantage of this.
736 // Open an in-memory database. Used by OpenInMemory().
739 // Open a temporary database. Used by OpenTemporary().
743 // Implements Open(), OpenInMemory(), and OpenTemporary().
745 // `db_file_path` is a UTF-8 path to the file storing the database pages. The
746 // path must be empty if `mode` is kTemporary. The path must be the SQLite
747 // magic memory path string if `mode` is kMemory.
748 bool OpenInternal(const std::string& file_name, OpenMode mode);
750 // Configures the underlying sqlite3* object via sqlite3_db_config().
752 // To minimize the number of possible SQLite code paths executed in Chrome,
753 // this method must be called right after the underlying sqlite3* object is
754 // obtained from sqlite3_open*(), before any other sqlite3_*() methods are
755 // called on the object.
756 void ConfigureSqliteDatabaseObject();
758 // Internal close function used by Close() and RazeAndPoison().
759 // |forced| indicates that orderly-shutdown checks should not apply.
760 void CloseInternal(bool forced);
762 // Construct a ScopedBlockingCall to annotate IO calls, but only if
763 // database wasn't open in memory. ScopedBlockingCall uses |from_here| to
764 // declare its blocking execution scope (see https://www.crbug/934302).
765 void InitScopedBlockingCall(
766 const base::Location& from_here,
767 absl::optional<base::ScopedBlockingCall>* scoped_blocking_call) const {
769 scoped_blocking_call->emplace(from_here, base::BlockingType::MAY_BLOCK);
772 // Internal helper for Does*Exist() functions.
773 bool DoesSchemaItemExist(base::StringPiece name, base::StringPiece type);
775 // Used to implement the interface with sql::test::ScopedErrorExpecter.
776 static ScopedErrorExpecterCallback* current_expecter_cb_;
778 // A StatementRef is a refcounted wrapper around a sqlite statement pointer.
779 // Refcounting allows us to give these statements out to sql::Statement
780 // objects while also optionally maintaining a cache of compiled statements
781 // by just keeping a refptr to these objects.
783 // A statement ref can be valid, in which case it can be used, or invalid to
784 // indicate that the statement hasn't been created yet, has an error, or has
787 // The Database may revoke a StatementRef in some error cases, so callers
788 // should always check validity before using.
789 class COMPONENT_EXPORT(SQL) StatementRef
790 : public base::RefCounted<StatementRef> {
792 REQUIRE_ADOPTION_FOR_REFCOUNTED_TYPE();
794 // |database| is the sql::Database instance associated with
795 // the statement, and is used for tracking outstanding statements
796 // and for error handling. Set to nullptr for invalid refs.
797 // |stmt| is the actual statement, and should only be null
798 // to create an invalid ref. |was_valid| indicates whether the
799 // statement should be considered valid for diagnostic purposes.
800 // |was_valid| can be true for a null |stmt| if the Database has
801 // been forcibly closed by an error handler.
802 StatementRef(Database* database, sqlite3_stmt* stmt, bool was_valid);
804 StatementRef(const StatementRef&) = delete;
805 StatementRef& operator=(const StatementRef&) = delete;
806 StatementRef(StatementRef&&) = delete;
807 StatementRef& operator=(StatementRef&&) = delete;
809 // When true, the statement can be used.
810 bool is_valid() const { return !!stmt_; }
812 // When true, the statement is either currently valid, or was
813 // previously valid but the database was forcibly closed. Used
814 // for diagnostic checks.
815 bool was_valid() const { return was_valid_; }
817 // If we've not been linked to a database, this will be null.
818 Database* database() const { return database_; }
820 // Returns the sqlite statement if any. If the statement is not active,
821 // this will return nullptr.
822 sqlite3_stmt* stmt() const { return stmt_; }
824 // Destroys the compiled statement and sets it to nullptr. The statement
825 // will no longer be active. |forced| is used to indicate if
826 // orderly-shutdown checks should apply (see Database::RazeAndPoison()).
827 void Close(bool forced);
829 // Construct a ScopedBlockingCall to annotate IO calls, but only if
830 // database wasn't open in memory. ScopedBlockingCall uses |from_here| to
831 // declare its blocking execution scope (see https://www.crbug/934302).
832 void InitScopedBlockingCall(
833 const base::Location& from_here,
834 absl::optional<base::ScopedBlockingCall>* scoped_blocking_call) const {
836 database_->InitScopedBlockingCall(from_here, scoped_blocking_call);
840 friend class base::RefCounted<StatementRef>;
844 raw_ptr<Database> database_;
845 raw_ptr<sqlite3_stmt> stmt_;
848 friend class StatementRef;
850 // Executes a rollback statement, ignoring all transaction state. Used
851 // internally in the transaction management code.
854 // Called by a StatementRef when it's being created or destroyed. See
855 // open_statements_ below.
856 void StatementRefCreated(StatementRef* ref);
857 void StatementRefDeleted(StatementRef* ref);
859 // Used by sql:: internals to report a SQLite error related to this database.
861 // `sqlite_error_code` contains the error code reported by SQLite. Possible
862 // values are documented at https://www.sqlite.org/rescode.html
864 // `statement` is non-null if the error is associated with a sql::Statement.
865 // Otherwise, `sql_statement` will be a non-null string pointing to a
866 // statically-allocated (valid for the entire duration of the process) buffer
867 // pointing to either a SQL statement or a SQL comment (starting with "-- ")
868 // pointing to a "sqlite3_" function name.
869 void OnSqliteError(SqliteErrorCode sqlite_error_code,
870 Statement* statement,
871 const char* sql_statement);
873 // Like Execute(), but returns a SQLite result code.
875 // This method returns SqliteResultCode::kOk or a SQLite error code. In other
876 // words, it never returns SqliteResultCode::{kDone, kRow}.
878 // This method is only exposed to the Database implementation. Code that uses
879 // sql::Database should not be concerned with SQLite result codes.
880 [[nodiscard]] SqliteResultCode ExecuteAndReturnResultCode(const char* sql);
882 // Like |Execute()|, but retries if the database is locked.
883 [[nodiscard]] bool ExecuteWithTimeout(const char* sql,
884 base::TimeDelta ms_timeout);
886 // Implementation helper for GetUniqueStatement() and GetCachedStatement().
887 scoped_refptr<StatementRef> GetStatementImpl(const char* sql,
890 // Release page-cache memory if memory-mapped I/O is enabled and the database
891 // was changed. Passing true for |implicit_change_performed| allows
892 // overriding the change detection for cases like DDL (CREATE, DROP, etc),
893 // which do not participate in the total-rows-changed tracking.
894 void ReleaseCacheMemoryIfNeeded(bool implicit_change_performed);
896 // Returns the results of sqlite3_db_filename(), which should match the path
898 base::FilePath DbPath() const;
900 // Helper to collect diagnostic info for a corrupt database.
901 std::string CollectCorruptionInfo();
903 // Helper to collect diagnostic info for errors. `diagnostics` is an optional
904 // out parameter. If `diagnostics` is defined, this method populates SOME of
905 // its fields. Some of the fields are left unmodified for the caller.
906 std::string CollectErrorInfo(int sqlite_error_code,
908 DatabaseDiagnostics* diagnostics) const;
910 // The size of the memory mapping that SQLite should use for this database.
912 // The return value follows the semantics of "PRAGMA mmap_size". In
913 // particular, zero (0) means memory-mapping should be disabled, and the value
914 // is capped by SQLITE_MAX_MMAP_SIZE. More details at
915 // https://www.sqlite.org/pragma.html#pragma_mmap_size
917 // "Memory-mapped access" is usually shortened to "mmap", which is the name of
918 // the POSIX system call used to implement. The same principles apply on
919 // Windows, but its more-descriptive API names don't make for good shorthands.
921 // When mmap is enabled, SQLite attempts to use the memory-mapped area (by
922 // calling xFetch() in the VFS file API) instead of requesting a database page
923 // buffer from the pager and reading (via xRead() in the VFS API) into it.
924 // When this works out, the database page cache ends up only storing pages
925 // whose contents has been modified. More details at
926 // https://sqlite.org/mmap.html
928 // I/O errors on memory-mapped files result in crashes in Chrome. POSIX
929 // systems signal SIGSEGV or SIGBUS on I/O errors in mmap-ed files. Windows
930 // raises the EXECUTE_IN_PAGE_ERROR strucuted exception in this case. Chrome
931 // does not catch signals or structured exceptions.
933 // In order to avoid crashes, this method attempts to read the file using
934 // regular I/O, and returns 0 (no mmap) if it encounters any error.
935 size_t ComputeMmapSizeForOpen();
937 // Helpers for ComputeMmapSizeForOpen().
938 bool GetMmapAltStatus(int64_t* status);
939 bool SetMmapAltStatus(int64_t status);
941 // sqlite3_prepare_v3() flags for this database.
942 int SqlitePrepareFlags() const;
944 // Returns a SQLite VFS interface pointer to the file storing database pages.
946 // Returns null if the database is not backed by a VFS file. This is always
947 // the case for in-memory databases. Temporary databases (only used by sq
948 // ::Recovery) start without a backing VFS file, and only get a file when they
949 // outgrow their page cache.
951 // This method must only be called while the database is successfully opened.
952 sqlite3_file* GetSqliteVfsFile();
954 // Will eventually be checked on all methods. See https://crbug.com/1306694
955 SEQUENCE_CHECKER(sequence_checker_);
957 // The actual sqlite database. Will be null before Init has been called or if
958 // Init resulted in an error.
959 // This field is not a raw_ptr<> because it was filtered by the rewriter for:
961 RAW_PTR_EXCLUSION sqlite3* db_ = nullptr;
963 // TODO(shuagga@microsoft.com): Make `options_` const after removing all
965 DatabaseOptions options_;
967 // Holds references to all cached statements so they remain active.
969 // flat_map is appropriate here because the codebase has ~400 cached
970 // statements, and each statement is at most one insertion in the map
971 // throughout a process' lifetime.
972 base::flat_map<StatementID, scoped_refptr<StatementRef>> statement_cache_;
974 // A list of all StatementRefs we've given out. Each ref must register with
975 // us when it's created or destroyed. This allows us to potentially close
976 // any open statements when we encounter an error.
977 std::set<StatementRef*> open_statements_;
979 // Number of currently-nested transactions.
980 int transaction_nesting_ = 0;
982 // True if any of the currently nested transactions have been rolled back.
983 // When we get to the outermost transaction, this will determine if we do
984 // a rollback instead of a commit.
985 bool needs_rollback_ = false;
987 // True if database is open with OpenInMemory(), False if database is open
989 bool in_memory_ = false;
991 // |true| if the Database was closed using RazeAndPoison(). Used
992 // to enable diagnostics to distinguish calls to never-opened
993 // databases (incorrect use of the API) from calls to once-valid
995 bool poisoned_ = false;
997 // |true| if SQLite memory-mapped I/O is not desired for this database.
1000 // |true| if SQLite memory-mapped I/O was enabled for this database.
1001 // Used by ReleaseCacheMemoryIfNeeded().
1002 bool mmap_enabled_ = false;
1004 // Used by ReleaseCacheMemoryIfNeeded() to track if new changes have happened
1005 // since memory was last released.
1006 int64_t total_changes_at_last_release_ = 0;
1008 // Called when a SQLite error occurs.
1010 // This callback may be null, in which case errors are handled using a default
1013 // This callback must never be exposed outside this Database instance. This is
1014 // a straight-forward way to guarantee that this callback will not be called
1015 // after the Database instance goes out of scope. set_error_callback() makes
1017 ErrorCallback error_callback_;
1019 // Developer-friendly database ID used in logging output and memory dumps.
1020 std::string histogram_tag_;
1022 // Stores the dump provider object when db is open.
1023 std::unique_ptr<DatabaseMemoryDumpProvider> memory_dump_provider_;
1028 #endif // SQL_DATABASE_H_