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.
5 #ifndef SQL_META_TABLE_H_
6 #define SQL_META_TABLE_H_
11 #include "base/macros.h"
12 #include "sql/sql_export.h"
19 // Creates and manages a table to store generic metadata. The features provided
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 SQL_EXPORT MetaTable {
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;
37 // Returns true if the 'meta' table exists.
38 static bool DoesTableExist(Connection* db);
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
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
51 static void RazeIfDeprecated(Connection* db, int deprecated_version);
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(Connection* db, int64_t* status);
57 static bool SetMmapStatus(Connection* db, int64_t status);
59 // Initializes the MetaTableHelper, providing the |Connection| 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(Connection* db, int version, int compatible_version);
68 // Resets this MetaTable object, making another call to Init() possible.
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.
75 // See also Get/SetCompatibleVersionNumber().
76 void SetVersionNumber(int version);
77 int GetVersionNumber();
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.
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.
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.
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();
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);
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);
107 // Deletes the key from the table.
108 bool DeleteKey(const char* key);
111 // Conveniences to prepare the two types of statements used by
113 void PrepareSetStatement(Statement* statement, const char* key);
114 bool PrepareGetStatement(Statement* statement, const char* key);
118 DISALLOW_COPY_AND_ASSIGN(MetaTable);
123 #endif // SQL_META_TABLE_H_