database.h 43 KB

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