sql/meta_table.h

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