hphp/util/sqlite-wrapper.h

   1 /*
   2    +----------------------------------------------------------------------+
   3    | HipHop for PHP                                                       |
   4    +----------------------------------------------------------------------+
   5    | Copyright (c) 2010-present Facebook, Inc. (http://www.facebook.com)  |
   6    +----------------------------------------------------------------------+
   7    | This source file is subject to version 3.01 of the PHP license,      |
   8    | that is bundled with this package in the file LICENSE, and is        |
   9    | available through the world-wide-web at the following url:           |
  10    | http://www.php.net/license/3_01.txt                                  |
  11    | If you did not receive a copy of the PHP license and are unable to   |
  12    | obtain it through the world-wide-web, please send a note to          |
  13    | license@php.net so we can mail you a copy immediately.               |
  14    +----------------------------------------------------------------------+
  15 */
  16
  17 #pragma once
  18
  19 #include <string>
  20
  21 #include "hphp/util/sqlite-wrapper-helpers.h"
  22
  23 struct sqlite3;
  24
  25 namespace HPHP {
  26
  27 /**
  28  * RAII wrapper around a sqlite3 database connection.
  29  *
  30  * Use with:
  31  *
  32  *   SQLite& db = SQLite::get(":memory:");
  33  *
  34  *   SQLiteTxn txn = db.begin();
  35  *   txn.exec("CREATE TABLE foo (bar)");
  36  *
  37  *   SQLiteStmt insertStmt = db.prepare("INSERT INTO foo VALUES (@v)");
  38  *   for (auto i = 0; i < 10; i++) {
  39  *     SQLiteQuery query = db.query(insertStmt);
  40  *
  41  *     query.bindInt("@v", i);
  42  *     query.step();
  43  *   }
  44  *
  45  *   SQLiteStmt selectStmt = db.prepare("SELECT bar FROM foo;");
  46  *   SQLiteQuery query = txn.query(selectStmt);
  47  *   for (; !query.done(); query.step()) {
  48  *     std::cout << query.getInt(0) << std::endl;
  49  *   }
  50  *
  51  */
  52 struct SQLite {
  53   SQLite(SQLite&&) noexcept;
  54   SQLite& operator=(SQLite&&) noexcept;
  55   ~SQLite();
  56
  57   /**
  58    * Run `ANALYZE` to improve query planning.
  59    *
  60    * We recommend you run this method after creating the DB and
  61    * loading it with data.
  62    *
  63    * https://sqlite.org/lang_analyze.html
  64    */
  65   void analyze();
  66
  67   enum class OpenMode {
  68     ReadOnly = 1,
  69     ReadWrite = 2
  70   };
  71
  72   /**
  73    * Return a new SQLite connection, creating the DB file if necessary.
  74    *
  75    * path is the location of the DB in your filesystem, or ":memory:"
  76    * if you want to store data in memory instead.
  77    */
  78   static SQLite connect(const std::string& path,
  79                         OpenMode mode = OpenMode::ReadWrite);
  80   static SQLite connect(const char* path, OpenMode mode = OpenMode::ReadWrite);
  81
  82   /**
  83    * Compile the given SQL query into a statement object which can run and rerun
  84    * the query.
  85    */
  86   SQLiteStmt prepare(const std::string_view sql);  // throws(SQLiteExc)
  87
  88   /**
  89    * Begin a SQLite transaction to run queries within.
  90    */
  91   SQLiteTxn begin();
  92
  93   /**
  94    * Sleep for a time up to the given maximum when the DB is locked.
  95    *
  96    * Setting a number equal to 0 or less than zero will disable the
  97    * busy timeout.
  98    */
  99   void setBusyTimeout(int ms) noexcept;
 100
 101   enum class JournalMode {
 102     // Default behavior. During each transaction, create a rollback journal
 103     // with the extension `.sql3-journal` file during each transaction, and
 104     // delete it when the transaction is committed or rolled back.
 105     DELETE,
 106
 107     // Truncate the rollback journal to 0 bytes instead of deleting it from
 108     // the filesystem.
 109     TRUNCATE,
 110
 111     // Instead of deleting or truncating the rollback journal, overwrite the
 112     // header with null bytes.
 113     PERSIST,
 114
 115     // Instead of creating the rollback journal on-disk, store the journal
 116     // in-memory. This may cause your database to become corrupt if your
 117     // application crashes in the middle of a write transaction.
 118     MEMORY,
 119
 120     // Instead of creating a rollback journal, create a write-ahead log file
 121     // with the extension `.sql3-wal`.
 122     WAL,
 123
 124     // Don't use a rollback journal at all. The behavior of the ROLLBACK
 125     // command will be undefined if you enable this, and application crashes
 126     // in the middle of a transaction can easily cause the db to become
 127     // corrupt.
 128     OFF
 129   };
 130
 131   /**
 132    * Set SQLite's journaling mode.
 133    *
 134    * Journaling is the mechanism that SQLite uses to rollback transactions,
 135    * recover from crashes and exceptions, and prevent other processes/threads
 136    * from seeing data that hasn't officially been committed yet.
 137    */
 138   void setJournalMode(JournalMode mode);
 139
 140   enum class SynchronousLevel {
 141     // Trust the filesystem to fsync for you. This may result in database
 142     // corruption if power loss occurs.
 143     OFF = 0,
 144
 145     // Sync often enough to guarantee consistency in WAL mode.
 146     NORMAL = 1,
 147
 148     // Sync on every write.
 149     FULL = 2,
 150
 151     // On every write, sync the SQLite DB, its journal or WAL, and the
 152     // directory containing the files.
 153     EXTRA = 3,
 154   };
 155
 156   /**
 157    * Tell SQLite when to fsync the DB.
 158    *
 159    * https://www.sqlite.org/pragma.html#pragma_synchronous
 160    */
 161   void setSynchronousLevel(SynchronousLevel lvl);
 162
 163   /**
 164    * True iff this wrapper points to a valid SQLite connection.
 165    *
 166    * This will be false if we've moved a connection out of this object.
 167    */
 168   operator bool() const noexcept {
 169     return m_dbc != nullptr;
 170   }
 171
 172   bool operator!() const noexcept {
 173     return m_dbc == nullptr;
 174   }
 175
 176   /**
 177    * True iff the database is read-only.
 178    *
 179    * dbName: The name you've given to a database you ATTACHed to your
 180    * connection, or "main" by default.
 181    */
 182   bool isReadOnly() const;
 183   bool isReadOnly(const std::string& dbName) const;
 184   bool isReadOnly(const char* dbName) const;
 185
 186   /**
 187    * Return the most recent error message from SQLite.
 188    */
 189   std::string errMsg() const noexcept;
 190
 191  private:
 192   friend struct SQLiteStmt;
 193   friend struct SQLiteTxn;
 194
 195   explicit SQLite(sqlite3* dbc);
 196
 197   SQLite() = delete;
 198   SQLite(const SQLite&) = delete;
 199   SQLite& operator=(const SQLite&) = delete;
 200
 201   void txPush();  // throws(SQLiteExc)
 202   void txPop();   // throws(SQLiteExc)
 203   void rollback() noexcept;
 204   void commit();  // throws(SQLiteExc)
 205
 206   sqlite3* m_dbc = nullptr;
 207   unsigned m_txDepth = 0;   // Transaction nesting depth.
 208   bool m_rollback = false;  // If true, rollback rather than commit.
 209
 210   SQLiteStmt m_beginStmt;
 211   SQLiteStmt m_rollbackStmt;
 212   SQLiteStmt m_commitStmt;
 213 };
 214
 215 }  // namespace HPHP