Add a new wrapper for sqlite. This is mostly a large cleanup of the existing

one, combined with the statement cache in a nice way. It is designed to
entirely wrap sqlite so that we can catch corrupt errors in the future and
"do something" when we get them without having to change all the calling code.

There is also a new meta_table file which is almost exactly like the old one
but which uses the new sql interface.

This patch changes Chrome's history TextDatabase to use this new wrapper as a
proof of concept, because this usage is relatively well-confined.
Review URL: http://codereview.chromium.org/199047

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@26022 0039d316-1c4b-4281-b951-d872f2087c98

1 files changed, 310 insertions, 0 deletions

diff --git a/app/sql/connection.h b/app/sql/connection.h
new file mode 100644
index 0000000..2948980
--- /dev/null
+++ b/app/sql/connection.h
@@ -0,0 +1,310 @@
+// Copyright (c) 2009 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 APP_SQL_CONNECTION_H_
+#define APP_SQL_CONNECTION_H_
+
+#include <map>
+#include <set>
+
+#include "base/basictypes.h"
+#include "base/ref_counted.h"
+
+class FilePath;
+struct sqlite3;
+struct sqlite3_stmt;
+
+namespace sql {
+
+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
+//   need to manage it yourself for whatever reason. In this case, you should
+//   make up your own unique name and pass it to the StatementID. This name
+//   must be a static string, since this object only deals with pointers and
+//   assumes the underlying string doesn't change or get deleted.
+//
+// This object is copyable and assignable using the compiler-generated
+// operator= and copy constructor.
+class StatementID {
+ public:
+  // Creates a uniquely named statement with the given file ane line number.
+  // Normally you will use SQL_FROM_HERE instead of calling yourself.
+  StatementID(const char* file, int line)
+      : number_(line),
+        str_(file) {
+  }
+
+  // Creates a uniquely named statement with the given user-defined name.
+  explicit StatementID(const char* unique_name)
+      : number_(-1),
+        str_(unique_name) {
+  }
+
+  // This constructor is unimplemented and will generate a linker error if
+  // called. It is intended to try to catch people dynamically generating
+  // a statement name that will be deallocated and will cause a crash later.
+  // All strings must be static and unchanging!
+  explicit StatementID(const std::string& dont_ever_do_this);
+
+  // We need this to insert into our map.
+  bool operator<(const StatementID& other) const;
+
+ private:
+  int number_;
+  const char* str_;
+};
+
+#define SQL_FROM_HERE sql::StatementID(__FILE__, __LINE__)
+
+class Connection {
+ private:
+  class StatementRef;  // Forward declaration, see real one below.
+
+ public:
+  // The database is opened by calling Init(). Any uncommitted transactions
+  // will be rolled back when this object is deleted.
+  Connection();
+  ~Connection();
+
+  // Pre-init configuration ----------------------------------------------------
+
+  // Sets the page size that will be used when creating a new adtabase. This
+  // must be called before Init(), and will only have an effect on new
+  // databases.
+  //
+  // From sqlite.org: "The page size must be a power of two greater than or
+  // equal to 512 and less than or equal to SQLITE_MAX_PAGE_SIZE. The maximum
+  // value for SQLITE_MAX_PAGE_SIZE is 32768."
+  void set_page_size(int page_size) { page_size_ = page_size; }
+
+  // Sets the number of pages that will be cached in memory by sqlite. The
+  // total cache size in bytes will be page_size * cache_size. This must be
+  // called before Init() to have an effect.
+  void set_cache_size(int cache_size) { cache_size_ = cache_size; }
+
+  // Call to put the database in exclusive locking mode. There is no "back to
+  // normal" flag because of some additional requirements sqlite puts on this
+  // transaition (requires another access to the DB) and because we don't
+  // actually need it.
+  //
+  // Exclusive mode means that the database is not unlocked at the end of each
+  // transaction, which means there may be less time spent initializing the
+  // next transaction because it doesn't have to re-aquire locks.
+  //
+  // This must be called before Init() to have an effect.
+  void set_exclusive_locking() { exclusive_locking_ = true; }
+
+  // Initialization ------------------------------------------------------------
+
+  // Initializes the SQL connection for the given file, returning true if the
+  // file could be opened.
+  bool Init(const FilePath& path);
+
+  // 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.
+  // If you expect to soon use a substantial portion of the database, this
+  // is much more efficient than allowing the pages to be populated organically
+  // since there is no per-page hard drive seeking. If the file is larger than
+  // the cache, the last part that doesn't fit in the cache will be brought in
+  // organically.
+  //
+  // This function assumes your class is using a meta table on the current
+  // database, as it openes a transaction on the meta table to force the
+  // database to be initialized. You should feel free to initialize the meta
+  // table after calling preload since the meta table will already be in the
+  // database if it exists, and if it doesn't exist, the database won't
+  // generally exist either.
+  void Preload();
+
+  // 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();
+
+  // Returns the current transaction nesting, which will be 0 if there are
+  // no open transactions.
+  int transaction_nesting() const { return transaction_nesting_; }
+
+  // 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).
+  bool Execute(const char* sql);
+
+  // Returns true if we have a statement with the given identifier already
+  // cached. This is normally not necessary to call, but can be useful if the
+  // caller has to dynamically build up SQL to avoid doing so if it's already
+  // cached.
+  bool HasCachedStatement(const StatementID& id) const;
+
+  // Returns a statement for the given SQL using the statement cache. It can
+  // take a nontrivial amount of work to parse and compile a statement, so
+  // keeping commonly-used ones around for future use is important for
+  // performance.
+  //
+  // The SQL may have an error, so the caller must check validity of the
+  // statement before using it.
+  //
+  // The StatementID and the SQL must always correspond to one-another. The
+  // ID is the lookup into the cache, so crazy things will happen if you use
+  // different SQL with the same ID.
+  //
+  // You will normally use the SQL_FROM_HERE macro to generate a statement
+  // ID associated with the current line of code. This gives uniqueness without
+  // you having to manage unique names. See StatementID above for more.
+  //
+  // Example:
+  //   sql::Statement stmt = connection_.GetCachedStatement(
+  //       SQL_FROM_HERE, "SELECT * FROM foo");
+  //   if (!stmt)
+  //     return false;  // Error creating statement.
+  scoped_refptr<StatementRef> GetCachedStatement(const StatementID& id,
+                                                 const char* sql);
+
+  // Returns a non-cached statement for the given SQL. Use this for SQL that
+  // is only executed once or only rarely (there is overhead associated with
+  // keeping a statement cached).
+  //
+  // See GetCachedStatement above for examples and error information.
+  scoped_refptr<StatementRef> GetUniqueStatement(const char* sql);
+
+  // Info querying -------------------------------------------------------------
+
+  // Returns true if the given table exists.
+  bool DoesTableExist( const char* table_name);
+
+  // Returns true if a column with the given name exists in the given table.
+  bool DoesColumnExist(const char* table_name, const char* column_name);
+
+  // Returns sqlite's internal ID for the last inserted row. Valid only
+  // immediately after an insert.
+  int64 GetLastInsertRowId() const;
+
+  // Errors --------------------------------------------------------------------
+
+  // Returns the error code associated with the last sqlite operation.
+  int GetErrorCode() const;
+
+  // Returns a pointer to a statically allocated string associated with the
+  // last sqlite operation.
+  const char* GetErrorMessage() const;
+
+ private:
+  // Statement access StatementRef which we don't want to expose to erverybody
+  // (they should go through Statement).
+  friend class Statement;
+
+  // A StatementRef is a refcounted wrapper around a sqlite statement pointer.
+  // Refcounting allows us to give these statements out to sql::Statement
+  // objects while also optionally maintaining a cache of compiled statements
+  // by just keeping a refptr to these objects.
+  //
+  // A statement ref can be valid, in which case it can be used, or invalid to
+  // indicate that the statement hasn't been created yet, has an error, or has
+  // been destroyed.
+  //
+  // The Connection may revoke a StatementRef in some error cases, so callers
+  // should always check validity before using.
+  class StatementRef : public base::RefCounted<StatementRef> {
+   public:
+    // Default constructor initializes to an invalid statement.
+    StatementRef();
+    StatementRef(Connection* connection, sqlite3_stmt* stmt);
+    ~StatementRef();
+
+    // When true, the statement can be used.
+    bool is_valid() const { return !!stmt_; }
+
+    // If we've not been linked to a connection, this will be NULL. Guaranteed
+    // non-NULL when is_valid().
+    Connection* connection() const { return connection_; }
+
+    // Returns the sqlite statement if any. If the statement is not active,
+    // this will return NULL.
+    sqlite3_stmt* stmt() const { return stmt_; }
+
+    // Destroys the compiled statement and marks it NULL. The statement will
+    // no longer be active.
+    void Close();
+
+   private:
+    Connection* connection_;
+    sqlite3_stmt* stmt_;
+
+    DISALLOW_COPY_AND_ASSIGN(StatementRef);
+  };
+  friend class StatementRef;
+
+  // Executes a rollback statement, ignoring all transaction state. Used
+  // internally in the transaction management code.
+  void DoRollback();
+
+  // Called by a StatementRef when it's being created or destroyed. See
+  // open_statements_ below.
+  void StatementRefCreated(StatementRef* ref);
+  void StatementRefDeleted(StatementRef* ref);
+
+  // Frees all cached statements from statement_cache_.
+  void ClearCache();
+
+  // The actual sqlite database. Will be NULL before Init has been called or if
+  // Init resulted in an error.
+  sqlite3* db_;
+
+  // Parameters we'll configure in sqlite before doing anything else. Zero means
+  // use the default value.
+  int page_size_;
+  int cache_size_;
+  bool exclusive_locking_;
+
+  // All cached statements. Keeping a reference to these statements means that
+  // they'll remain active.
+  typedef std::map<StatementID, scoped_refptr<StatementRef> >
+      CachedStatementMap;
+  CachedStatementMap statement_cache_;
+
+  // A list of all StatementRefs we've given out. Each ref must register with
+  // us when it's created or destroyed. This allows us to potentially close
+  // any open statements when we encounter an error.
+  typedef std::set<StatementRef*> StatementRefSet;
+  StatementRefSet open_statements_;
+
+  // Number of currently-nested transactions.
+  int transaction_nesting_;
+
+  // True if any of the currently nested transactions have been rolled back.
+  // When we get to the outermost transaction, this will determine if we do
+  // a rollback instead of a commit.
+  bool needs_rollback_;
+
+  DISALLOW_COPY_AND_ASSIGN(Connection);
+};
+
+}  // namespace sql
+
+#endif  // APP_SQL_CONNECTION_H_