[sql] Scoped recovery framework.

sql/connection.h

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef SQL_CONNECTION_H_
 #define SQL_CONNECTION_H_
 
 #include <map>
 #include <set>
 #include <string>
@@ skipping 10 matching lines @@
 
 struct sqlite3;
 struct sqlite3_stmt;
 
 namespace base {
 class FilePath;
 }
 
 namespace sql {
 
+class Recovery;
 class Statement;
 
 // Uniquely identifies a statement. There are two modes of operation:
 //
 // - In the most common mode, you will use the source file and line number to
 //   identify your statement. This is a convienient way to get uniqueness for
 //   a statement that is only used in one place. Use the SQL_FROM_HERE macro
 //   to generate a StatementID.
 //
 // - In the "custom" mode you may use the statement from different places or
@@ skipping 112 matching lines @@
 
   // Initializes the SQL connection for the given file, returning true if the
   // file could be opened. You can call this or OpenInMemory.
   bool Open(const base::FilePath& path) WARN_UNUSED_RESULT;
 
   // Initializes the SQL connection for a temporary in-memory database. There
   // will be no associated file on disk, and the initial database will be
   // empty. You can call this or Open.
   bool OpenInMemory() WARN_UNUSED_RESULT;
 
+  // Create a temporary on-disk database.  The database will be
+  // deleted after close.  This kind of database is similar to
+  // OpenInMemory() for small databases, but can page to disk if the
+  // database becomes large.
+  bool OpenTemporary() WARN_UNUSED_RESULT;
+
   // Returns true if the database has been successfully opened.
   bool is_open() const { return !!db_; }
 
   // Closes the database. This is automatically performed on destruction for
   // you, but this allows you to close the database early. You must not call
   // any other functions after closing it. It is permissable to call Close on
   // an uninitialized or already-closed database.
   void Close();
 
   // Pre-loads the first <cache-size> pages into the cache from the file.
@@ skipping 38 matching lines @@
   // NOTE(shess): For Android, SQLITE_DEFAULT_AUTOVACUUM is set to 1,
   // so Raze() sets auto_vacuum to 1.
   //
   // TODO(shess): Raze() needs a connection so cannot clear SQLITE_NOTADB.
   // TODO(shess): Bake auto_vacuum into Connection's API so it can
   // just pick up the default.
   bool Raze();
   bool RazeWithTimout(base::TimeDelta timeout);
 
   // Breaks all outstanding transactions (as initiated by
-  // BeginTransaction()), calls Raze() to destroy the database, then
-  // closes the database.  After this is called, any operations
-  // against the connections (or statements prepared by the
-  // connection) should fail safely.
+  // BeginTransaction()), closes the SQLite database, and poisons the
+  // object so that all future operations against the Connection (or
+  // its Statements) fail safely, without side effects.
   //
-  // The value from Raze() is returned, with Close() called in all
-  // cases.
+  // This is intended as an alternative to Close() in error callbacks.
+  // Close() should still be called at some point.
+  void Poison();
+
+  // Raze() the database and Poison() the handle.  Returns the return
+  // value from Raze().
+  // TODO(shess): Rename to RazeAndPoison().
   bool RazeAndClose();
 
   // Delete the underlying database files associated with |path|.
   // This should be used on a database which has no existing
   // connections.  If any other connections are open to the same
   // database, this could cause odd results or corruption (for
   // instance if a hot journal is deleted but the associated database
   // is not).
   //
   // Returns true if the database file and associated journals no
   // longer exist, false otherwise.  If the database has never
   // existed, this will return true.
   static bool Delete(const base::FilePath& path);
 
   // Transactions --------------------------------------------------------------
 
   // Transaction management. We maintain a virtual transaction stack to emulate
   // nested transactions since sqlite can't do nested transactions. The
   // limitation is you can't roll back a sub transaction: if any transaction
   // fails, all transactions open will also be rolled back. Any nested
   // transactions after one has rolled back will return fail for Begin(). If
   // Begin() fails, you must not call Commit or Rollback().
   //
   // Normally you should use sql::Transaction to manage a transaction, which
   // will scope it to a C++ context.
   bool BeginTransaction();
   void RollbackTransaction();
   bool CommitTransaction();
 
+  // Rollback all outstanding transactions.  Use with care, there may
+  // be scoped transactions on the stack.
+  void RollbackAllTransactions();
+
   // Returns the current transaction nesting, which will be 0 if there are
   // no open transactions.
   int transaction_nesting() const { return transaction_nesting_; }
 
+  // Attached databases---------------------------------------------------------
+
+  // SQLite supports attaching multiple database files to a single
+  // handle.  Attach the database in |other_db_path| to the current
+  // handle under |attachment_point|.  |attachment_point| should only
+  // contain characters from [a-zA-Z0-9_].
+  //
+  // Note that calling attach or detach with an open transaction is an
+  // error.
+  bool AttachDatabase(const base::FilePath& other_db_path,
+                      const char* attachment_point);
+  bool DetachDatabase(const char* attachment_point);
+
   // Statements ----------------------------------------------------------------
 
   // Executes the given SQL string, returning true on success. This is
   // normally used for simple, 1-off statements that don't take any bound
   // parameters and don't return any data (e.g. CREATE TABLE).
   //
   // This will DCHECK if the |sql| contains errors.
   //
   // Do not use ignore_result() to ignore all errors.  Use
   // ExecuteAndReturnErrorCode() and ignore only specific errors.
@@ skipping 72 matching lines @@
 
   // Returns the errno associated with GetErrorCode().  See
   // SQLITE_LAST_ERRNO in SQLite documentation.
   int GetLastErrno() const;
 
   // Returns a pointer to a statically allocated string associated with the
   // last sqlite operation.
   const char* GetErrorMessage() const;
 
  private:
+  // For recovery module.
+  friend class Recovery;

[Scott Hess - ex-Googler, 2013/07/15 21:10:34]

Specifically for sqlite3_backup stuff.  Given that, it might be reasonable to
pull OpenTemporary(), Poison() and RollbackAllTransactions() down into private:
instead of making them publicly available.  In fact, if this all works out, even
Raze() and RazeAndClose() could be made private.

+
   // Allow test-support code to set/reset error ignorer.
   friend class ScopedErrorIgnorer;
 
   // Statement accesses StatementRef which we don't want to expose to everybody
   // (they should go through Statement).
   friend class Statement;
 
   // Internal initialize function used by both Init and InitInMemory. The file
   // name is always 8 bits since we want to use the 8-bit version of
   // sqlite3_open. The string can also be sqlite's special ":memory:" string.
@@ skipping 153 matching lines @@
 
   // Tag for auxiliary histograms.
   std::string histogram_tag_;
 
   DISALLOW_COPY_AND_ASSIGN(Connection);
 };
 
 }  // namespace sql
 
 #endif  // SQL_CONNECTION_H_