amalgalite 0.1.0

data/lib/amalgalite/boolean.rb

@@ -0,0 +1,42 @@
+#--
+# Copyright (c) 2008 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+module Amalgalite
+  ##
+  # Do type conversion on values that could be boolen values into 
+  # real 'true' or 'false'
+  #
+  # This is pulled from the possible boolean values from PostgreSQL
+  #
+  class Boolean
+    class << self
+      #
+      # list of downcased strings are potential true values
+      # 
+      def true_values
+        @true_values ||= %w[ true t yes y 1 ]
+      end
+
+      #
+      # list of downcased strings are potential false values
+      #
+      def false_values
+        @false_values ||= %w[ false f no n 0 ]
+      end
+
+      # 
+      # Convert +val+ to a string and attempt to convert it to +true+ or +false+
+      #
+      def to_bool( val )
+        return false if val.nil?
+        unless @to_bool
+          @to_bool = {}
+          true_values.each  { |t| @to_bool[t] = true  }
+          false_values.each { |f| @to_bool[f] = false }
+        end
+        return @to_bool[val.to_s.downcase]
+      end
+    end
+  end
+end

data/lib/amalgalite/column.rb

@@ -0,0 +1,83 @@
+#--
+# Copyright (c) 2008 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+
+require 'amalgalite/boolean'
+require 'amalgalite/blob'
+
+module Amalgalite
+  ##
+  # a class representing the meta information about an SQLite column, this class
+  # serves both for general Schema level information, and for result set
+  # information from a SELECT query.
+  #
+  class Column
+    # the database this column belongs to
+    attr_accessor :db
+
+    # the column name
+    attr_accessor :name
+
+    # the table to which this column belongs
+    attr_accessor :table
+
+    # the default value of the column.   This may not have a value and that
+    # either means that there is no default value, or one could not be
+    # determined.
+    #
+    attr_accessor :default_value
+
+    # the declared data type of the column in the original sql that created the
+    # column
+    attr_accessor :declared_data_type
+    
+    # the collation sequence name of the column
+    attr_accessor :collation_sequence_name
+
+    # true if the column has a NOT NULL constraint, false otherwise
+    attr_accessor :not_null_constraint
+
+    # true if the column is part of a primary key, false otherwise
+    attr_accessor :primary_key
+
+    # true if the column is AUTO INCREMENT, false otherwise
+    attr_accessor :auto_increment
+
+    ## 
+    # Create a column with its name and associated table
+    #
+    def initialize( db, name, table )
+      @db                 = db
+      @name               = name
+      @table              = table
+      @declared_data_type = nil
+      @default_value      = nil
+    end
+
+    # true if the column has a default value
+    def has_default_value?
+      not default_value.nil?
+    end
+
+    # true if the column may have a NULL value
+    def nullable?
+      not_null_constraint == false
+    end
+
+    # true if the column as a NOT NULL constraint
+    def not_null_constraint?
+      not_null_constraint
+    end
+
+    # true if the column is a primary key column
+    def primary_key?
+      primary_key
+    end
+
+    # true if the column is auto increment
+    def auto_increment?
+      auto_increment
+    end
+  end
+end

data/lib/amalgalite/database.rb

@@ -0,0 +1,505 @@
+#--
+# Copyright (c) 2008 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+require 'amalgalite3'
+require 'amalgalite/statement'
+require 'amalgalite/trace_tap'
+require 'amalgalite/profile_tap'
+require 'amalgalite/type_maps/default_map'
+
+module Amalgalite
+  #
+  # The encapsulation of a connection to an SQLite3 database.  
+  #
+  # Example opening and possibly creating a new daabase
+  #
+  #   db = Amalgalite::Database.new( "mydb.db" )
+  #   db.execute( "SELECT * FROM table" ) do |row|
+  #     puts row
+  #   end
+  #
+  #   db.close
+  #
+  # Open a database read only:
+  #
+  #   db = Amalgalite::Database.new( "mydb.db", "r" )
+  #
+  #
+  class Database
+
+    # Error thrown if a database is opened with an invalid mode
+    class InvalidModeError < ::Amalgalite::Error; end
+
+    ##
+    # container class for holding transaction behavior constants.  These are the
+    # SQLite values passed to a START TRANSACTION SQL statement.
+    #
+    class TransactionBehavior
+      # no read or write locks are created until the first statement is executed
+      # that requries a read or a write
+      DEFERRED  = "DEFERRED"
+
+      # a readlock is obtained immediately so that no other process can write to
+      # the database
+      IMMEDIATE = "IMMEDIATE"
+      
+      # a read+write lock is obtained, no other proces can read or write to the
+      # database
+      EXCLUSIVE = "EXCLUSIVE"
+
+      # list of valid transaction behavior constants
+      VALID     = [ DEFERRED, IMMEDIATE, EXCLUSIVE ]
+
+      # 
+      # is the given mode a valid transaction mode
+      #
+      def self.valid?( mode )
+        VALID.include? mode
+      end
+    end
+    
+   include Amalgalite::SQLite3::Constants
+
+   # list of valid modes for opening an Amalgalite::Database
+   VALID_MODES = {
+      "r"  => Open::READONLY,
+      "r+" => Open::READWRITE,
+      "w+" => Open::READWRITE | Open::CREATE,
+    }
+
+    # the low level Amalgalite::SQLite3::Database
+    attr_reader :api
+
+    # An object that follows the TraceTap protocol, or nil.  By default this is nil
+    attr_reader :trace_tap
+
+    # An object that follows the ProfileTap protocol, or nil.  By default this is nil
+    attr_reader :profile_tap
+
+    # An object that follows the TypeMap protocol, or nil.  
+    # By default this is an instances of TypeMaps::DefaultMap
+    attr_reader :type_map
+
+    ##
+    # Create a new Amalgalite database
+    #
+    # :call-seq:
+    #   Amalgalite::Database.new( filename, "w+", opts = {}) -> Database
+    #
+    # The first parameter is the filename of the sqlite database.  
+    # The second parameter is the standard file modes of how to open a file.
+    #
+    # The modes are:
+    #
+    # * r  - Read-only
+    # * r+ - Read/write, an error is thrown if the database does not already exist
+    # * w+ - Read/write, create a new database if it doesn't exist
+    #
+    # <tt>w+</tt> is the default as this is how most databases will want to be utilized.
+    #
+    # opts is a hash of available options for the database:
+    #
+    # * :utf16  option to set the database to a utf16 encoding if creating a database. 
+    #
+    # By default, databases are created with an encoding of utf8.  Setting this to 
+    # true and opening an already existing database has no effect.
+    #
+    # *NOTE* Currently :utf16 is not supported by Amalgalite, it is planned 
+    # for a later release
+    #
+    #
+    def initialize( filename, mode = "w+", opts = {})
+      @open           = false
+      @profile_tap    = nil
+      @trace_tap      = nil
+      @type_map       = ::Amalgalite::TypeMaps::DefaultMap.new
+
+      unless VALID_MODES.keys.include?( mode ) 
+        raise InvalidModeError, "#{mode} is invalid, must be one of #{VALID_MODES.keys.join(', ')}" 
+      end
+
+      if not File.exist?( filename ) and opts[:utf16] then
+        raise NotImplementedError, "Currently Amalgalite has not implemented utf16 support"
+      else
+        @api = Amalgalite::SQLite3::Database.open( filename, VALID_MODES[mode] )
+      end
+      @open = true
+    end
+
+    ##
+    # Is the database open or not
+    #
+    def open?
+      @open
+    end
+
+    ##
+    # Close the database
+    #
+    def close
+      if open? then
+        @api.close
+      end
+    end
+
+    ##
+    # Is the database in autocommit mode or not
+    #
+    def autocommit?
+      @api.autocommit?
+    end
+
+    ##
+    # Return the rowid of the last inserted row
+    #
+    def last_insert_rowid
+      @api.last_insert_rowid
+    end
+
+    ##
+    # Is the database utf16 or not?  A database is utf16 if the encoding is not
+    # UTF-8.  Database can only be UTF-8 or UTF-16, and the default is UTF-8
+    #
+    def utf16?
+      unless @utf16.nil?
+        @utf16 = (encoding != "UTF-8") 
+      end
+      return @utf16
+    end
+
+    ## 
+    # return the encoding of the database
+    #
+    def encoding
+      unless @encoding
+        @encoding = pragma( "encoding" ).first['encoding']
+      end
+      return @encoding
+    end
+
+    ## 
+    # return whether or not the database is currently in a transaction or not
+    # 
+    def in_transaction?
+      not @api.autocommit?
+    end
+
+    ##
+    # return how many rows changed in the last insert, update or delete statement.
+    #
+    def row_changes
+      @api.row_changes
+    end
+
+    ##
+    # return how many rows have changed since this connection to the database was
+    # opened.
+    #
+    def total_changes
+      @api.total_changes
+    end
+
+    ##
+    # Prepare a statement for execution
+    #
+    # If called with a block, the statement is yielded to the block and the
+    # statement is closed when the block is done.
+    #
+    #  db.prepare( "SELECT * FROM table WHERE c = ?" ) do |stmt|
+    #    list_of_c_values.each do |c|
+    #      stmt.execute( c ) do |row|
+    #        puts "when c = #{c} : #{row.inspect}"
+    #      end
+    #    end
+    #  end
+    #
+    # Or without a block:
+    #
+    #   stmt = db.prepare( "INSERT INTO t1(x, y, z) VALUES ( :
+    #
+    def prepare( sql )
+      stmt = Amalgalite::Statement.new( self, sql )
+      if block_given? then
+        begin 
+          yield stmt
+        ensure
+          stmt.close
+          stmt = nil
+        end
+      end
+      return stmt
+    end
+
+    ##
+    # Execute a single SQL statement. 
+    #
+    # If called with a block and there are result rows, then they are iteratively
+    # yielded to the block.
+    #
+    # If no block passed and there are results, then a ResultSet is returned.
+    # Otherwise nil is returned.  On an error an exception is thrown.
+    #
+    # This is just a wrapper around the preparation of an Amalgalite Statement and
+    # iterating over the results.
+    #
+    def execute( sql, *bind_params )
+      stmt = prepare( sql )
+      stmt.bind( *bind_params )
+      if block_given? then
+        stmt.each { |row| yield row }
+      else
+        return stmt.all_rows
+      end
+    ensure
+      stmt.close if stmt
+    end
+
+    ##
+    # Execute a batch of statements, this will execute all the sql in the given
+    # string until no more sql can be found in the string.  It will bind the 
+    # same parameters to each statement.  All data that would be returned from 
+    # all of the statements is thrown away.
+    #
+    # All statements to be executed in the batch must be terminated with a ';'
+    # Returns the number of statements executed
+    #
+    #
+    def execute_batch( sql, *bind_params) 
+      count = 0
+      while sql
+        prepare( sql ) do |stmt|
+          stmt.execute( *bind_params )
+          sql =  stmt.remaining_sql 
+          sql = nil unless (sql.index(";") and Amalgalite::SQLite3.complete?( sql ))
+        end
+        count += 1
+      end
+      return count
+    end
+
+    ##
+    # clear all the current taps
+    #
+    def clear_taps!
+      self.trace_tap = nil
+      self.profile_tap = nil
+    end
+
+    ##
+    # call-seq:
+    #   db.trace_tap = obj 
+    #
+    # Register a trace tap.  
+    #
+    # Registering a trace tap measn that the +obj+ registered will have its
+    # +trace+ method called with a string parameter at various times.
+    # If the object doesn't respond to the +trace+ method then +write+
+    # will be called.
+    #
+    # For instance:
+    #
+    #   db.trace_tap = Amalgalite::TraceTap.new( logger, 'debug' )
+    # 
+    # This will register an instance of TraceTap, which wraps an logger object.
+    # On each +trace+ event the TraceTap#trace method will be called, which in
+    # turn will call the <tt>logger.debug</tt> method
+    #
+    #   db.trace_tap = $stderr 
+    #
+    # This will register the <tt>$stderr</tt> io stream as a trace tap.  Every time a
+    # +trace+ event happens then <tt>$stderr.write( msg )</tt> will be called.
+    #
+    #   db.trace_tap = nil
+    #
+    # This will unregistere the trace tap
+    #
+    #
+    def trace_tap=( tap_obj )
+
+      # unregister any previous trace tap
+      #
+      unless @trace_tap.nil?
+        @trace_tap.trace( 'unregistered as trace tap' )
+        @trace_tap = nil
+      end
+      return @trace_tap if tap_obj.nil?
+
+
+      # wrap the tap if we need to
+      #
+      if tap_obj.respond_to?( 'trace' ) then
+        @trace_tap = tap_obj
+      elsif tap_obj.respond_to?( 'write' ) then
+        @trace_tap = Amalgalite::TraceTap.new( tap_obj, 'write' )
+      else
+        raise Amalgalite::Error, "#{tap_obj.class.name} cannot be used to tap.  It has no 'write' or 'trace' method.  Look at wrapping it in a Tap instances."
+      end
+
+      # and do the low level registration
+      #
+      @api.register_trace_tap( @trace_tap )
+
+      @trace_tap.trace( 'registered as trace tap' )
+    end
+
+
+    ##
+    # call-seq:
+    #   db.profile_tap = obj 
+    #
+    # Register a profile tap.
+    #
+    # Registering a profile tap means that the +obj+ registered will have its
+    # +profile+ method called with an Integer and a String parameter every time
+    # a profile event happens.  The Integer is the number of nanoseconds it took
+    # for the String (SQL) to execute in wall-clock time.
+    #
+    # That is, every time a profile event happens in SQLite the following is
+    # invoked:
+    #
+    #   obj.profile( str, int ) 
+    #
+    # For instance:
+    #
+    #   db.profile_tap = Amalgalite::ProfileTap.new( logger, 'debug' )
+    # 
+    # This will register an instance of ProfileTap, which wraps an logger object.
+    # On each +profile+ event the ProfileTap#profile method will be called
+    # which in turn will call <tt>logger.debug<tt> with a formatted string containing
+    # the String and Integer from the profile event.
+    #
+    #   db.profile_tap = nil
+    #
+    # This will unregister the profile tap
+    #
+    #
+    def profile_tap=( tap_obj )
+
+      # unregister any previous profile tap
+      unless @profile_tap.nil?
+        @profile_tap.profile( 'unregistered as profile tap', 0.0 )
+        @profile_tap = nil
+      end
+      return @profile_tap if tap_obj.nil?
+
+      if tap_obj.respond_to?( 'profile' ) then
+        @profile_tap = tap_obj
+      else
+        raise Amalgalite::Error, "#{tap_obj.class.name} cannot be used to tap.  It has no 'profile' method"
+      end
+      @api.register_profile_tap( @profile_tap )
+      @profile_tap.profile( 'registered as profile tap', 0.0 )
+    end
+
+    ##
+    # call-seq:
+    #   db.type_map = DefaultMap.new
+    #
+    # Assign your own TypeMap instance to do type conversions.  The value
+    # assigned here must respond to +bind_type_of+ and +result_value_of+
+    # methods.  See the TypeMap class for more details.
+    #
+    #
+    def type_map=( type_map_obj )
+      %w[ bind_type_of result_value_of ].each do |method|
+        unless type_map_obj.respond_to?( method )
+          raise Amalgalite::Error, "#{type_map_obj.class.name} cannot be used to do type mapping.  It does not respond to '#{method}'"
+        end
+      end
+      @type_map = type_map_obj
+    end
+
+    ##
+    # :call-seq:
+    #   db.schema( dbname = "main" ) -> Schema
+    # 
+    # Returns a Schema object  containing the table and column structure of the
+    # database.
+    #
+    def schema( dbname = "main" ) 
+      @schema ||= ::Amalgalite::Schema.new( self, dbname )
+    end
+
+    ##
+    # :call-seq:
+    #   db.reload_schema! -> Schema
+    #
+    # By default once the schema is obtained, it is cached.  This is here to
+    # force the schema to be reloaded.
+    #
+    def reload_schema!( dbname = "main" )
+      @schema = nil
+      schema( dbname )
+    end
+
+    ##
+    # Run a pragma command against the database
+    # 
+    # Returns the result set of the pragma
+    def pragma( cmd )
+      execute("PRAGMA #{cmd}")
+    end
+
+    ##
+    # Begin a transaction.  The valid transaction types are:
+    #
+    # DEFERRED:: no read or write locks are created until the first
+    #            statement is executed that requries a read or a write
+    # IMMEDIATE:: a readlock is obtained immediately so that no other process
+    #             can write to the database
+    # EXCLUSIVE:: a read+write lock is obtained, no other proces can read or
+    #             write to the database
+    #
+    # As a convenience, these are constants available in the
+    # Database::TransactionBehavior class.
+    #
+    # Amalgalite Transactions are database level transactions, just as SQLite's
+    # are.
+    #
+    # If a block is passed in, then when the block exits, it is guaranteed that
+    # either 'COMMIT' or 'ROLLBACK' has been executed.  
+    #
+    # If any exception happens during the transaction that is caught by Amalgalite, 
+    # then a 'ROLLBACK' is issued when the block closes.  
+    #
+    # If no exception happens during the transaction then a 'COMMIT' is
+    # issued upon leaving the block.
+    #
+    # If no block is passed in then you are on your own.
+    # 
+    def transaction( mode = TransactionBehavior::DEFERRED )
+      raise Amalgalite::Error, "Invalid transaction behavior mode #{mode}" unless TransactionBehavior.valid?( mode )
+      raise Amalgalite::Error, "Nested Transactions are not supported" if in_transaction?
+      execute( "BEGIN #{mode} TRANSACTION" )
+      if block_given? then
+        begin
+          yield self
+        ensure
+          if $! then
+            rollback
+            raise $!
+          else
+            commit
+          end
+        end
+      end
+      return in_transaction?
+    end
+
+    ##
+    # Commit a transaction
+    #
+    def commit
+      execute( "COMMIT" )
+    end
+
+    ##
+    # Rollback a transaction
+    #
+    def rollback
+      execute( "ROLLBACK" )
+    end
+  end
+end
+