sql/statement.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_STATEMENT_H_
   6 #define SQL_STATEMENT_H_
   7
   8 #include <stdint.h>
   9
  10 #include <string>
  11 #include <vector>
  12
  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"
  22
  23 namespace sql {
  24
  25 enum class SqliteResultCode : int;
  26
  27 // Possible return values from ColumnType in a statement. These should match
  28 // the values in sqlite3.h.
  29 enum class ColumnType {
  30   kInteger = 1,
  31   kFloat = 2,
  32   kText = 3,
  33   kBlob = 4,
  34   kNull = 5,
  35 };
  36
  37 // Compiles and executes SQL statements.
  38 //
  39 // This class is not thread-safe. An instance must be accessed from a single
  40 // sequence. This is enforced in DCHECK-enabled builds.
  41 //
  42 // Normal usage:
  43 //   sql::Statement s(connection_.GetUniqueStatement(...));
  44 //   s.BindInt(0, a);
  45 //   if (s.Step())
  46 //     return s.ColumnString(0);
  47 //
  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
  50 //   validity, use:
  51 //   if (!s.is_valid())
  52 //     return false;
  53 //
  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 {
  58  public:
  59   // Creates an uninitialized statement. The statement will be invalid until
  60   // you initialize it via Assign.
  61   Statement();
  62
  63   explicit Statement(scoped_refptr<Database::StatementRef> ref);
  64
  65   Statement(const Statement&) = delete;
  66   Statement& operator=(const Statement&) = delete;
  67
  68   Statement(Statement&&) = delete;
  69   Statement& operator=(Statement&&) = delete;
  70
  71   ~Statement();
  72
  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);
  76
  77   // Resets the statement to an uninitialized state corresponding to
  78   // the default constructor, releasing the StatementRef.
  79   void Clear();
  80
  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
  85   // has to be reset.
  86   bool is_valid() const {
  87     DCHECK_CALLED_ON_VALID_SEQUENCE(sequence_checker_);
  88
  89     return ref_->is_valid();
  90   }
  91
  92   // Running -------------------------------------------------------------------
  93
  94   // Executes the statement, returning true on success. This is like Step but
  95   // for when there is no output, like an INSERT statement.
  96   bool Run();
  97
  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.
 101   //
 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().
 105   //
 106   // Typical example:
 107   //   while (s.Step()) {
 108   //     ...
 109   //   }
 110   //   return s.Succeeded();
 111   bool Step();
 112
 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);
 116
 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
 119   // return false.
 120   bool Succeeded() const;
 121
 122   // Binding -------------------------------------------------------------------
 123
 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);
 137
 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)));
 141   }
 142
 143   // Conforms with base::Time serialization recommendations.
 144   //
 145   // This is equivalent to the following snippets, which should be replaced.
 146   // * BindInt64(col, val.ToInternalValue())
 147   // * BindInt64(col, val.ToDeltaSinceWindowsEpoch().InMicroseconds())
 148   //
 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.
 152   //
 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);
 156
 157   // Retrieving ----------------------------------------------------------------
 158
 159   // Returns the number of output columns in the result.
 160   int ColumnCount() const;
 161
 162   // Returns the type associated with the given column.
 163   //
 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);
 169
 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);
 177
 178   // Conforms with base::Time serialization recommendations.
 179   //
 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)))
 184   //
 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);
 188
 189   // Returns a span pointing to a buffer containing the blob data.
 190   //
 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.
 193   //
 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);
 198
 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);
 202
 203   // Diagnostics --------------------------------------------------------------
 204
 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();
 209
 210  private:
 211   friend class Database;
 212
 213   // Checks SQLite result codes and handles any errors.
 214   //
 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.
 218   //
 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);
 222
 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
 225   // if it is not.
 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;
 236
 237   // Helper for Run() and Step(), calls sqlite3_step() and returns the checked
 238   // value from it.
 239   SqliteResultCode StepInternal();
 240
 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_);
 246
 247   // See Succeeded() for what this holds.
 248   bool succeeded_ GUARDED_BY_CONTEXT(sequence_checker_) = false;
 249
 250 #if DCHECK_IS_ON()
 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()
 255
 256   SEQUENCE_CHECKER(sequence_checker_);
 257 };
 258
 259 }  // namespace sql
 260
 261 #endif  // SQL_STATEMENT_H_