[sql] Database recovery system for Shortcuts.

sql/recovery.h

 // Copyright 2013 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_RECOVERY_H_
 #define SQL_RECOVERY_H_
 
 #include <stddef.h>
 
 #include <memory>
 
 #include "base/macros.h"
 #include "sql/connection.h"
 
 namespace base {
 class FilePath;
 }
 
 namespace sql {
 
-// Recovery module for sql/.  The basic idea is to create a fresh
-// database and populate it with the recovered contents of the
-// original database.  If recovery is successful, the recovered
-// database is backed up over the original database.  If recovery is
-// not successful, the original database is razed.  In either case,
-// the original handle is poisoned so that operations on the stack do
-// not accidentally disrupt the restored data.
+// Recovery module for sql/.  The basic idea is to create a fresh database and
+// populate it with the recovered contents of the original database.  If
+// recovery is successful, the recovered database is backed up over the original
+// database.  If recovery is not successful, the original database is razed.  In
+// either case, the original handle is poisoned so that operations on the stack
+// do not accidentally disrupt the restored data.
+//
+// RecoverDatabaseOrRaze() automates this, including recoverying the schema of
+// from the suspect database.  If a database requires special handling, such as
+// recovering between different schema, or tables requiring post-processing,
+// then the module can be used manually like:
 //
 // {
 //   std::unique_ptr<sql::Recovery> r =
 //       sql::Recovery::Begin(orig_db, orig_db_path);
 //   if (r) {
 //     // Create the schema to recover to.  On failure, clear the
 //     // database.
 //     if (!r.db()->Execute(kCreateSchemaSql)) {
 //       sql::Recovery::Unrecoverable(std::move(r));
 //       return;
@@ skipping 106 matching lines @@
   // table as needed.
   bool SetupMeta();
 
   // Fetch the version number from temp.recover_meta.  Returns false
   // if the query fails, or if there is no version row.  Otherwise
   // returns true, with the version in |*version_number|.
   //
   // Only valid to call after successful SetupMeta().
   bool GetMetaVersionNumber(int* version_number);
 
+  // Attempt to recover the database by creating a new database with schema from
+  // |db|, then copying over as much data as possible.  After this call, the
+  // |db| handle will be poisoned so that future calls will return errors until
+  // the handle is re-opened.
+  //
+  // If a corrupt database contains tables without unique indices, the resulting
+  // table may contain duplication.  If this is not acceptable, the client
+  // should use the manual process as described in the example at the top of the
+  // file, cleaning up data at the appropriate points.
+  static void RecoverDatabase(Connection* db, const base::FilePath& db_path);
+
+  // Returns true for SQLite errors which RecoverDatabase() could plausibly fix.
+  // This does not guarantee that RecoverDatabase() will successfully recover
+  // the database.  Returning false means the error is not related to the
+  // contents of the database (such as SQLITE_BUSY or SQLITE_MISUSE), or is not
+  // verified to be recovered correctly (such as SQLITE_IOERR or SQLITE_FULL).

[Mark P, 2016/06/27 23:20:13]

nit: recovered -> recoverable ?

[Scott Hess - ex-Googler, 2016/06/29 21:39:30]

I'm just going to remove the entire "why false" case, and just let the "why
true" case stand alone.

I intentionally avoided language like "Do not call RecoverDatabase() unless this
returns true", because it actually doesn't matter.  The code doesn't work better
or worse based on this error code, the caller just shouldn't dump all errors
into recovery because of the goal of strongly flagging newly-introduced errors
like SQLITE_ERROR or SQLITE_MISUSE.

[Mark P, 2016/07/01 22:40:55]

Good move.
Acknowledged.

+  static bool ShouldRecover(int extended_error);
+
  private:
   explicit Recovery(Connection* connection);
 
   // Setup the recovery database handle for Begin().  Returns false in
   // case anything failed.
   bool Init(const base::FilePath& db_path) WARN_UNUSED_RESULT;
 
   // Copy the recovered database over the original database.
   bool Backup() WARN_UNUSED_RESULT;
 
   // Close the recovery database, and poison the original handle.
   // |raze| controls whether the original database is razed or just
   // poisoned.
   enum Disposition {
     RAZE_AND_POISON,
     POISON,
   };
   void Shutdown(Disposition raze);
 
   Connection* db_;         // Original database connection.
   Connection recover_db_;  // Recovery connection.
 
   DISALLOW_COPY_AND_ASSIGN(Recovery);
 };
 
 }  // namespace sql
 
 #endif  // SQL_RECOVERY_H_