sql/statement.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_STATEMENT_H_
   6 #define SQL_STATEMENT_H_
   7
   8 #include <stdint.h>
   9 #include <string>
  10 #include <vector>
  11
  12 #include "base/component_export.h"
  13 #include "base/macros.h"
  14 #include "base/memory/ref_counted.h"
  15 #include "base/sequence_checker.h"
  16 #include "base/strings/string16.h"
  17 #include "sql/database.h"
  18
  19 namespace sql {
  20
  21 // Possible return values from ColumnType in a statement. These should match
  22 // the values in sqlite3.h.
  23 enum ColType {
  24   COLUMN_TYPE_INTEGER = 1,
  25   COLUMN_TYPE_FLOAT = 2,
  26   COLUMN_TYPE_TEXT = 3,
  27   COLUMN_TYPE_BLOB = 4,
  28   COLUMN_TYPE_NULL = 5,
  29 };
  30
  31 // Normal usage:
  32 //   sql::Statement s(connection_.GetUniqueStatement(...));
  33 //   s.BindInt(0, a);
  34 //   if (s.Step())
  35 //     return s.ColumnString(0);
  36 //
  37 //   If there are errors getting the statement, the statement will be inert; no
  38 //   mutating or database-access methods will work. If you need to check for
  39 //   validity, use:
  40 //   if (!s.is_valid())
  41 //     return false;
  42 //
  43 // Step() and Run() just return true to signal success. If you want to handle
  44 // specific errors such as database corruption, install an error handler in
  45 // in the connection object using set_error_delegate().
  46 class COMPONENT_EXPORT(SQL) Statement {
  47  public:
  48   // Creates an uninitialized statement. The statement will be invalid until
  49   // you initialize it via Assign.
  50   Statement();
  51
  52   explicit Statement(scoped_refptr<Database::StatementRef> ref);
  53   ~Statement();
  54
  55   // Initializes this object with the given statement, which may or may not
  56   // be valid. Use is_valid() to check if it's OK.
  57   void Assign(scoped_refptr<Database::StatementRef> ref);
  58
  59   // Resets the statement to an uninitialized state corrosponding to
  60   // the default constructor, releasing the StatementRef.
  61   void Clear();
  62
  63   // Returns true if the statement can be executed. All functions can still
  64   // be used if the statement is invalid, but they will return failure or some
  65   // default value. This is because the statement can become invalid in the
  66   // middle of executing a command if there is a serious error and the database
  67   // has to be reset.
  68   bool is_valid() const { return ref_->is_valid(); }
  69
  70   // Running -------------------------------------------------------------------
  71
  72   // Executes the statement, returning true on success. This is like Step but
  73   // for when there is no output, like an INSERT statement.
  74   bool Run();
  75
  76   // Executes the statement, returning true if there is a row of data returned.
  77   // You can keep calling Step() until it returns false to iterate through all
  78   // the rows in your result set.
  79   //
  80   // When Step returns false, the result is either that there is no more data
  81   // or there is an error. This makes it most convenient for loop usage. If you
  82   // need to disambiguate these cases, use Succeeded().
  83   //
  84   // Typical example:
  85   //   while (s.Step()) {
  86   //     ...
  87   //   }
  88   //   return s.Succeeded();
  89   bool Step();
  90
  91   // Resets the statement to its initial condition. This includes any current
  92   // result row, and also the bound variables if the |clear_bound_vars| is true.
  93   void Reset(bool clear_bound_vars);
  94
  95   // Returns true if the last executed thing in this statement succeeded. If
  96   // there was no last executed thing or the statement is invalid, this will
  97   // return false.
  98   bool Succeeded() const;
  99
 100   // Binding -------------------------------------------------------------------
 101
 102   // These all take a 0-based argument index and return true on success. You
 103   // may not always care about the return value (they'll DCHECK if they fail).
 104   // The main thing you may want to check is when binding large blobs or
 105   // strings there may be out of memory.
 106   bool BindNull(int col);
 107   bool BindBool(int col, bool val);
 108   bool BindInt(int col, int val);
 109   bool BindInt64(int col, int64_t val);
 110   bool BindDouble(int col, double val);
 111   bool BindCString(int col, const char* val);
 112   bool BindString(int col, const std::string& val);
 113   bool BindString16(int col, const base::string16& value);
 114   bool BindBlob(int col, const void* value, int value_len);
 115
 116   // Retrieving ----------------------------------------------------------------
 117
 118   // Returns the number of output columns in the result.
 119   int ColumnCount() const;
 120
 121   // Returns the type associated with the given column.
 122   //
 123   // Watch out: the type may be undefined if you've done something to cause a
 124   // "type conversion." This means requesting the value of a column of a type
 125   // where that type is not the native type. For safety, call ColumnType only
 126   // on a column before getting the value out in any way.
 127   ColType ColumnType(int col) const;
 128
 129   // These all take a 0-based argument index.
 130   bool ColumnBool(int col) const;
 131   int ColumnInt(int col) const;
 132   int64_t ColumnInt64(int col) const;
 133   double ColumnDouble(int col) const;
 134   std::string ColumnString(int col) const;
 135   base::string16 ColumnString16(int col) const;
 136
 137   // When reading a blob, you can get a raw pointer to the underlying data,
 138   // along with the length, or you can just ask us to copy the blob into a
 139   // vector. Danger! ColumnBlob may return nullptr if there is no data!
 140   int ColumnByteLength(int col) const;
 141   const void* ColumnBlob(int col) const;
 142   bool ColumnBlobAsString(int col, std::string* blob) const;
 143   bool ColumnBlobAsString16(int col, base::string16* val) const;
 144   bool ColumnBlobAsVector(int col, std::vector<char>* val) const;
 145   bool ColumnBlobAsVector(int col, std::vector<unsigned char>* val) const;
 146
 147   // Diagnostics --------------------------------------------------------------
 148
 149   // Returns the original text of sql statement. Do not keep a pointer to it.
 150   const char* GetSQLStatement();
 151
 152  private:
 153   friend class Database;
 154
 155   // This is intended to check for serious errors and report them to the
 156   // Database object. It takes a sqlite error code, and returns the same
 157   // code. Currently this function just updates the succeeded flag, but will be
 158   // enhanced in the future to do the notification.
 159   int CheckError(int err);
 160
 161   // Contraction for checking an error code against SQLITE_OK. Does not set the
 162   // succeeded flag.
 163   bool CheckOk(int err) const;
 164
 165   // Should be called by all mutating methods to check that the statement is
 166   // valid. Returns true if the statement is valid. DCHECKS and returns false
 167   // if it is not.
 168   // The reason for this is to handle two specific cases in which a Statement
 169   // may be invalid. The first case is that the programmer made an SQL error.
 170   // Those cases need to be DCHECKed so that we are guaranteed to find them
 171   // before release. The second case is that the computer has an error (probably
 172   // out of disk space) which is prohibiting the correct operation of the
 173   // database. Our testing apparatus should not exhibit this defect, but release
 174   // situations may. Therefore, the code is handling disjoint situations in
 175   // release and test. In test, we're ensuring correct SQL. In release, we're
 176   // ensuring that contracts are honored in error edge cases.
 177   bool CheckValid() const;
 178
 179   // Helper for Run() and Step(), calls sqlite3_step() and then generates
 180   // sql::Database histograms based on the results.  Timing and change count
 181   // are only recorded if |timer_flag| is true.  The checked value from
 182   // sqlite3_step() is returned.
 183   int StepInternal(bool timer_flag);
 184
 185   // sql::Database uses cached statments for transactions, but tracks their
 186   // runtime independently.
 187   bool RunWithoutTimers();
 188
 189   // The actual sqlite statement. This may be unique to us, or it may be cached
 190   // by the Database, which is why it's ref-counted. This pointer is
 191   // guaranteed non-null.
 192   scoped_refptr<Database::StatementRef> ref_;
 193
 194   // Set after Step() or Run() are called, reset by Reset().  Used to
 195   // prevent accidental calls to API functions which would not work
 196   // correctly after stepping has started.
 197   bool stepped_;
 198
 199   // See Succeeded() for what this holds.
 200   bool succeeded_;
 201
 202   DISALLOW_COPY_AND_ASSIGN(Statement);
 203 };
 204
 205 }  // namespace sql
 206
 207 #endif  // SQL_STATEMENT_H_