amalgalite 0.1.0 → 0.2.0

data/gemspec.rb

@@ -23,6 +23,7 @@ Amalgalite::GEM_SPEC = Gem::Specification.new do |spec|
   # spec.add_dependency("rake", ">= 0.8.1")
   spec.add_dependency("configuration", ">= 0.0.5")
   spec.add_dependency("arrayfields", ">= 4.5.0")
+  spec.add_dependency("mkrf", ">= 0.2.3")
   
 
   if ext_conf = Configuration.for_if_exist?("extension") then

data/lib/amalgalite.rb

@@ -20,6 +20,7 @@ end
     sqlite3 
     statement 
     table 
+    taps
     trace_tap 
     type_map 
     version 

data/lib/amalgalite/blob.rb

@@ -4,11 +4,176 @@
 #++
 module Amalgalite
   ##
-  # Eventually this will be amalgalites interface to the SQLite Blob API to
-  # allow for streaming of data to and from Blobs in an SQLite database.
+  # This is the interface to allow Blob objects to be written to and read from
+  # the SQLite database.  When using statements, use a Blob object as
+  # the wrapper around the source to be written to the row, and a Blob object is
+  # returned if the the type mapping warrents during select queries.
   #
-  # Right now it is just a place holder.
+  # For instance during an insert:
   #
-  class Blob
+  #   blob_column = db.schema.tables['blobs'].columsn['data']
+  #   db.execute("INSERT INTO blobs(name, data) VALUES ( $name, $blob )",
+  #             { "$name" => "/path/to/file",
+  #               "$blob" => Amalgalite::Blob.new( :file => '/path/to/file',
+  #                                                :column => blob_column) } )
+  #
+  #   db.execute("INSERT INTO blobs(id, data) VALUES ($id, $blob )",
+  #             { "$name" => 'blobname',
+  #               "$blob" => Amalgalite::Blob.new( :io => "something with .read and .length methods",
+  #                                                :column => blob_column) } )
+  #
+  # On select the blob data needs to be read into an IO object
+  #
+  #   all_rows = db.execute("SELECT name, blob FROM blobs WHERE name = '/path/to/file' ")
+  #   blob_row = all_rows.first
+  #   blob_row['blob'].write_to_file( blob_row['name'] )
+  #   
+  # Or write to an IO object
+  #   
+  #   blob_results = {}
+  #   db.execute("SELECT name, blob FROM blobs") do |row|
+  #     io = StringIO.new
+  #     row['blob'].write_to_io( io )
+  #     blob_results[row['name']] = io
+  #     # or use a shortcut
+  #     # blob_results[row['name']] = row['blob'].to_string_io
+  #   end
+  #
+  # If using a Blob as a conditional, for instance in a WHERE clause then the
+  # Blob must resolvable to a String.
+  #
+  #   db.execute("SELECT FROM blobs(name, data) WHERE data = $blob",
+  #             { "$blob' => Amalgalite::Blob.new( :string => "A string of data" ) })
+  #
+  class Blob 
+    class Error < ::Amalgalite::Error; end
+    class << self
+      def valid_source_params
+        @valid_source_params ||= [ :file, :io, :string, :db_blob ]
+      end
+
+      def default_block_size
+        @default_block_size ||= 8192
+      end
+    end
+
+    # the object representing the source of the blob
+    attr_reader :source 
+
+    # the size in bytes of the of the blob
+    attr_reader :length
+
+    # the size in bytes of the blocks of data to move from the source
+    attr_reader :block_size
+
+    # the column the blob is associated with
+    attr_reader :column
+
+    ##
+    # Initialize a new blob, it takes a single parameter, a hash which describes
+    # the source of the blob.  The keys of the hash are one of:
+    #
+    #   :file    : the value is the path to a file on the file system
+    #   :io      : the value is an object that responds to the the methods +read+
+    #              and +length+.  +read+ should have the behavior of IO#read
+    #   :db_blob : not normally used by an end user, used to initialize a blob
+    #              object that is returned from an SQL query.
+    #   :string  : used when a Blob is part of a WHERE clause
+    #
+    # And additional key of :block_size may be used to indicate the maximum size
+    # of a single block of data to move from the source to the destination, this
+    # defaults ot 8192.
+    #
+    def initialize( params )
+      if (Blob.valid_source_params & params.keys).size > 1 then
+        raise Blob::Error, "Only a one of #{Blob.valid_source_params.join(', ')} is allowed to initialize a Blob.  #{params.keys.join(', ')} were sent"
+      end
+
+      @source                  = nil
+      @source_length           = 0
+      @close_source_after_read = false
+      @incremental             = true
+      @block_size              = params[:block_size] || Blob.default_block_size
+      @column                  = params[:column]     
+
+      raise Blob::Error, "A :column parameter is required for a Blob" unless @column
+
+      if params.has_key?( :file ) then
+        @source = File.open( params[:file], "r" )
+        @length = File.size( params[:file] )
+        @close_source_after_read = true
+      elsif params.has_key?( :io ) then
+        @source = params[:io]
+        @length = @source.length
+      elsif params.has_key?( :db_blob ) then
+        @source = params[:db_blob]
+        @length = @source.length
+        @close_source_after_read = true
+      elsif params.has_key?( :string ) then
+        @source = params[:string]
+        @length = @source.length
+        @incremental = false
+      end
+    end
+
+    ##
+    # close the source when done reading from it
+    #
+    def close_source_after_read?
+      @close_source_after_read
+    end
+
+    ##
+    # is this an incremental Blob or not
+    #
+    def incremental?
+      @incremental
+    end
+
+    ##
+    # Write the Blob to an IO object
+    #
+    def write_to_io( io )
+      if source.respond_to?( :read ) then
+        while buf = source.read( block_size ) do
+          io.write( buf )
+        end
+      else
+        io.write( source.to_s )
+      end
+
+      if close_source_after_read? then
+        source.close
+      end
+    end
+
+    ##
+    # write the Blob contents to a StringIO
+    #
+    def to_string_io
+      sio = StringIO.new
+      write_to_io( sio )
+      return sio
+    end
+
+    ##
+    # Write the Blob contents to a File.  
+    #
+    def write_to_file( filename, modestring="w" )
+      File.open(filename, modestring) do |f|
+        write_to_io( f )
+      end
+    end
+
+    ##
+    # Write the Blob contents to the column.  This assumes that the row_id to
+    # insert into is the last row that was inserted into the db
+    #
+    def write_to_column!
+      last_rowid = column.schema.db.last_insert_rowid
+      SQLite3::Blob.new( column.schema.db.api, column.db, column.table, column.name, last_rowid, "w" ) do |sqlite_blob|
+        write_to_io( sqlite_blob )
+      end
+    end
   end
 end

data/lib/amalgalite/column.rb

@@ -13,7 +13,10 @@ module Amalgalite
   # information from a SELECT query.
   #
   class Column
-    # the database this column belongs to
+    # the schema object this column is associated with
+    attr_accessor :schema
+
+    # the database name this column belongs to
     attr_accessor :db
 
     # the column name
@@ -47,7 +50,7 @@ module Amalgalite
     ## 
     # Create a column with its name and associated table
     #
-    def initialize( db, name, table )
+    def initialize( db, table, name)
       @db                 = db
       @name               = name
       @table              = table

data/lib/amalgalite/schema.rb

@@ -19,6 +19,7 @@ module Amalgalite
     attr_reader :schema 
     attr_reader :tables
     attr_reader :views
+    attr_reader :db
 
     #
     # Create a new instance of Schema
@@ -46,6 +47,7 @@ module Amalgalite
       @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 )
+        table.schema = self
 
         @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|
@@ -64,12 +66,13 @@ module Amalgalite
     def load_columns( table )
       cols = {}
       @db.execute("PRAGMA table_info(#{table.name})") do |row|
-        col = Amalgalite::Column.new( "main", row['name'], table )
+        col = Amalgalite::Column.new( "main", table.name, row['name'] )
 
         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
+        col.schema = self
         cols[col.name] = col
       end
       cols
@@ -82,6 +85,7 @@ module Amalgalite
       @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'] )
+        view.schema = self
         @views[view.name] = view
       end
       @views

data/lib/amalgalite/statement.rb

@@ -17,14 +17,30 @@ module Amalgalite
     attr_reader :sql
     attr_reader :api
 
+    class << self
+      # special column names that indicate that indicate the column is a rowid
+      def rowid_column_names
+        @rowid_column_names ||= %w[ ROWID OID _ROWID_ ]
+      end
+    end
+
     ##
     # Initialize a new statement on the database.  
     #
     def initialize( db, sql )
       @db = db
-      prepare_method =  @db.utf16? ? :prepare16 : :prepare
+      prepare_method   =  @db.utf16? ? :prepare16 : :prepare
       @param_positions = {}
-      @stmt_api = @db.api.send( prepare_method, sql )
+      @stmt_api        = @db.api.send( prepare_method, sql )
+      @blobs_to_write  = []
+      @rowid_index     = nil
+    end
+
+    ##
+    # Is the special column "ROWID", "OID", or "_ROWID_" used?
+    #
+    def using_rowid_column?
+      not @rowid_index.nil?
     end
 
     ##
@@ -34,8 +50,9 @@ module Amalgalite
     #
     def reset!
       @stmt_api.reset!
-      @column_names = nil
       @param_positions = {}
+      @blobs_to_write.clear
+      @rowid_index = nil
     end
 
     ##
@@ -47,20 +64,39 @@ module Amalgalite
       @stmt_api.clear_bindings!
     end
 
+    ##
+    # reset the statment in preparation for executing it again
+    #
+    def reset_for_next_execute!
+      @stmt_api.reset!
+      @stmt_api.clear_bindings!
+      @blobs_to_write.clear
+    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
+    # block is given then return all rows from the result.  No matter what the
+    # prepared statement should be reset before returning the final time.
     #
     def execute( *params )
       bind( *params )
-      if block_given? then
-        while row = next_row
-          yield row
+      begin
+        if block_given? then
+          while row = next_row
+            yield row
+          end
+        else
+          all_rows
         end
-      else
-        all_rows
+      ensure
+        s = $!
+        begin 
+          reset_for_next_execute!
+        rescue => e
+        end
+        raise s if s
       end
     end
 
@@ -110,11 +146,11 @@ module Amalgalite
       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
+      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
 
@@ -144,12 +180,17 @@ module Amalgalite
       when DataType::TEXT
         @stmt_api.bind_text( position, value.to_s )
       when DataType::BLOB
-        raise NotImplemented, "Blob binding is not implemented yet"
+        if value.incremental? then
+          @stmt_api.bind_zeroblob( position, value.length )
+          @blobs_to_write << value
+        else
+          @stmt_api.bind_blob( position, value.source )
+        end
       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
@@ -174,6 +215,17 @@ module Amalgalite
       return expected
     end
 
+    ##
+    # Write any blobs that have been bound to parameters to the database.  This
+    # assumes that the blobs go into the last inserted row
+    #
+    def write_blobs
+      unless @blobs_to_write.empty?
+        @blobs_to_write.each do |blob|
+          blob.write_to_column!
+        end
+      end
+    end
 
     ##
     # Iterate over the results of the statement returning each row of results 
@@ -208,7 +260,19 @@ module Amalgalite
           when DataType::NULL
             value = nil
           when DataType::BLOB
-            raise NotImplemented, "returning a blob is not supported yet"
+            # if the rowid column is encountered, then we can use an incremental
+            # blob api, otherwise we have to use the all at once version.
+            if using_rowid_column? then
+              value = Amalgalite::Blob.new( :db_blob => SQLite3::Blob.new( db.api,
+                                                                           col.schema.db,
+                                                                           col.schema.table,
+                                                                           col.schema.name,
+                                                                           @stmt_api.column_int64( @rowid_index ),
+                                                                          "r"),
+                                            :column => col.schema)
+            else
+              value = Amalgalite::Blob.new( :string => @stmt_api.column_blob( idx ), :column => col.schema )
+            end
           else
             raise ::Amalgalite::Error, "BUG! : Unknown SQLite column type of #{column_type}"
           end
@@ -218,9 +282,10 @@ module Amalgalite
         row.fields = result_fields
       when ResultCode::DONE
         row = nil
+        write_blobs
       else
         raise Amalgalite::SQLite3::Error, 
-              "Received unexepcted result code #{rc} : #{Amalgalite::SQLite3::Constants::ResultCode.from_int( rc )}"
+              "SQLITE ERROR #{rc} (#{Amalgalite::SQLite3::Constants::ResultCode.from_int( rc )}) : #{@db.api.last_error_message}"
       end
       return row
     end
@@ -245,13 +310,17 @@ module Amalgalite
     # The full meta information from teh origin column is also obtained for help
     # in doing type conversion.
     #
+    # As iteration over the row meta informatio happens, record if the special
+    # "ROWID", "OID", or "_ROWID_" column is encountered.  If that column is
+    # encountered then we make note of it.
+    #
     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 ) 
@@ -259,13 +328,31 @@ module Amalgalite
           column_meta.schema = ::Amalgalite::Column.new( db_name, tbl_name, col_name )
           column_meta.schema.declared_data_type = @stmt_api.column_declared_type( idx )
 
+          # only check for rowid if we have a table name and it is not the
+          # sqlite_master table.  We could get recursion in those cases.
+          if not using_rowid_column? and tbl_name and tbl_name != 'sqlite_master' and is_column_rowid?( tbl_name, col_name ) then
+            @rowid_index = idx
+          end
+
           meta << column_meta 
         end
+
         @result_meta = meta
       end
       return @result_meta
     end
 
+    ##
+    # is the column indicated by the Column a 'rowid' column
+    #
+    def is_column_rowid?( table_name, column_name )
+      column_schema  = @db.schema.tables[table_name].columns[column_name]
+      if column_schema.primary_key? and column_schema.declared_data_type.upcase == "INTEGER" then
+        return true
+      end
+      return false
+    end
+
     ##
     # Return the array of field names for the result set, the field names are
     # all strings
@@ -288,7 +375,7 @@ module Amalgalite
     def column_count
       @stmt_api.column_count
     end
-    
+
     ##
     # return the raw sql that was originally used to prepare the statement
     #