amalgalite 0.1.0

data/lib/amalgalite/index.rb

@@ -0,0 +1,27 @@
+#--
+# Copyright (c) 2008 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+
+module Amalgalite
+  #
+  # a class representing the meta information about an SQLite index
+  #
+  class Index
+    # the name of the index
+    attr_reader   :name
+
+    # the sql statement that created the index
+    attr_reader   :sql
+
+    # the table the index is for
+    attr_accessor :table
+
+    def initialize( name, sql, table ) 
+      @name  = name
+      @sql   = sql
+      @table = table
+    end
+  end
+end
+

data/lib/amalgalite/paths.rb

@@ -0,0 +1,70 @@
+#--
+# Copyright (c) 2008 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+module Amalgalite
+  #
+  # Paths contains helpful methods to determine paths of files inside the
+  # Amalgalite library
+  #
+  module Paths
+    #
+    # The root directory of the project is considered to be the parent directory
+    # of the 'lib' directory.
+    #   
+    # returns:: [String] The full expanded path of the parent directory of 'lib'
+    #           going up the path from the current file.  Trailing
+    #           File::SEPARATOR is guaranteed.
+    #   
+    def self.root_dir
+      unless @root_dir
+        path_parts = ::File.expand_path(__FILE__).split(::File::SEPARATOR)
+        lib_index  = path_parts.rindex("lib")
+        @root_dir = path_parts[0...lib_index].join(::File::SEPARATOR) + ::File::SEPARATOR
+      end 
+      return @root_dir
+    end 
+
+    # returns:: [String] The full expanded path of the +config+ directory
+    #           below _root_dir_.  All parameters passed in are joined onto the
+    #           result.  Trailing File::SEPARATOR is guaranteed if _args_ are
+    #           *not* present.
+    #   
+    def self.config_path(*args)
+      self.sub_path("config", *args)
+    end 
+
+    # returns:: [String] The full expanded path of the +data+ directory below
+    #           _root_dir_.  All parameters passed in are joined onto the 
+    #           result. Trailing File::SEPARATOR is guaranteed if 
+    #           _*args_ are *not* present.
+    #   
+    def self.data_path(*args)
+      self.sub_path("data", *args)
+    end 
+
+    # returns:: [String] The full expanded path of the +lib+ directory below
+    #           _root_dir_.  All parameters passed in are joined onto the 
+    #           result. Trailing File::SEPARATOR is guaranteed if 
+    #           _*args_ are *not* present.
+    #   
+    def self.lib_path(*args)
+      self.sub_path("lib", *args)
+    end 
+
+    # returns:: [String] The full expanded path of the +ext+ directory below
+    #           _root_dir_.  All parameters passed in are joined onto the 
+    #           result. Trailing File::SEPARATOR is guaranteed if 
+    #           _*args_ are *not* present.
+    #
+    def self.ext_path(*args)
+      self.sub_path("ext", *args)
+    end
+
+    def self.sub_path(sub,*args)
+      sp = ::File.join(root_dir, sub) + File::SEPARATOR
+      sp = ::File.join(sp, *args) if args
+    end
+  end
+end
+

data/lib/amalgalite/profile_tap.rb

@@ -0,0 +1,130 @@
+#--
+# Copyright (c) 2008 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+
+module Amalgalite
+  # 
+  # A ProfileSampler is a sampler of profile times.  It aggregates up profile
+  # events that happen for the same source.  It is based upon the RFuzz::Sampler 
+  # class from the rfuzz gem
+  #
+  class ProfileSampler
+    #
+    # create a new sampler with the given name
+    #
+    def initialize( name )
+      @name = name
+      reset!
+    end
+
+    ##
+    # reset the internal state so it may be used again
+    #
+    def reset!
+      @sum   = 0.0
+      @sumsq = 0.0
+      @n     = 0
+      @min   = 0.0
+      @max   = 0.0
+    end
+
+    ##
+    # add a sample to the calculations
+    #
+    def sample( value )
+      @sum   += value
+      @sumsq += (value * value)
+      if @n == 0 then
+        @min = @max = value
+      else
+        @min = value if value < @min
+        @max = value if value > @max
+      end
+      @n += 1
+    end
+
+    ##
+    # return the mean of the data 
+    #
+    def mean
+      @sum / @n
+    end
+
+    ##
+    # returns the standard deviation of the data
+    #
+    def stddev
+      begin
+        Math.sqrt( (@sumsq - ( @sum * @sum / @n)) / (@n-1) )
+      rescue Errno::EDOM
+        return 0.0
+      end
+    end
+
+    ##
+    # return all the values as an array
+    #
+    def to_a
+      [ @name, @sum, @sumsq, @n, mean, stddev, @min, @max ]
+    end
+
+    ##
+    # return all the values as a hash
+    #
+    def to_h
+      { 'name'    => @name,  'n' => @n,
+        'sum'     => @sum,   'sumsq'   => @sumsq, 'mean'    => mean,
+        'stddev'  => stddev, 'min'     => @min,   'max'     => @max }
+    end
+
+    ##
+    # return a string containing the sampler summary
+    #
+    def to_s
+      "[%s] => sum: %d, sumsq: %d, n: %d, mean: %0.6f, stddev: %0.6f, min: %d, max: %d" % to_a
+    end
+
+  end
+
+  #
+  # A Profile Tap recives +profile+ events from SQLite  which involve the number of
+  # nanoseconds in wall-clock time it took for a particular thing to happen. In
+  # general this +thing+ is an SQL statement.
+  #
+  # It has a well known +profile+ method which when invoked will write the event
+  # to a delegate object.
+  #
+  #
+  class ProfileTap
+
+    attr_reader :samplers
+
+    #
+    # Create a new ProfileTap object that wraps the given object and calls the
+    # method named in +send_to+ ever time a profile event happens.
+    #
+    def initialize( wrapped_obj, send_to = 'profile' )
+      unless wrapped_obj.respond_to?( send_to ) 
+        raise Amalgalite::Error, "#{wrapped_obj.class.name} does not respond to #{send_to.to_s} "
+      end
+
+      @delegate_obj    = wrapped_obj
+      @delegate_method = send_to
+      @samplers        = {}
+    end
+
+    #
+    # Record the profile information and send the delegate object the msg and
+    # time information.
+    #
+    def profile( msg, time )
+      unless sampler = @samplers[msg] 
+        msg = msg.gsub(/\s+/,' ')
+        sampler = @samplers[msg] = ProfileSampler.new( msg )
+      end
+      sampler.sample( time )
+      @delegate_obj.send( @delegate_method, msg, time )
+    end
+  end
+end

data/lib/amalgalite/schema.rb

@@ -0,0 +1,90 @@
+#--
+# Copyright (c) 2008 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+
+require 'amalgalite/table'
+require 'amalgalite/index'
+require 'amalgalite/column'
+require 'amalgalite/view'
+
+module Amalgalite
+  #
+  # An object view of the schema  in the SQLite database.  If the schema changes
+  # after this class is created, it has no knowledge of that.
+  #
+  class Schema
+
+    attr_reader :catalog
+    attr_reader :schema 
+    attr_reader :tables
+    attr_reader :views
+
+    #
+    # Create a new instance of Schema
+    #
+    def initialize( db, catalog = 'main', schema = 'sqlite')
+      @db = db
+      @catalog = catalog
+      @schema = schema
+
+      load_schema!
+    end
+
+    #
+    # load the schema from the database
+    def load_schema!
+      load_tables
+      load_views
+    end
+
+    ##
+    # load all the tables
+    #
+    def load_tables
+      @tables = {}
+      @db.execute("SELECT tbl_name, sql FROM sqlite_master WHERE type = 'table'") do |table_info|
+        table = Amalgalite::Table.new( table_info['tbl_name'], table_info['sql'] )
+        table.columns = load_columns( table )
+
+        @db.prepare("SELECT name, sql FROM sqlite_master WHERE type ='index' and tbl_name = @name") do |idx_stmt|
+          idx_stmt.execute( "@name" => table.name) do |idx_info|
+            table.indexes << Amalgalite::Index.new( idx_info['name'], idx_info['sql'], table )
+          end
+        end
+        @tables[table.name] = table
+      end
+
+      @tables
+    end
+
+    ##
+    # load all the columns for a particular table
+    #
+    def load_columns( table )
+      cols = {}
+      @db.execute("PRAGMA table_info(#{table.name})") do |row|
+        col = Amalgalite::Column.new( "main", row['name'], table )
+
+        col.default_value = row['dflt_value']
+        @db.api.table_column_metadata( "main", table.name, col.name ).each_pair do |key, value|
+          col.send("#{key}=", value)
+        end
+        cols[col.name] = col
+      end
+      cols
+    end
+
+    ##
+    # load all the views for the database
+    #
+    def load_views
+      @views = {}
+      @db.execute("SELECT name, sql FROM sqlite_master WHERE type = 'view'") do |view_info|
+        view = Amalgalite::View.new( view_info['name'], view_info['sql'] )
+        @views[view.name] = view
+      end
+      @views
+    end
+  end
+end

data/lib/amalgalite/sqlite3.rb

@@ -0,0 +1,4 @@
+require 'amalgalite3'
+require 'amalgalite/version'
+require 'amalgalite/sqlite3/version'
+require 'amalgalite/sqlite3/constants'

data/lib/amalgalite/sqlite3/constants.rb

@@ -0,0 +1,48 @@
+#--
+# Copyright (c) 2008 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+
+require 'amalgalite3'
+module Amalgalite::SQLite3
+  ##
+  # module containing all constants used from the SQLite C extension
+  #
+  module Constants
+    ##
+    # DataType defines the namespace for all possible SQLite data types.
+    # 
+    module DataType
+    end
+    DataType.freeze
+
+    ##
+    # Open defines the namespace for all possible flags to the Database.open
+    # method
+    #
+    module Open
+    end
+    Open.freeze
+
+    ##
+    # ResultCode defines the namespace for all possible result codes from an
+    # SQLite API call.
+    #
+    module ResultCode
+      #
+      # convert an integer value into the string representation of the associated
+      # ResultCode constant.
+      #
+      def self.from_int( value )
+        unless @const_map_from_int
+          @const_map_from_int = {}
+          constants.each do |const_name|
+            c_int = const_get( const_name )
+            @const_map_from_int[c_int] = const_name
+          end
+        end
+        return @const_map_from_int[ value ]
+      end
+    end # end ResultCode
+  end
+end

data/lib/amalgalite/sqlite3/version.rb

@@ -0,0 +1,38 @@
+#--
+# Copyright (c) 2008 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+require 'amalgalite3'
+module Amalgalite 
+  module SQLite3
+    module Version
+      # Sqlite3 version number is equal to 
+      # MAJOR * 1_000_000 + MINOR * 1_000 + RELEASE
+
+      # major version number of the SQLite C library
+      MAJOR   = (to_i / 1_000_000).freeze
+      
+      # minor version number of the SQLite C library
+      MINOR   = ((to_i % 1_000_000) / 1_000).freeze
+      
+      # release version number of the SQLite C library
+      RELEASE = (to_i % 1_000).freeze
+   
+      #
+      # call-seq:
+      #   Amalgalite::SQLite3::Version.to_a -> [ MAJOR, MINOR, RELEASE ]
+      #
+      # Return the SQLite C library version number as an array of MAJOR, MINOR,
+      # RELEASE
+      # 
+      def self.to_a
+        [ MAJOR, MINOR, RELEASE ]
+      end
+
+    end
+
+    # Version of SQLite that ships with Amalgalite
+    VERSION = Version.to_s.freeze
+  end
+  Version.freeze
+end

data/lib/amalgalite/statement.rb

@@ -0,0 +1,307 @@
+#--
+# Copyright (c) 2008 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+#
+require 'amalgalite3'
+require 'date'
+require 'arrayfields'
+require 'ostruct'
+
+module Amalgalite
+  class Statement
+
+    include ::Amalgalite::SQLite3::Constants
+
+    attr_reader :db
+    attr_reader :sql
+    attr_reader :api
+
+    ##
+    # Initialize a new statement on the database.  
+    #
+    def initialize( db, sql )
+      @db = db
+      prepare_method =  @db.utf16? ? :prepare16 : :prepare
+      @param_positions = {}
+      @stmt_api = @db.api.send( prepare_method, sql )
+    end
+
+    ##
+    # reset the Statement back to it state right after the constructor returned,
+    # except if any variables have been bound to parameters, those are still
+    # bound.
+    #
+    def reset!
+      @stmt_api.reset!
+      @column_names = nil
+      @param_positions = {}
+    end
+
+    ##
+    # reset the Statement back to it state right after the constructor returned,
+    # AND clear all parameter bindings.
+    #
+    def reset_and_clear_bindings!
+      reset!
+      @stmt_api.clear_bindings!
+    end
+
+    ##
+    # Execute the statement with the given parameters
+    #
+    # If a block is given, then yield each returned row to the block.  If no
+    # block is given then return all rows from the result
+    #
+    def execute( *params )
+      bind( *params )
+      if block_given? then
+        while row = next_row
+          yield row
+        end
+      else
+        all_rows
+      end
+    end
+
+    ##
+    # Bind parameters to the sql statement.
+    #
+    # Bindings in SQLite can have a number of formats:
+    #
+    #   ?
+    #   ?num
+    #   :var
+    #   @var
+    #   $var
+    #
+    # Where 'num' is an Integer and 'var'is an alphanumerical variable.
+    # They may exist in the SQL for which this Statement was created. 
+    #
+    # Amalgalite binds parameters to these variables in the following manner:
+    # 
+    # If bind is passed in an Array, either as +bind( "foo", "bar", "baz")+ or
+    # as bind( ["foo", "bar", "baz"] ) then each of the params is assumed to be
+    # positionally bound to the statement( ?, ?num ).
+    # 
+    # If bind is passed a Hash, either as +bind( :foo => 1, :bar => 'sqlite' )+
+    # or as bind( { :foo => 1, 'bar' => 'sqlite' }) then it is assumed that each
+    # parameter should be bound as a named parameter (:var, @var, $var).
+    #
+    # If bind is not passed any parameters, or nil, then nothing happens.
+    #
+    def bind( *params )
+      if params.nil? or params.empty? then
+        check_parameter_count!( 0 )
+        return nil 
+      end
+
+      if params.first.instance_of?( Hash ) then
+        bind_named_parameters( params.first )
+      else
+        bind_positional_parameters( params )
+      end
+    end
+
+    ##
+    # Bind parameters to the statement based upon named parameters
+    #
+    def bind_named_parameters( params )
+      check_parameter_count!( params.size )
+      params.each_pair do | param, value |
+        position = param_position_of( param )
+        if position > 0 then
+          bind_parameter_to( position, value )
+        else
+          raise Amalgalite::Error, "Unable to find parameter '#{param}' in SQL statement [#{sql}]"
+        end
+      end
+    end
+
+    ##
+    # Bind parameters to the statements based upon positions. 
+    #
+    def bind_positional_parameters( params )
+      check_parameter_count!( params.size )
+      params.each_with_index do |value, index|
+        position = index + 1
+        bind_parameter_to( position, value )
+      end
+    end
+
+    ##
+    # bind a single parameter to a particular position
+    #
+    def bind_parameter_to( position, value )
+      bind_type = db.type_map.bind_type_of( value ) 
+      case bind_type
+      when DataType::FLOAT
+        @stmt_api.bind_double( position, value )
+      when DataType::INTEGER
+        @stmt_api.bind_int64( position, value )
+      when DataType::NULL
+        @stmt_api.bind_null( position )
+      when DataType::TEXT
+        @stmt_api.bind_text( position, value.to_s )
+      when DataType::BLOB
+        raise NotImplemented, "Blob binding is not implemented yet"
+      else
+        raise ::Amalgalite::Error, "Unknown binding type of #{bind_type} from #{db.type_map.class.name}.bind_type_of"
+      end
+    end
+      
+
+    ##
+    # Find and cache the binding parameter indexes
+    #
+    def param_position_of( name )
+      ns = name.to_s
+      unless pos = @param_positions[ns] 
+        pos = @param_positions[ns] = @stmt_api.parameter_index( ns )
+      end
+      return pos
+    end
+
+    ##
+    # Check and make sure that the number of parameters aligns with the number
+    # that sqlite expects
+    #
+    def check_parameter_count!( num )
+      expected = @stmt_api.parameter_count
+      if num != expected then 
+        raise Amalgalite::Error, "#{sql} has #{expected} parameters, but #{num} were passed to bind."
+      end
+      return expected
+    end
+
+
+    ##
+    # Iterate over the results of the statement returning each row of results 
+    # as a hash by +column_name+.  The column names are the value after an 
+    # 'AS' in the query or default chosen by sqlite.  
+    #
+    def each
+      while row = next_row
+        yield row
+      end
+      return self
+    end
+
+    ##
+    # Return the next row of data, with type conversion as indicated by the
+    # Database#type_map
+    #
+    def next_row
+      row = []
+      case rc = @stmt_api.step
+      when ResultCode::ROW
+        result_meta.each_with_index do |col, idx|
+          value = nil
+          column_type = @stmt_api.column_type( idx )
+          case column_type
+          when DataType::TEXT
+            value = @stmt_api.column_text( idx )
+          when DataType::FLOAT
+            value = @stmt_api.column_double( idx )
+          when DataType::INTEGER
+            value = @stmt_api.column_int64( idx )
+          when DataType::NULL
+            value = nil
+          when DataType::BLOB
+            raise NotImplemented, "returning a blob is not supported yet"
+          else
+            raise ::Amalgalite::Error, "BUG! : Unknown SQLite column type of #{column_type}"
+          end
+
+          row << db.type_map.result_value_of( col.schema.declared_data_type, value )
+        end
+        row.fields = result_fields
+      when ResultCode::DONE
+        row = nil
+      else
+        raise Amalgalite::SQLite3::Error, 
+              "Received unexepcted result code #{rc} : #{Amalgalite::SQLite3::Constants::ResultCode.from_int( rc )}"
+      end
+      return row
+    end
+
+    ##
+    # Return all rows from the statement as one array
+    #
+    def all_rows
+      rows = []
+      while row = next_row
+        rows << row
+      end
+      return rows
+    end
+
+    ##
+    # Inspect the statement and gather all the meta information about the
+    # results, include the name of the column result column and the origin
+    # column.  The origin column is the original database.table.column the value
+    # comes from.
+    #
+    # The full meta information from teh origin column is also obtained for help
+    # in doing type conversion.
+    #
+    def result_meta
+      unless @result_meta
+        meta = []
+        column_count.times do |idx|
+          column_meta = ::OpenStruct.new
+          column_meta.name = @stmt_api.column_name( idx )
+          
+          db_name  = @stmt_api.column_database_name( idx ) 
+          tbl_name = @stmt_api.column_table_name( idx ) 
+          col_name = @stmt_api.column_origin_name( idx ) 
+
+          column_meta.schema = ::Amalgalite::Column.new( db_name, tbl_name, col_name )
+          column_meta.schema.declared_data_type = @stmt_api.column_declared_type( idx )
+
+          meta << column_meta 
+        end
+        @result_meta = meta
+      end
+      return @result_meta
+    end
+
+    ##
+    # Return the array of field names for the result set, the field names are
+    # all strings
+    #
+    def result_fields
+      @fields ||= result_meta.collect { |m| m.name }
+    end
+
+    ##
+    # Return any unsued SQL from the statement
+    #
+    def remaining_sql
+      @stmt_api.remaining_sql
+    end
+
+
+    ##
+    # return the number of columns in the result of this query
+    #
+    def column_count
+      @stmt_api.column_count
+    end
+    
+    ##
+    # return the raw sql that was originally used to prepare the statement
+    #
+    def sql
+      @stmt_api.sql
+    end
+
+    ##
+    # Close the statement.  The statement is no longer valid for use after it
+    # has been closed.
+    #
+    def close
+      @stmt_api.close
+    end
+  end
+end