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_STATEMENT_H_
6 #define SQL_STATEMENT_H_
13 #include "base/component_export.h"
14 #include "base/containers/span.h"
15 #include "base/dcheck_is_on.h"
16 #include "base/memory/ref_counted.h"
17 #include "base/sequence_checker.h"
18 #include "base/strings/string_piece_forward.h"
19 #include "base/thread_annotations.h"
20 #include "base/time/time.h"
21 #include "sql/database.h"
25 enum class SqliteResultCode : int;
27 // Possible return values from ColumnType in a statement. These should match
28 // the values in sqlite3.h.
29 enum class ColumnType {
37 // Compiles and executes SQL statements.
39 // This class is not thread-safe. An instance must be accessed from a single
40 // sequence. This is enforced in DCHECK-enabled builds.
43 // sql::Statement s(connection_.GetUniqueStatement(...));
46 // return s.ColumnString(0);
48 // If there are errors getting the statement, the statement will be inert; no
49 // mutating or database-access methods will work. If you need to check for
54 // Step() and Run() just return true to signal success. If you want to handle
55 // specific errors such as database corruption, install an error handler in
56 // in the connection object using set_error_delegate().
57 class COMPONENT_EXPORT(SQL) Statement {
59 // Creates an uninitialized statement. The statement will be invalid until
60 // you initialize it via Assign.
63 explicit Statement(scoped_refptr<Database::StatementRef> ref);
65 Statement(const Statement&) = delete;
66 Statement& operator=(const Statement&) = delete;
68 Statement(Statement&&) = delete;
69 Statement& operator=(Statement&&) = delete;
73 // Initializes this object with the given statement, which may or may not
74 // be valid. Use is_valid() to check if it's OK.
75 void Assign(scoped_refptr<Database::StatementRef> ref);
77 // Resets the statement to an uninitialized state corresponding to
78 // the default constructor, releasing the StatementRef.
81 // Returns true if the statement can be executed. All functions can still
82 // be used if the statement is invalid, but they will return failure or some
83 // default value. This is because the statement can become invalid in the
84 // middle of executing a command if there is a serious error and the database
86 bool is_valid() const {
87 DCHECK_CALLED_ON_VALID_SEQUENCE(sequence_checker_);
89 return ref_->is_valid();
92 // Running -------------------------------------------------------------------
94 // Executes the statement, returning true on success. This is like Step but
95 // for when there is no output, like an INSERT statement.
98 // Executes the statement, returning true if there is a row of data returned.
99 // You can keep calling Step() until it returns false to iterate through all
100 // the rows in your result set.
102 // When Step returns false, the result is either that there is no more data
103 // or there is an error. This makes it most convenient for loop usage. If you
104 // need to disambiguate these cases, use Succeeded().
107 // while (s.Step()) {
110 // return s.Succeeded();
113 // Resets the statement to its initial condition. This includes any current
114 // result row, and also the bound variables if the |clear_bound_vars| is true.
115 void Reset(bool clear_bound_vars);
117 // Returns true if the last executed thing in this statement succeeded. If
118 // there was no last executed thing or the statement is invalid, this will
120 bool Succeeded() const;
122 // Binding -------------------------------------------------------------------
124 // These all take a 0-based parameter index and return true on success.
125 // strings there may be out of memory.
126 void BindNull(int param_index);
127 void BindBool(int param_index, bool val);
128 void BindInt(int param_index, int val);
129 void BindInt(int param_index,
130 int64_t val) = delete; // Call BindInt64() instead.
131 void BindInt64(int param_index, int64_t val);
132 void BindDouble(int param_index, double val);
133 void BindCString(int param_index, const char* val);
134 void BindString(int param_index, base::StringPiece val);
135 void BindString16(int param_index, base::StringPiece16 value);
136 void BindBlob(int param_index, base::span<const uint8_t> value);
138 // Overload that makes it easy to pass in std::string values.
139 void BindBlob(int param_index, base::span<const char> value) {
140 BindBlob(param_index, base::as_bytes(base::make_span(value)));
143 // Conforms with base::Time serialization recommendations.
145 // This is equivalent to the following snippets, which should be replaced.
146 // * BindInt64(col, val.ToInternalValue())
147 // * BindInt64(col, val.ToDeltaSinceWindowsEpoch().InMicroseconds())
149 // Features that serialize base::Time in other ways, such as ToTimeT() or
150 // ToJavaTime(), will require a database migration to be converted to this
151 // (recommended) serialization method.
153 // TODO(crbug.com/1195962): Migrate all time serialization to this method, and
154 // then remove the migration details above.
155 void BindTime(int param_index, base::Time time);
157 // Retrieving ----------------------------------------------------------------
159 // Returns the number of output columns in the result.
160 int ColumnCount() const;
162 // Returns the type associated with the given column.
164 // Watch out: the type may be undefined if you've done something to cause a
165 // "type conversion." This means requesting the value of a column of a type
166 // where that type is not the native type. For safety, call ColumnType only
167 // on a column before getting the value out in any way.
168 ColumnType GetColumnType(int col);
170 // These all take a 0-based argument index.
171 bool ColumnBool(int column_index);
172 int ColumnInt(int column_index);
173 int64_t ColumnInt64(int column_index);
174 double ColumnDouble(int column_index);
175 std::string ColumnString(int column_index);
176 std::u16string ColumnString16(int column_index);
178 // Conforms with base::Time serialization recommendations.
180 // This is equivalent to the following snippets, which should be replaced.
181 // * base::Time::FromInternalValue(ColumnInt64(col))
182 // * base::Time::FromDeltaSinceWindowsEpoch(
183 // base::Microseconds(ColumnInt64(col)))
185 // TODO(crbug.com/1195962): Migrate all time serialization to this method, and
186 // then remove the migration details above.
187 base::Time ColumnTime(int column_index);
189 // Returns a span pointing to a buffer containing the blob data.
191 // The span's contents should be copied to a caller-owned buffer immediately.
192 // Any method call on the Statement may invalidate the span.
194 // The span will be empty (and may have a null data) if the underlying blob is
195 // empty. Code that needs to distinguish between empty blobs and NULL should
196 // call GetColumnType() before calling ColumnBlob().
197 base::span<const uint8_t> ColumnBlob(int column_index);
199 bool ColumnBlobAsString(int column_index, std::string* result);
200 bool ColumnBlobAsVector(int column_index, std::vector<char>* result);
201 bool ColumnBlobAsVector(int column_index, std::vector<uint8_t>* result);
203 // Diagnostics --------------------------------------------------------------
205 // Returns the original text of a SQL statement WITHOUT any bound values.
206 // Intended for logging in case of failures. Note that DOES NOT return any
207 // bound values, because that would cause a privacy / PII issue for logging.
208 std::string GetSQLStatement();
211 friend class Database;
213 // Checks SQLite result codes and handles any errors.
215 // Returns `sqlite_result_code`. This gives callers the convenience of writing
216 // "return CheckSqliteResultCode(sqlite_result_code)" and gives the compiler
217 // the opportunity of doing tail call optimization (TCO) on the code above.
219 // This method reports error codes to the associated Database, and updates
220 // internal state to reflect whether the statement succeeded or not.
221 SqliteResultCode CheckSqliteResultCode(SqliteResultCode sqlite_result_code);
223 // Should be called by all mutating methods to check that the statement is
224 // valid. Returns true if the statement is valid. DCHECKS and returns false
226 // The reason for this is to handle two specific cases in which a Statement
227 // may be invalid. The first case is that the programmer made an SQL error.
228 // Those cases need to be DCHECKed so that we are guaranteed to find them
229 // before release. The second case is that the computer has an error (probably
230 // out of disk space) which is prohibiting the correct operation of the
231 // database. Our testing apparatus should not exhibit this defect, but release
232 // situations may. Therefore, the code is handling disjoint situations in
233 // release and test. In test, we're ensuring correct SQL. In release, we're
234 // ensuring that contracts are honored in error edge cases.
235 bool CheckValid() const;
237 // Helper for Run() and Step(), calls sqlite3_step() and returns the checked
239 SqliteResultCode StepInternal();
241 // The actual sqlite statement. This may be unique to us, or it may be cached
242 // by the Database, which is why it's ref-counted. This pointer is
243 // guaranteed non-null.
244 scoped_refptr<Database::StatementRef> ref_
245 GUARDED_BY_CONTEXT(sequence_checker_);
247 // See Succeeded() for what this holds.
248 bool succeeded_ GUARDED_BY_CONTEXT(sequence_checker_) = false;
251 // Used to DCHECK() that Bind*() is called before Step() or Run() are called.
252 bool step_called_ GUARDED_BY_CONTEXT(sequence_checker_) = false;
253 bool run_called_ GUARDED_BY_CONTEXT(sequence_checker_) = false;
254 #endif // DCHECK_IS_ON()
256 SEQUENCE_CHECKER(sequence_checker_);
261 #endif // SQL_STATEMENT_H_