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.
5 #ifndef SQL_META_TABLE_H_
6 #define SQL_META_TABLE_H_
11 #include "base/component_export.h"
12 #include "base/memory/raw_ptr.h"
13 #include "base/strings/string_piece_forward.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 COMPONENT_EXPORT(SQL) MetaTable {
28 MetaTable(const MetaTable&) = delete;
29 MetaTable& operator=(const MetaTable&) = delete;
30 MetaTable(MetaTable&&) = delete;
31 MetaTable& operator=(MetaTable&&) = delete;
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;
41 // Returns true if the 'meta' table exists.
42 static bool DoesTableExist(Database* db);
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
47 static bool DeleteTableForTesting(Database* db);
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`.
55 // Returns false if razing the database was necessary but failed or if
56 // determining the metadata version failed.
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,
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);
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);
85 // Resets this MetaTable object, making another call to Init() possible.
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.
92 // See also Get/SetCompatibleVersionNumber().
93 [[nodiscard]] bool SetVersionNumber(int version);
94 int GetVersionNumber();
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.
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.
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.
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();
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);
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);
125 // Deletes the key from the table.
126 bool DeleteKey(base::StringPiece key);
129 raw_ptr<Database, DanglingUntriaged> db_ = nullptr;
134 #endif // SQL_META_TABLE_H_