database.h 43 KB

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