sql/meta_table.h

   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
   5 #ifndef SQL_META_TABLE_H_
   6 #define SQL_META_TABLE_H_
   7
   8 #include <stdint.h>
   9 #include <string>
  10
  11 #include "base/component_export.h"
  12 #include "base/macros.h"
  13
  14 namespace sql {
  15
  16 class Database;
  17 class Statement;
  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();
  29
  30   // Values for Get/SetMmapStatus(). |kMmapFailure| indicates that there was at
  31   // some point a read error and the database should not be memory-mapped, while
  32   // |kMmapSuccess| indicates that the entire file was read at some point and
  33   // can be memory-mapped without constraint.
  34   static constexpr int64_t kMmapFailure = -2;
  35   static constexpr int64_t kMmapSuccess = -1;
  36
  37   // Returns true if the 'meta' table exists.
  38   static bool DoesTableExist(Database* db);
  39
  40   // If the current version of the database is less than or equal to
  41   // |deprecated_version|, raze the database. Must be called outside of a
  42   // transaction.
  43   // TODO(shess): At this time the database is razed IFF meta exists and
  44   // contains a version row with value <= deprecated_version. It may make sense
  45   // to also raze if meta exists but has no version row, or if meta doesn't
  46   // exist. In those cases if the database is not already empty, it probably
  47   // resulted from a broken initialization.
  48   // TODO(shess): Folding this into Init() would allow enforcing
  49   // |deprecated_version|<|version|. But Init() is often called in a
  50   // transaction.
  51   static void RazeIfDeprecated(Database* db, int deprecated_version);
  52
  53   // Used to tuck some data into the meta table about mmap status. The value
  54   // represents how much data in bytes has successfully been read from the
  55   // database, or |kMmapFailure| or |kMmapSuccess|.
  56   static bool GetMmapStatus(Database* db, int64_t* status);
  57   static bool SetMmapStatus(Database* db, int64_t status);
  58
  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
  68   // Resets this MetaTable object, making another call to Init() possible.
  69   void Reset();
  70
  71   // The version number of the database. This should be the version number of
  72   // the creator of the file. The version number will be 0 if there is no
  73   // previously set version number.
  74   //
  75   // See also Get/SetCompatibleVersionNumber().
  76   void SetVersionNumber(int version);
  77   int GetVersionNumber();
  78
  79   // The compatible version number is the lowest version of the code that this
  80   // database can be read by. If there are minor changes or additions, old
  81   // versions of the code can still work with the database without failing.
  82   //
  83   // For example, if an optional column is added to a table in version 3, the
  84   // new code will set the version to 3, and the compatible version to 2, since
  85   // the code expecting version 2 databases can still read and write the table.
  86   //
  87   // Rule of thumb: check the version number when you're upgrading, but check
  88   // the compatible version number to see if you can read the file at all. If
  89   // it's larger than you code is expecting, fail.
  90   //
  91   // The compatible version number will be 0 if there is no previously set
  92   // compatible version number.
  93   void SetCompatibleVersionNumber(int version);
  94   int GetCompatibleVersionNumber();
  95
  96   // Set the given arbitrary key with the given data. Returns true on success.
  97   bool SetValue(const char* key, const std::string& value);
  98   bool SetValue(const char* key, int value);
  99   bool SetValue(const char* key, int64_t value);
 100
 101   // Retrieves the value associated with the given key. This will use sqlite's
 102   // type conversion rules. It will return true on success.
 103   bool GetValue(const char* key, std::string* value);
 104   bool GetValue(const char* key, int* value);
 105   bool GetValue(const char* key, int64_t* value);
 106
 107   // Deletes the key from the table.
 108   bool DeleteKey(const char* key);
 109
 110  private:
 111   // Conveniences to prepare the two types of statements used by
 112   // MetaTableHelper.
 113   void PrepareSetStatement(Statement* statement, const char* key);
 114   bool PrepareGetStatement(Statement* statement, const char* key);
 115
 116   Database* db_;
 117
 118   DISALLOW_COPY_AND_ASSIGN(MetaTable);
 119 };
 120
 121 }  // namespace sql
 122
 123 #endif  // SQL_META_TABLE_H_