meta_table.h 5.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129
  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_META_TABLE_H_
  5. #define SQL_META_TABLE_H_
  6. #include <cstdint>
  7. #include <string>
  8. #include "base/component_export.h"
  9. #include "base/memory/raw_ptr.h"
  10. #include "base/strings/string_piece_forward.h"
  11. namespace sql {
  12. class Database;
  13. // Creates and manages a table to store generic metadata. The features provided
  14. // are:
  15. // * An interface for storing multi-typed key-value data.
  16. // * Helper methods to assist in database schema version control.
  17. // * Historical data on past attempts to mmap the database to make it possible
  18. // to avoid unconditionally retrying to load broken databases.
  19. class COMPONENT_EXPORT(SQL) MetaTable {
  20. public:
  21. MetaTable();
  22. MetaTable(const MetaTable&) = delete;
  23. MetaTable& operator=(const MetaTable&) = delete;
  24. ~MetaTable();
  25. // Values for Get/SetMmapStatus(). `kMmapFailure` indicates that there was at
  26. // some point a read error and the database should not be memory-mapped, while
  27. // `kMmapSuccess` indicates that the entire file was read at some point and
  28. // can be memory-mapped without constraint.
  29. static constexpr int64_t kMmapFailure = -2;
  30. static constexpr int64_t kMmapSuccess = -1;
  31. // Returns true if the 'meta' table exists.
  32. static bool DoesTableExist(Database* db);
  33. // Deletes the 'meta' table if it exists, returning false if an internal error
  34. // occurred during the deletion and true otherwise (no matter whether the
  35. // table existed).
  36. static bool DeleteTableForTesting(Database* db);
  37. // If the current version of the database is less than
  38. // `lowest_supported_version`, or the current version is less than the
  39. // database's least compatible version, razes the database. To only enforce
  40. // the latter, pass `kNoLowestSupportedVersion` for
  41. // `lowest_supported_version`.
  42. //
  43. // TODO(crbug.com/1228463): At this time the database is razed IFF meta exists
  44. // and contains a version row with the value not satisfying the constraints.
  45. // It may make sense to also raze if meta exists but has no version row, or if
  46. // meta doesn't exist. In those cases if the database is not already empty, it
  47. // probably resulted from a broken initialization.
  48. // TODO(crbug.com/1228463): Folding this into Init() would allow enforcing
  49. // the version constraint, but Init() is often called in a transaction.
  50. static constexpr int kNoLowestSupportedVersion = 0;
  51. static void RazeIfIncompatible(Database* db,
  52. int lowest_supported_version,
  53. int current_version);
  54. // Used to tuck some data into the meta table about mmap status. The value
  55. // represents how much data in bytes has successfully been read from the
  56. // database, or `kMmapFailure` or `kMmapSuccess`.
  57. static bool GetMmapStatus(Database* db, int64_t* status);
  58. static bool SetMmapStatus(Database* db, int64_t status);
  59. // Initializes the MetaTableHelper, providing the `Database` pointer and
  60. // creating the meta table if necessary. Must be called before any other
  61. // non-static methods. For new tables, it will initialize the version number
  62. // to `version` and the compatible version number to `compatible_version`.
  63. // Versions must be greater than 0 to distinguish missing versions (see
  64. // GetVersionNumber()). If there was no meta table (proxy for a fresh
  65. // database), mmap status is set to `kMmapSuccess`.
  66. bool Init(Database* db, int version, int compatible_version);
  67. // Resets this MetaTable object, making another call to Init() possible.
  68. void Reset();
  69. // The version number of the database. This should be the version number of
  70. // the creator of the file. The version number will be 0 if there is no
  71. // previously set version number.
  72. //
  73. // See also Get/SetCompatibleVersionNumber().
  74. void SetVersionNumber(int version);
  75. int GetVersionNumber();
  76. // The compatible version number is the lowest current version embedded in
  77. // Chrome code that can still use this database. This is usually the same as
  78. // the current version. In some limited cases, such as adding a column without
  79. // a NOT NULL constraint, the SQL queries embedded in older code can still
  80. // execute successfully.
  81. //
  82. // For example, if an optional column is added to a table in version 3, the
  83. // new code will set the version to 3, and the compatible version to 2, since
  84. // the code expecting version 2 databases can still read and write the table.
  85. //
  86. // Rule of thumb: check the version number when you're upgrading, but check
  87. // the compatible version number to see if you can use the file at all. If
  88. // it's larger than you code is expecting, fail.
  89. //
  90. // The compatible version number will be 0 if there is no previously set
  91. // compatible version number.
  92. void SetCompatibleVersionNumber(int version);
  93. int GetCompatibleVersionNumber();
  94. // Set the given arbitrary key with the given data. Returns true on success.
  95. bool SetValue(base::StringPiece key, const std::string& value);
  96. bool SetValue(base::StringPiece key, int64_t value);
  97. // Retrieves the value associated with the given key. This will use sqlite's
  98. // type conversion rules. It will return true on success.
  99. bool GetValue(base::StringPiece key, std::string* value);
  100. bool GetValue(base::StringPiece key, int* value);
  101. bool GetValue(base::StringPiece key, int64_t* value);
  102. // Deletes the key from the table.
  103. bool DeleteKey(base::StringPiece key);
  104. private:
  105. raw_ptr<Database> db_ = nullptr;
  106. };
  107. } // namespace sql
  108. #endif // SQL_META_TABLE_H_