dbmlite3 1.0.a1

data/lib/dbmlite3.rb

@@ -0,0 +1,909 @@
+
+require 'sqlite3'
+require 'yaml'
+require 'set'
+
+
+module Lite3
+
+  # Exception class for errors specific `Lite3::DBM`.  Note that
+  # `Lite3::*` methods may also throw `SQLite3` exceptions.
+  class Error < StandardError; end
+
+  #
+  # Private classes
+  #
+
+
+  # Wrapper around a SQLite3::Database object.
+  #
+  # We do this instead of using them directly because transactions
+  # happen at the handle level rather than the file level and this
+  # lets us share the transaction across multiple tables in the same
+  # file.
+  #
+  # In addition, we can use this to cache prepared SQL statements and
+  # to transparently close and reopen the underlying database file
+  # when (e.g.) forking the process.
+  #
+  # Instances contain references to DBM objects using them.  When the
+  # set becomes empty, the handle is closed; adding a reference will
+  # ensure the handle is open.
+  class Handle
+    attr_reader :path
+    def initialize(path)
+      @path = path
+      @db = nil
+      @refs = Set.new
+      @statement_cache = {}
+
+      open!
+    end
+
+    def to_s
+      "<#{self.class}:0x#{object_id.to_s(16)} path=#{@path} open=#{!!@db}>"
+    end
+    alias inspect to_s
+
+    #
+    # Back-references to the DBM object(s) using this handle.
+    #
+    # `delref` will close the handle if there are no more references.
+    #
+
+    def addref(parent)
+      @refs.add parent
+      open!
+    end
+
+    def delref(parent)
+      @refs.delete parent
+      close! if @refs.empty?
+    end
+
+    # Return the list of active parents;
+    def refs
+      return @refs.to_a
+    end
+
+
+    #
+    # Opening and closing
+    #
+
+    def closed?
+      return @db == nil
+    end
+
+    # Close the underlying SQLite3::Database handle.  Does *not*
+    # render `self` unusable; it will recreate the handle the next
+    # time it's needed.
+    def close!
+      return unless @db
+
+      @statement_cache.values.each{|ps| ps.close }
+      @statement_cache = {}
+
+      @db.close
+      @db = nil
+    end
+
+    private
+
+    # Open
+    def open!
+      return if @db   # already open
+      @db = SQLite3::Database.new @path
+    end
+
+    public
+
+    # Perform &block in a transaction.  See DBM.transaction.
+    #
+    # Always evalautes the block. If no transaction is in progress,
+    # starts one first and ends it afterward. In other words: always
+    # finishes what it starts and doesn't mess with things already in
+    # progress.
+    def transaction(&block)
+      open!
+
+      return block.call if @db.transaction_active?
+
+      begin
+        @db.transaction
+        result = block.call
+        return result
+
+      rescue => e
+        @db.rollback
+        raise e
+
+      ensure
+        @db.commit if @db.transaction_active?
+      end
+    end
+
+    # Test if there is currently a transaction in progress
+    def transaction_active?
+      return !closed? && @db.transaction_active?
+    end
+
+    # Execute query with bindvars. The corresponding Statement is cached
+    # and reused if present.
+    def sql(query, bindvars = [], &block)
+      open!
+      unless @statement_cache.has_key? query
+        stmt = @db.prepare(query)
+        @statement_cache[query] = stmt
+      end
+
+      return @statement_cache[query].execute!(bindvars, &block)
+    end
+  end
+
+
+  # Dummy `Handle` that throws an `Error` exception whenever something
+  # tries to treat it as an open handle.  This replaces a `DBM`'s
+  # `Handle` object when `DBM.close` is called so that the error
+  # message will be useful if something tries to access a closed
+  # handle.
+  class ClosedHandle
+    def initialize(filename, table)
+      @filename, @table = [filename, table]
+    end
+
+    def closed?()       return true;    end
+
+    # We clone the rest of Handle's interface with methods that throw
+    # an Error.
+    Handle.instance_methods(false).each { |name|
+      next if method_defined? name
+      define_method(name) { |*args|
+        raise Error.new("Use of closed database at #{@filename}/#{@table}")
+      }
+    }
+  end
+
+
+  # Module to manage the collection of active Handle objects.  See the
+  # docs for `Lite3::SQL` for an overview; this module hold the actual
+  # code and data.
+  module HandlePool
+    @@handles = {}      # The hash of `Handle` objects keyed by filename
+
+    # Retrieve the `Handle` associated with `filename`, creating it
+    # first if necessary.  `filename` is normalized with
+    # `File.realpath` before using as a key and so is as good or bad
+    # as that for detecting an existing file.
+    def self.get(filename)
+
+      # Scrub @@handles of all inactive Handles
+      self.gc
+
+      # We need to convert the filename to a canonical
+      # form. `File.realpath` does this for us but only if the file
+      # exists.  If not, we use it on the parent directory instead and
+      # use `File.join` to create the full path.
+      if File.exist?(filename)
+        File.file?(filename) or
+          raise Error.new("Filename '#{filename}' exists but is not a file.")
+
+        filename = File.realpath(filename)
+      else
+        dn = File.dirname(filename)
+        File.directory?(dn) or
+          raise Error.new("Parent directory '#{dn}' nonexistant or " +
+                          "not a directory.")
+
+        filename = File.join(File.realpath(dn), File.basename(filename))
+      end
+
+      @@handles[filename] = Handle.new(filename) unless
+        @@handles.has_key?(filename)
+
+      return @@handles[filename]
+    end
+
+    # Close all underlying SQLite3::Database handles.
+    def self.close_all
+      @@handles.values.each{|h| h.close!}
+    end
+
+    # Close and remove all Handle objects with no refs and return a
+    # hash mapping the filename for each live Handle to the DBM
+    # objects that currently reference it.  Does **NOT** perform a
+    # Ruby GC.
+    def self.gc
+      results = {}
+      @@handles.select!{|path, handle|
+        refs = handle.refs
+        if refs.empty?
+          handle.close!
+          next false
+        end
+
+        results[path] = refs
+        true
+      }
+
+      return results
+    end
+  end
+
+
+  # This module provides some basic access to the underlying
+  # `SQLite3::Database` objects used by `Lite3::DBM` to actually store
+  # and retrieve data.
+  #
+  # Things you need to care about are:
+  #
+  # 1. Use `threadsafe?` to see if the underlying `SQLite3` lib was
+  #    compiled to be threadsafe.
+  #
+  # 2. Invoke `Lite3::SQL.close_all` before forking the process if you
+  #    have ever opened a `Lite3::DBM` object and intend on using
+  #    `Lite3` in both the parent and the child process.
+  #
+  # More details:
+  #
+  # `Lite3` maintains a pool of private handle objects (private class
+  # `Lite3::Handle`) which in turn manage the `SQLite3::Database`
+  # objects that actually do the work.  There is one handle per
+  # SQLite3 database file; since each `DBM` represents one table in a
+  # SQLite3 file, multiple `DBM` objects will use the same handle.
+  #
+  # Handle objects can themselves close and replace their
+  # `SQLite3::Database` objects transparently.
+  #
+  # The underlying system keeps track of which `DBM` objects reference
+  # which files and will close a file's `SQLite3::Database` when all
+  # of the `DBM`s using it have been closed.  (It does **not** handle
+  # the case where a `DBM` object remains open and goes out of scope;
+  # that object will be kept around for the life of the process.)
+  #
+  # Mostly, you don't need to care about this.  However, it affects
+  # you in two ways:
+  #
+  # 1. Transactions are done at the file level and not the table level.
+  #    This means that you can access separate tables in the same
+  #    transaction, which is a Very Good Thing.
+  #
+  # 2. You can safely fork the current process and keep using existing
+  #    `DBM` objects in both processes, provided you've invoked
+  #    `close_all` before the fork.  This will have closed the actual
+  #    database handles (which can't tolerate being carried across a
+  #    fork) and opens new ones the next time they're needed.
+  #
+  # If you find yourself needing to be sure that you don't have any
+  # unexpected open file handles (e.g. before forking or if you need
+  # Windows to unlock it), you should call `close_all`.
+  #
+  # Otherwise, it's safe to ignore this stuff.
+  module SQL
+    # Test if the SQLite3 lib we are using has been compiled to be
+    # thread safe.  Just a wrapper around `SQLite3.threadsafe?`
+    def self.threadsafe?
+      return SQLite3.threadsafe?
+    end
+
+    # Clean up lingering unused database handle metadata.
+    #
+    # This is usually not a significant amount of space unless you
+    # have opened and closed a lot of different database files, but
+    # it's here if you need it.
+    #
+    # Returns a hash mapping each remaining handle's canonical file
+    # path to a list of `DBM` objects that reference it.  This is
+    # probably not useful to you; it's there for the unit tests.
+    def self.gc()           return HandlePool.gc;           end
+
+    # Close and remove the underlying `SQLite3::Database` associated
+    # with each `DBM`. A new `SQLite3::Database` will be created on
+    # the file the first time the `DBM` is used.
+    #
+    # This **should not** be called while a database operation is in
+    # progress.  (E.g. do **not** call this from the block of
+    # `DBM.each`.)
+    def self.close_all()    return HandlePool.close_all     end
+  end
+
+
+  # Lite3::DBM encapsulates a single table in a single SQLite3
+  # database file and lets you access it as easily as a Hash:
+  #
+  #     require 'dbmlite3'
+  #
+  #     db = Lite3::DBM.new("database.sqlite3", "table")
+  #     db["speed"] = 88
+  #     db["date"] = Date.new(1955, 11, 5)
+  #     db["power_threshold"] = 2.2
+  #
+  #     db.each{|k, v| puts "#{k} -> #{v}"}
+  #
+  #     double_speed = db["speed"] * 2
+  #
+  #     db.close
+  #
+  # Note that keys must be Strings.  As a special exception, Symbols
+  # are also allowed but are transparently converted to Strings
+  # first. This means that while something like this will work:
+  #
+  #     db[:foo] = 42
+  #
+  # a subseqent
+  #
+  #     db.keys.include?(:foo) or raise AbjectFailure.new
+  #
+  # will raise an exception because the key `:foo` was turned into a
+  # string.  you will need to do this instead:
+  #
+  #     db.keys.include?('foo') or raise AbjectFailure.new
+  #     
+  # Unlike DBM, values may (optionally) be any serializable Ruby type.
+  #
+  # You can select the serialization method with an optional third
+  # constructor argument.  Options are `YAML` (the default), `Marshal`
+  # or simple string conversion with `to_s`.  Each of these methods will
+  # have their own pros and cons.
+  #
+  # The table name must be a valid name identifier (i.e. matches
+  # /^[a-zA-Z_]\w*$/).
+  #
+  # Lite3::DBM also provides access to SQLite3 transactions with the
+  # `transaction` method:
+  #
+  #     db.transaction {
+  #         (1..1000).each{ |n| db["key_#{n}"] = [n, n*2, n-1] }
+  #     }
+  #
+  # Outside of a transaction statement, each Lite3::DBM method that accesses
+  # the database does so in a single transaction.
+  #
+  # Note that if you need to do a large number of database operations,
+  # there is often a significant performance advantage to grouping them
+  # together in a transaction.
+  #
+  # The underlying table will have the given name prefixed with the
+  # string `dbmlite3_`.  In addition, the table `meta_dbmlite3` holds
+  # some related metadata.  If your program also uses the SQLite3 gem to
+  # access the database directly, you should not touch these tables or
+  # expect their format to remain consistant.
+  class Lite3::DBM
+    include Enumerable
+
+    PREFIX = "dbmlite3_"
+    META = "meta_dbmlite3"
+    private_constant(:PREFIX, :META)
+
+    #
+    # Construction and setup
+    #
+
+
+    # Create a new `Lite3::DBM` object that opens database file
+    # `filename` and performs subsequent operations on `table`.  Both
+    # the database file and the table will be created if they do not
+    # yet exist.
+    #
+    # The optional third argument `serializer` is used to choose the
+    # serialization method for converting Ruby values into storable
+    # strings.  There are three options:
+    #
+    # * `:yaml` uses the `YAML` module.
+    # * `:marshal` uses the `Marshal` module.
+    # * `:string` simply uses the default `to_s` method, just like the
+    #   stock `DBM`.
+    #
+    # Each of these will have their pros and cons.  The default is
+    # `:yaml` because that is the most portable across Ruby versions.
+    # `:marshal` tends to be faster but is not stable across Ruby
+    # versions.  Note that `DBM` does not check your Marshal version.
+    #
+    # Your serializer choice is registered in a metadata table when
+    # `tablename` is created in the SQLite3 file.  Afterward, it is an
+    # error to attempt to open the table with a different serializer
+    # and will result in a Lite3::Error exception.
+    #
+    def initialize(filename, tablename, serializer = :yaml)
+      @filename = filename
+      @tablename = tablename
+      @valenc,
+      @valdec = value_encoders(serializer)
+      @handle = HandlePool.get(filename)
+
+      @handle.addref(self)
+
+      check("Malformed table name '#{tablename}'; must be a valid identifer") {
+        tablename =~ /^[a-zA-Z_]\w*$/
+      }
+
+      transaction {
+        register_serialization_scheme(serializer)
+        create_table_if_not_present()
+      }
+    rescue Error => e
+      self.close if @handle
+      raise e
+    end
+
+
+    # Identical to `initialize` except that if a block is provided, it
+    # is evaluated with a new Lite3::DBM which is then closed afterward.
+    # This is analagous to `File.open`.
+    def self.open(filename, tablename, serializer = :yaml, &block)
+      instance = self.new(filename, tablename, serializer)
+      return instance unless block
+
+      begin
+        return block.call(instance)
+      ensure
+        instance.close
+      end
+    end
+
+    private
+
+    # Return encode and decode procs for the requested serialization
+    # scheme.
+    def value_encoders(serializer)
+      case serializer
+      when :yaml
+        enc = proc{ |val| YAML.dump(val) }
+        dec = proc{ |val| YAML.load(val) }
+
+      when :marshal
+        enc = proc { |val| Marshal.dump(val) }
+        dec = proc { |val| Marshal.load(val) }
+
+      when :string
+        enc = proc { |val| val.to_s }
+        dec = proc { |val| val.to_s } # sqlite preserves some types
+
+      else
+        raise Error.new("Invalid serializer selected: '#{serializer}'")
+      end
+
+      return enc, dec
+    end
+
+    # Create @table if it does not exist yet.
+    def create_table_if_not_present
+      @handle.sql <<-SQL
+create table if not exists #{actual_tbl} (
+    key     string primary key,
+    value   string
+);
+SQL
+    end
+
+    # Add the serialization scheme for this table to META
+    def register_serialization_scheme(req_ser)
+      @handle.sql <<-SQL
+create table if not exists #{META} (
+    tbl         string primary key,
+    serializer  string
+);
+SQL
+
+      matched = false
+      @handle.sql("select * from #{META} where tbl = ?", [@tablename]) { |row|
+        tbl, ser = row
+
+        msg = "Table '#{@tablename}' uses serializer '#{ser}'; " +
+              "expecting '#{req_ser}'."
+        raise Error.new(msg) unless req_ser.to_s == ser
+
+        matched = true
+      }
+
+      matched or
+        @handle.sql("insert into #{META} (tbl, serializer) values (?,?)",
+                    [@tablename,req_ser.to_s]);
+    end
+
+
+
+    #
+    # Helpers
+    #
+
+
+    # Return the actual table name we are using.
+    def actual_tbl()    return "#{PREFIX}#{@tablename}"; end
+
+
+    public
+
+    def to_s
+      openstr = closed? ? 'CLOSED' : 'OPEN'
+      return "<#{self.class}:0x#{object_id.to_s(16)} file='#{@filename}'" +
+             " tablename='#{@tablename}' #{openstr}>"
+    end
+    alias inspect to_s
+
+    # Close `self`.  Subsequent attempts at database operations will
+    # fail with an exception but `closed?` will still work.
+    #
+    # Note that the underlying file handle (via the
+    # `SQLite3::Database` object) will **only** be closed if there are
+    # no other `DBM` objects using that file.
+    def close
+      @handle.delref(self)
+      @handle = ClosedHandle.new(@filename, @tablename)
+    end
+
+    # Test if this object has been closed.  This is safe to call on a
+    # closed `DBM`.
+    def closed?()
+      return @handle.is_a? ClosedHandle
+    end
+
+    # Test if the underlying `SQLite3::Database` is closed.  You
+    # probably don't need to care about this method; it's mostly here
+    # to help with unit tests.
+    #
+    # This will **not** work if `self` has been closed.
+    def handle_closed?
+      return @handle.closed?
+    end
+
+
+    #
+    # Transactions
+    #
+
+
+    # Begins a transaction, evaluates the given block and then ends the
+    # transaction.  If no error occurred, the transaction is committed;
+    # otherwise, it is rolled back.
+    #
+    # It is safe to call `DBM.transaction` within another
+    # `DBM.transaction` block's call chain because `DBM` will not
+    # start a new transaction on a database handle that already has
+    # one in progress.  (It may be possible to trick `DBM` into trying
+    # via fibers or other flow control trickery; don't do that.)
+    #
+    # It is also not safe to mix `DBM` transactions and bare `SQLite3`
+    # transactions.
+    #
+    # Transactions are always executed in `:deferred` mode.
+    #
+    # @yield [db] The block takes a reference to the receiver as an
+    #             argument.
+    #
+    def transaction(&block)
+      return @handle.transaction { block.call(self) }
+    end
+
+    # Test if there is currently a transaction in progress
+    def transaction_active?
+      return @handle.transaction_active?
+    end
+
+
+    #
+    # Basic hash-like access
+    #
+
+
+    # Store `value` at `key` in the database.
+    #
+    # `key` **must** be a String or a Symbol.
+    #
+    # `value` **must** be convertable to string by whichever
+    # serialization method you have chosen.
+    def []=(key, value)
+      key = check_key(key)
+      valstr = SQLite3::Blob.new( @valenc.call(value) )
+
+      insert = <<~SQL
+        insert into #{actual_tbl} (key, value) values (?,?)
+            on conflict(key) do update set value = ?;
+        SQL
+      transaction {
+        @handle.sql(insert, [key, valstr, valstr])
+      }
+
+      return value
+    end
+    alias store :'[]='
+
+    # Retrieve the value associated with `key` from the database or
+    # nil if it is not present.
+    def [](key)
+      return fetch(key, nil)
+    end
+
+    # Retrieve the value associated with `key`.
+    #
+    # If it is not present and a block is given, evaluate the block
+    # with the key as its argument and return that.
+    #
+    # If no block was given either but one extra parameter was given,
+    # that value is returned instead.
+    #
+    # Finally, if none of these was given, it throws an `IndexError`
+    # exception.
+    #
+    # It is an error if `fetch` is called with more than two arguments.
+    #
+    # @yield [key]            The fallback block.
+    def fetch(key, *args, &default_block)
+
+      # Ensure there are no extra arguments
+      nargs = args.size + 1
+      check("Too many arguments for 'fetch'; expected 1 or 2; got #{nargs}") {
+        nargs <= 2
+      }
+
+      # Retrieve the value
+      key = check_key(key)
+      rows = @handle.sql("select * from #{actual_tbl} where key=?" +
+                         " order by rowid;", [key])
+      check("Multiple matches for key '#{key}'!") { rows.size <= 1 }
+
+      # Return the value if found
+      return @valdec.call(rows[0][1]) unless rows.empty?
+
+      # Otherwise, evaluate the block and use its result if a block was
+      # given
+      return default_block.call(key) if default_block
+
+      # Next, see if we have a default value we can return
+      return args[0] if args.size > 0
+
+      # And if all else fails, raise an IndexError.
+      raise IndexError.new("key '#{key}' not found.")
+    end
+
+    # Return a new `Array` containing the values corresponding to the
+    # given keys.
+    def values_at(*keys)
+      return keys.map{|k| self[k]}
+    end
+
+    # Return an `Array` of all of the keys in the table.
+    #
+    # **WARNING:** since this list is being read from disk, it is possible
+    # that the result could exceed available memory.
+    def keys
+      keys = []
+      each_key{|k| keys.push k}
+      return keys
+    end
+
+    # Return an array of all values in the table.
+    #
+    # **WARNING:** since this list is being read from disk, it is possible
+    # that the result could exceed available memory.
+    def values
+      values = []
+      each_value {|val| values.push val }
+      return values
+    end
+
+    # Return `true` if the table contains `key`; otherwise, return
+    # `false`.
+    def has_key?(key)
+      return false unless key.class == String || key.class == Symbol
+      fetch( key ) { return false }
+      return true
+    end
+    alias include? has_key?
+    alias member? has_key?
+    alias key? has_key?
+
+    # Delete all entries from the table.
+    def clear
+      transaction { @handle.sql("delete from #{actual_tbl};", []) }
+    end
+
+    # Calls the given block with each key-value pair in the usual
+    # order, then return self.  The entire call takes place in its own
+    # transaction.
+    #
+    # If no block is given, returns an Enumerator instead.  The
+    # Enumerator does *not* start a transaction but individual
+    # accesses of it (e.g. calling `next`) each take place in their
+    # own transaction.
+    #
+    # @yield [key, value]            The block to evaluate
+    def each(&block)
+      return self.to_enum(:nt_each) unless block
+      transaction { nt_each(&block) }
+      return self
+    end
+    alias each_pair each
+
+    private
+
+    # Back-end for `each`; does not explicitly start a transaction.
+    def nt_each(&block)
+      #return self.to_enum unless block
+
+      front = "select rowid, key, value from #{actual_tbl} "
+      back = " order by rowid limit 1;"
+
+      # We do enumeration by looking up each item in a separate query
+      # rather than attaching a block to the SQL query.  This is so that
+      # it is safe to access `self` from inside the block.
+      get_row = proc do |first, last_id|
+        query = front
+        query += "where rowid > ?" unless first
+        query += back
+
+        vars = []
+        vars.push last_id unless first
+
+        row = @handle.sql(query, vars)
+        return self if row.empty?
+
+        rowid, key, value = row[0]
+        block.call(key, @valdec.call(value))
+
+        next rowid
+      end
+
+      rowid = get_row.call(true, nil)
+      while true
+        rowid = get_row.call(false, rowid)
+      end
+
+      return self     # not reached
+    end
+
+    public
+
+    # Calls the given block with each key; returns self.  Exactly like
+    # `each` except for the block argument.
+    #
+    # @yield [key]            The block to evaluate
+    def each_key(&block)
+      return Enumerator.new{|y| nt_each{ |k,v| y << k  } } unless block
+      return each{ |k,v| block.call(k) }
+    end
+
+    # Calls the given block with each value; returns self. Exactly like
+    # `each` except for the block argument.
+    #
+    # @yield [value]            The block to evaluate
+    def each_value(&block)
+      return Enumerator.new{|y| nt_each{ |k,v| y << v  } } unless block
+      return each{ |k,v| block.call(v) }
+    end
+
+    # Updates the database with multiple values from the specified
+    # object. Takes any object which implements the each_pair method,
+    # including `Hash` and `DBM` objects.
+    def update(hash)
+      transaction {
+        hash.each{|k, v| self[k] = v }
+      }
+    end
+
+    # Remove `key` and its associated value from `self`.  If `key` is
+    # not present, does nothing.
+    def delete(key)
+      transaction {
+        @handle.sql("delete from #{actual_tbl} where key = ?", [key])
+      }
+    end
+
+    # Evaluate the block on each key-value pair in `self` end delete
+    # each entry for which the block returns true.
+    #
+    # @yield [value]            The block to evaluate
+    def delete_if(&block)
+      transaction {
+        self.each{ |k, v| block.call(k,v) and delete(k) }
+      }
+    end
+    alias reject! delete_if
+
+    # Return the number of entries (key-value pairs) in `self`.
+    def size
+      @handle.sql("select count(*) from #{actual_tbl};", []) { |row|
+        return row[0]
+      }
+      check("count query failed!")
+    end
+    alias length size
+
+    # Test if `self` is empty.
+    def empty?
+      return size == 0
+    end
+
+
+    #
+    # Conversion to internal types
+    #
+
+
+    # Copies the table into a `Hash` and returns it.
+    #
+    # **WARNING:** it is possible for tables to be significantly larger
+    # than available RAM; in that case, this will likely crash your
+    # program.
+    def to_hash
+      result = {}
+      each{|k,v| result[k] = v}
+      return result
+    end
+
+
+    # Returns an `Array` of 2-element `Array` objects each containing a
+    # key-value pair from `self`.
+    #
+    # **WARNING:** it is possible for tables to be significantly larger
+    # than available RAM; in that case, this will likely crash your
+    # program.
+    def to_a
+      result = []
+      each { |k,v| result.push [k,v] }
+      return result
+    end
+
+
+    #
+    # Hacky odds and ends
+    #
+
+
+    # Test if `val` is one of the values in this table.
+    #
+    # Potentially very slow, especially on large tables.
+    def has_value?(val)
+      self.each{|k,v| return true if v == val}
+      return false
+    end
+    alias value? has_value?
+
+    # Return a `Hash` whose keys are the table's values and whose values
+    # are the table's keys.
+    #
+    # **WARNING:** it is possible for tables to be significantly larger
+    # than available RAM; in that case, this will likely crash your
+    # program.
+    def invert
+      result = {}
+      each{|k,v| result[v] = k}
+      return result
+    end
+
+    # Remove the first key/value pair from `self` and return it.  "First"
+    # is defined by `self`'s row order, which is the order of insertion
+    # as determined by SQLite3.
+    def shift
+      transaction {
+        return nil if empty?
+
+        key, value = self.each.first
+        delete(key)
+
+        return [key, value]
+      }
+    end
+
+    private
+
+    # Attempt to turn 'key' to a valid key and raise an exception if
+    # that isn't possible.
+    def check_key(key)
+      key = key.to_s if key.class == Symbol
+      raise TypeError.new("Key '#{key}' is not a string or symbol!") unless
+        key.class == String
+
+      return key
+    end
+
+    # Error check: if block evaluates to false, raise a Lite3::DBM::Error
+    # with the given message.
+    def check(message, &block)
+      return if block && block.call
+      raise Error.new(message)
+    end
+  end
+
+  private_constant :Handle, :ClosedHandle, :HandlePool
+end