swift 0.14.0 → 1.0.0

data/lib/swift/adapter.rb

@@ -1,3 +1,6 @@
+require 'swift/result'
+require 'swift/statement'
+
 module Swift
 
   # Adapter.
@@ -5,7 +8,11 @@ module Swift
   # @abstract
   # @see      Swift::DB See Swift::DB for concrete adapters.
   class Adapter
-    attr_reader :options
+    attr_reader :db
+
+    def initialize db
+      @db = db
+    end
 
     # Select by id(s).
     #
@@ -14,47 +21,46 @@ module Swift
     # @example Complex primary key.
     #   Swift.db.get(UserAddress, user_id: 12, address_id: 15)
     #
-    # @param  [Swift::Scheme] scheme Concrete scheme subclass to load.
+    # @param  [Swift::Record] record Concrete record subclass to load.
     # @param  [Hash]          keys   Hash of id(s) <tt>{id_name: value}</tt>.
-    # @return [Swift::Scheme, nil]
-    # @see    Swift::Scheme.get
+    # @return [Swift::Record, nil]
+    # @see    Swift::Record.get
     #--
-    # NOTE: Not significantly shorter than Scheme.db.first(User, 'id = ?', 12)
-    def get scheme, keys
-      resource = scheme.new(keys)
-      prepare_get(scheme).execute(*resource.tuple.values_at(*scheme.header.keys)).first
+    # NOTE: Not significantly shorter than Record.db.first(User, 'id = ?', 12)
+    def get record, keys
+      resource = record.new(keys)
+      execute(record, command_get(record), *resource.tuple.values_at(*record.header.keys)).first
     end
 
     # Create one or more.
     #
-    # @example Scheme.
+    # @example Record.
     #   user = User.new(name: 'Apply Arthurton', age: 32)
     #   Swift.db.create(User, user)
-    #   #=> Swift::Scheme
-    # @example Coerce hash to scheme.
+    #   #=> Swift::Record
+    # @example Coerce hash to record.
     #   Swif.db.create(User, name: 'Apple Arthurton', age: 32)
-    #   #=> Swift::Scheme
+    #   #=> Swift::Record
     # @example Multiple resources.
     #   apple = User.new(name: 'Apple Arthurton', age: 32)
     #   benny = User.new(name: 'Benny Arthurton', age: 30)
     #   Swift.db.create(User, [apple, benny])
-    #   #=> Array<Swift::Scheme>
+    #   #=> Array<Swift::Record>
     # @example Coerce multiple resources.
     #   Swift.db.create(User, [{name: 'Apple Arthurton', age: 32}, {name: 'Benny Arthurton', age: 30}])
-    #   #=> Array<Swift::Scheme>
+    #   #=> Array<Swift::Record>
     #
-    # @param  [Swift::Scheme]                                   scheme    Concrete scheme subclass to load.
-    # @param  [Swift::Scheme, Hash, Array<Swift::Scheme, Hash>] resources The resources to be saved.
-    # @return [Swift::Scheme, Array<Swift::Scheme>]
-    # @note   Hashes will be coerced into a Swift::Scheme resource via Swift::Scheme#new
+    # @param  [Swift::Record]                                   record    Concrete record subclass to load.
+    # @param  [Swift::Record, Hash, Array<Swift::Record, Hash>] resources The resources to be saved.
+    # @return [Swift::Record, Array<Swift::Record>]
+    # @note   Hashes will be coerced into a Swift::Record resource via Swift::Record#new
     # @note   Passing a scalar will result in a scalar.
-    # @see    Swift::Scheme.create
-    def create scheme, resources
-      statement = prepare_create(scheme)
-      result    = [resources].flatten.map do |resource|
-        resource = scheme.new(resource) unless resource.kind_of?(scheme)
-        result   = statement.execute(*resource.tuple.values_at(*scheme.header.insertable))
-        resource.tuple[scheme.header.serial] = result.insert_id if scheme.header.serial
+    # @see    Swift::Record.create
+    def create record, resources
+      result = [resources].flatten.map do |resource|
+        resource = record.new(resource) unless resource.kind_of?(record)
+        result   = execute(command_create(record), *resource.tuple.values_at(*record.header.insertable))
+        resource.tuple[record.header.serial] = result.insert_id if record.header.serial
         resource
       end
       resources.kind_of?(Array) ? result : result.first
@@ -62,44 +68,43 @@ module Swift
 
     # Update one or more.
     #
-    # @example Scheme.
+    # @example Record.
     #   user      = Swift.db.create(User, name: 'Apply Arthurton', age: 32)
     #   user.name = 'Arthur Appleton'
     #   Swift.db.update(User, user)
-    #   #=> Swift::Scheme
-    # @example Coerce hash to scheme.
+    #   #=> Swift::Record
+    # @example Coerce hash to record.
     #   user      = Swift.db.create(User, name: 'Apply Arthurton', age: 32)
     #   user.name = 'Arthur Appleton'
     #   Swif.db.update(User, user.tuple)
-    #   #=> Swift::Scheme
+    #   #=> Swift::Record
     # @example Multiple resources.
     #   apple = Swift.db.create(User, name: 'Apple Arthurton', age: 32)
     #   benny = Swift.db.create(User, name: 'Benny Arthurton', age: 30)
     #   Swift.db.update(User, [apple, benny])
-    #   #=> Array<Swift::Scheme>
+    #   #=> Array<Swift::Record>
     # @example Coerce multiple resources.
     #   apple = Swift.db.create(User, name: 'Apple Arthurton', age: 32)
     #   benny = Swift.db.create(User, name: 'Benny Arthurton', age: 30)
     #   Swift.db.update(User, [apple.tuple, benny.tuple])
-    #   #=> Array<Swift::Scheme>
+    #   #=> Array<Swift::Record>
     #
-    # @param  [Swift::Scheme]                                   scheme    Concrete scheme subclass to load.
-    # @param  [Swift::Scheme, Hash, Array<Swift::Scheme, Hash>] resources The resources to be updated.
-    # @return [Swift::Scheme, Swift::Result]
-    # @note   Hashes will be coerced into a Swift::Scheme resource via Swift::Scheme#new
+    # @param  [Swift::Record]                                   record    Concrete record subclass to load.
+    # @param  [Swift::Record, Hash, Array<Swift::Record, Hash>] resources The resources to be updated.
+    # @return [Swift::Record, Swift::Result]
+    # @note   Hashes will be coerced into a Swift::Record resource via Swift::Record#new
     # @note   Passing a scalar will result in a scalar.
-    # @see    Swift::Scheme#update
-    def update scheme, resources
-      statement = prepare_update(scheme)
-      result    = [resources].flatten.map do |resource|
-        resource = scheme.new(resource) unless resource.kind_of?(scheme)
-        keys     = resource.tuple.values_at(*scheme.header.keys)
+    # @see    Swift::Record#update
+    def update record, resources
+      result = [resources].flatten.map do |resource|
+        resource = record.new(resource) unless resource.kind_of?(record)
+        keys     = resource.tuple.values_at(*record.header.keys)
 
         # TODO: Name the key field(s) missing.
-        raise ArgumentError, "#{scheme} resource has incomplete key: #{resource.inspect}" \
+        raise ArgumentError, "#{record} resource has incomplete key: #{resource.inspect}" \
           unless keys.select(&:nil?).empty?
 
-        statement.execute(*resource.tuple.values_at(*scheme.header.updatable), *keys)
+        execute(command_update(record), *resource.tuple.values_at(*record.header.updatable), *keys)
         resource
       end
       resources.kind_of?(Array) ? result : result.first
@@ -107,11 +112,11 @@ module Swift
 
     # Delete one or more.
     #
-    # @example Scheme.
+    # @example Record.
     #   user      = Swift.db.create(User, name: 'Apply Arthurton', age: 32)
     #   user.name = 'Arthur Appleton'
     #   Swift.db.delete(User, user)
-    # @example Coerce hash to scheme.
+    # @example Coerce hash to record.
     #   user      = Swift.db.create(User, name: 'Apply Arthurton', age: 32)
     #   user.name = 'Arthur Appleton'
     #   Swif.db.delete(User, user.tuple)
@@ -124,23 +129,22 @@ module Swift
     #   benny = Swift.db.create(User, name: 'Benny Arthurton', age: 30)
     #   Swift.db.delete(User, [apple.tuple, benny.tuple])
     #
-    # @param  [Swift::Scheme]                                   scheme    Concrete scheme subclass to load.
-    # @param  [Swift::Scheme, Hash, Array<Swift::Scheme, Hash>] resources The resources to be deleteed.
-    # @return [Swift::Scheme, Array<Swift::Scheme>]
-    # @note   Hashes will be coerced into a Swift::Scheme resource via Swift::Scheme#new
+    # @param  [Swift::Record]                                   record    Concrete record subclass to load.
+    # @param  [Swift::Record, Hash, Array<Swift::Record, Hash>] resources The resources to be deleteed.
+    # @return [Swift::Record, Array<Swift::Record>]
+    # @note   Hashes will be coerced into a Swift::Record resource via Swift::Record#new
     # @note   Passing a scalar will result in a scalar.
-    # @see    Swift::Scheme#delete
-    def delete scheme, resources
-      statement = prepare_delete(scheme)
-      result    = [resources].flatten.map do |resource|
-        resource = scheme.new(resource) unless resource.kind_of?(scheme)
-        keys     = resource.tuple.values_at(*scheme.header.keys)
+    # @see    Swift::Record#delete
+    def delete record, resources
+      result = [resources].flatten.map do |resource|
+        resource = record.new(resource) unless resource.kind_of?(record)
+        keys     = resource.tuple.values_at(*record.header.keys)
 
         # TODO: Name the key field(s) missing.
-        raise ArgumentError, "#{scheme} resource has incomplete key: #{resource.inspect}" \
+        raise ArgumentError, "#{record} resource has incomplete key: #{resource.inspect}" \
           unless keys.select(&:nil?).empty?
 
-        if result = statement.execute(*keys)
+        if result = execute(command_delete(record), *keys)
           resource.freeze
         end
         result
@@ -148,22 +152,77 @@ module Swift
       resources.kind_of?(Array) ? result : result.first
     end
 
-    protected
-      def prepare_get scheme
-        raise NotImplementedError
-      end
+    # Create a server side prepared statement
+    #
+    # @example
+    #   finder = Swift.db.prepare(User, "select * from users where id > ?")
+    #   user   = finder.execute(1).first
+    #   user.id
+    #
+    # @overload prepare(record, command)
+    #   @param  [Swift::Record]       record    Concrete record subclass to load.
+    #   @param  [String]              command   Command to be prepared by the underlying concrete adapter.
+    # @overload prepare(command)
+    #   @param  [String]              command   Command to be prepared by the underlying concrete adapter.
+    #
+    # @return [Swift::Statement, Swift::DB::Mysql::Statement, Swift::DB::Sqlite3::Statement, ...]
+    def prepare record = nil, command
+      record ? Statement.new(record, command) : db.prepare(command)
+    end
 
-      def prepare_create scheme
-        raise NotImplementedError
-      end
+    # Trace commands being executed.
+    #
+    # @example
+    #   Swift.db.trace { Swift.db.execute("select * from users") }
+    # @example
+    #   Swift.db.trace(StringIO.new) { Swift.db.execute("select * from users") }
+    # @example
+    #   Swift.db.trace(File.open('command.log', 'w')) { Swift.db.execute("select * from users") }
+    #
+    # @param  [IO]      io      An optional IO object to log commands
+    # @return [Object]  result  Result from the block yielded to
+    def trace io = $stdout
+      @trace = io
+      result = yield
+      @trace = false
+      result
+    end
 
-      def prepare_update scheme
-        raise NotImplementedError
-      end
+    # Check if the adapter commands are being traced.
+    #
+    # @return [TrueClass, FalseClass]
+    def trace?
+      !!@trace
+    end
 
-      def prepare_delete scheme
-        raise NotImplementedError
-      end
+    # Execute a command using the underlying concrete adapter.
+    #
+    # @example
+    #   Swift.db.execute("select * from users")
+    # @example
+    #   Swift.db.execute(User, "select * from users where id = ?", 1)
+    #
+    # @overload execute(record, command, *bind)
+    #   @param  [Swift::Record]       record    Concrete record subclass to load.
+    #   @param  [String]              command   Command to be executed by the adapter.
+    #   @param  [*Object]             bind      Bind values.
+    # @overload execute(command, *bind)
+    #   @param  [String]              command   Command to be executed by the adapter.
+    #   @param  [*Object]             bind      Bind values.
+    #
+    # @return [Swift::Result, Swift::DB::Mysql::Result, Swift::DB::Sqlite3::Result, ...]
+    def execute command, *bind
+      start = Time.now
+      record, command = command, bind.shift if command.kind_of?(Class) && command < Record
+      record ? Result.new(record, db.execute(command, *bind)) : db.execute(command, *bind)
+    ensure
+      log_command(start, command, bind) if @trace
+    end
 
+    private
+
+    def log_command start, command, bind
+      @trace.print Time.now.strftime('%F %T.%N'), ' - ', (Time.now - start).to_f, ' - ', command, ' ', bind, $/
+    end
   end # Adapter
 end # Swift

data/lib/swift/attribute.rb

@@ -7,10 +7,10 @@ module Swift
     attr_reader :name, :field, :key, :serial
 
     # @example
-    #   user = Class.new(Swift::Scheme)
+    #   user = Class.new(Swift::Record)
     #   Swift::Attribute.new(user, :name, Swift::Type::String)
     #
-    # @param [Swift::Scheme] scheme
+    # @param [Swift::Record] record
     # @param [Symbol]        name
     # @param [Hash]          options
     # @option options [Object, Proc]          :default
@@ -18,15 +18,26 @@ module Swift
     # @option options [TrueClass, FalseClass] :key
     # @option options [TrueClass, FalseClass] :serial
     #
-    # @see Swift::Scheme
+    # @see Swift::Record
     # @see Swift::Type
-    def initialize scheme, name, options = {}
+    def initialize record, name, options = {}
       @name    = name
       @default = options.fetch(:default, nil)
       @field   = options.fetch(:field,   name)
       @key     = options.fetch(:key,     false)
       @serial  = options.fetch(:serial,  false)
-      define_scheme_methods(scheme)
+      define_record_methods(record)
+    end
+
+    def default
+      case @default
+        when Numeric, Symbol, true, false, nil
+          @default
+        when Proc
+          @default.call
+        else
+          @default.dup
+      end
     end
 
     # The attributes field.
@@ -36,9 +47,9 @@ module Swift
       field.to_s
     end
 
-    # Evals attribute accessors for this attribute into the scheme.
-    def define_scheme_methods scheme
-      scheme.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+    # Evals attribute accessors for this attribute into the record.
+    def define_record_methods record
+      record.class_eval <<-RUBY, __FILE__, __LINE__ + 1
         def #{name};        tuple.fetch(:#{field}, nil)   end
         def #{name}= value; tuple.store(:#{field}, value) end
       RUBY

data/lib/swift/eventmachine.rb

@@ -0,0 +1,49 @@
+require 'eventmachine'
+require 'swift'
+
+module Swift
+  # Eventmachine Adapter Extensions.
+  #
+  # This replaces the Adapter#execute method with a non-blocking asynchronous version.
+  class Adapter
+    alias :blocking_execute :execute
+
+    class EMHandler < EM::Connection
+      def initialize adapter, record, defer
+        @adapter = adapter
+        @record  = record
+        @defer   = defer
+      end
+
+      def notify_readable
+        detach
+        begin
+          @defer.succeed(@record ? Result.new(@record, @adapter.result) : @adapter.result)
+        rescue Exception => e
+          @defer.fail(e)
+        end
+      end
+    end
+
+    # Execute a command asynchronously.
+    #
+    # @example
+    #   defer = Swift.db.execute(User, "select * from users where id = ?", 1)
+    #   defer.callback do |user|
+    #     p user.id
+    #   end
+    #   defer.errback do |error|
+    #     p error
+    #   end
+    #
+    # @see  [Swift::Adapter]
+    def execute command, *bind
+      start = Time.now
+      record, command = command, bind.shift if command.kind_of?(Class) && command < Record
+      query(command, *bind)
+      EM::DefaultDeferrable.new.tap do |defer|
+        EM.watch(fileno, EMHandler, self, record, defer) {|c| c.notify_readable = true }
+      end
+    end
+  end
+end

data/lib/swift/identity_map.rb

@@ -33,17 +33,17 @@ module Swift
     end
   end
 
-  class Scheme
+  class Record
     #--
     # TODO: Redefined method :(
     def self.load tuple
       im = [self, *tuple.values_at(*header.keys)]
-      unless scheme = Swift.db.identity_map.get(im)
-        scheme       = allocate
-        scheme.tuple = tuple
-        Swift.db.identity_map.set(im, scheme)
+      unless record = Swift.db.identity_map.get(im)
+        record       = allocate
+        record.tuple = tuple
+        Swift.db.identity_map.set(im, record)
       end
-      scheme
+      record
     end
-  end # Scheme
+  end # Record
 end # Swift

data/lib/swift/migrations.rb

@@ -2,15 +2,15 @@ module Swift
   module Migrations
     module ClassMethods
       # @example
-      #   class User < Swift::Scheme
+      #   class User < Swift::Record
       #     migrations do |db|
       #       db.execute %q{create table users(id serial, name text, age int)}
       #     end
       #   end
       #
-      # @param [Proc] &migrations
+      # @param [Proc] migrations
       #
-      # @see Swift::Scheme
+      # @see Swift::Record
       def migrations &migrations
         define_singleton_method(:migrate!, lambda{|db = Swift.db| migrations.call(db)})
       end
@@ -20,7 +20,7 @@ module Swift
       #
       # @param [Swift::Adapter] db
       #
-      # @see Swift::Scheme
+      # @see Swift::Record
       def migrate! db = Swift.db
         db.migrate! self
       end
@@ -30,25 +30,25 @@ module Swift
       # @example
       #   db.migrate! User
       #
-      # @param [Swift::Scheme] scheme
+      # @param [Swift::Record] record
       #
       # @see Swift::Adapter::Sql
-      def migrate! scheme
-        keys   =  scheme.header.keys
-        fields =  scheme.header.map{|p| field_definition(p)}.join(', ')
+      def migrate! record
+        keys   =  record.header.keys
+        fields =  record.header.map{|p| field_definition(p)}.join(', ')
         fields += ", primary key (#{keys.join(', ')})" unless keys.empty?
 
-        execute("drop table if exists #{scheme.store} cascade")
-        execute("create table #{scheme.store} (#{fields})")
+        execute("drop table if exists #{record.store} cascade")
+        execute("create table #{record.store} (#{fields})")
       end
     end # InstanceMethods
   end # Migrations
 
   def self.migrate! name = nil
-    schema.each{|scheme| scheme.migrate!(db(name)) }
+    schema.each{|record| record.migrate!(db(name)) }
   end
 
-  class Scheme
+  class Record
     extend Migrations::ClassMethods
   end
 

data/lib/swift/{scheme.rb → record.rb}

@@ -2,17 +2,17 @@ module Swift
 
   # A resource (instance) definition.
   #
-  # @example A user scheme.
-  #   class User < Swift::Scheme
+  # @example A user record.
+  #   class User < Swift::Record
   #     store     :users
   #     attribute :id,         Swift::Type::Integer, serial: true, key: true
   #     attribute :name,       Swift::Type::String
   #     attribute :email,      Swift::Type::String
   #     attribute :updated_at, Swift::Type::Time
   #   end # User
-  class Scheme
+  class Record
     attr_accessor :tuple
-    alias_method :scheme, :class
+    alias_method :record, :class
 
     # @example
     #   User.new(
@@ -22,7 +22,7 @@ module Swift
     #   )
     # @param [Hash] options Create resource and set attributes. <tt>{name: value}</tt>
     def initialize options = {}
-      @tuple = scheme.header.new_tuple
+      @tuple = record.header.new_tuple
       options.each{|k, v| public_send(:"#{k}=", v)}
     end
 
@@ -37,7 +37,7 @@ module Swift
     # @param [Hash] options Update attributes. <tt>{name: value}</tt>
     def update options = {}
       options.each{|k, v| public_send(:"#{k}=", v)}
-      Swift.db.update(scheme, self)
+      Swift.db.update(record, self)
     end
 
     # @example
@@ -48,7 +48,7 @@ module Swift
     #   )
     #   apple.delete
     def delete resources = self
-      Swift.db.delete(scheme, resources)
+      Swift.db.delete(record, resources)
     end
 
     class << self
@@ -65,12 +65,12 @@ module Swift
       end
 
       def load tuple
-        scheme       = allocate
-        scheme.tuple = tuple
-        scheme
+        record       = allocate
+        record.tuple = tuple
+        record
       end
 
-      # Define a new attribute for this scheme.
+      # Define a new attribute for this record.
       #
       # @see Swift::Attribute#new
       def attribute name, type, options = {}
@@ -102,7 +102,7 @@ module Swift
       #     updated_at: Time.now
       #   )
       #
-      # @param [Hash, Array<Hash>] options Create with attributes. <tt>{name: value}</tt>
+      # @param [Hash, Array<Hash>] resources Create with attributes. <tt>{name: value}</tt>
       def create resources = {}
         Swift.db.create(self, resources)
       end
@@ -115,7 +115,7 @@ module Swift
       #   UserAddress.get(user_id: 12, address_id: 15)
       #
       # @param  [Hash] keys Hash of id(s) <tt>{id_name: value}</tt>.
-      # @return [Swift::Scheme, nil]
+      # @return [Swift::Record, nil]
       def get keys
         Swift.db.get(self, keys)
       end
@@ -143,10 +143,9 @@ module Swift
       # @param  [*Object] binds     Bind values.
       # @yield  [Swift::Result]
       # @return [Swift::Result]
-      def execute statement = '', *binds, &block
-        Swift.db.execute(self, statement, *binds, &block)
+      def execute statement = '', *binds
+        Swift::Result.new(self, Swift.db.execute(statement, *binds))
       end
     end
-  end # Scheme
+  end # Record
 end # Swift
-

data/lib/swift/result.rb

@@ -0,0 +1,24 @@
+require 'forwardable'
+
+module Swift
+  # Result.
+  #
+  # Wrapper for command result. It lazily instantiates a new Swift::Record instance for each result row.
+  class Result
+    include Enumerable
+    extend  Forwardable
+
+    def_delegators :@result, :selected_rows, :affected_rows, :fields, :types, :insert_id
+
+    def initialize record, result
+      @record = record
+      @result = result
+    end
+
+    def each
+      @result.each do |tuple|
+        yield @record.allocate.tap {|s| s.tuple = tuple}
+      end
+    end
+  end # Result
+end # Swift

data/lib/swift/statement.rb

@@ -0,0 +1,25 @@
+require 'swift/result'
+
+module Swift
+  # Statement.
+  #
+  # Wrapper for server side prepared statements.
+  class Statement
+    def initialize record, command
+      @record    = record
+      @statement = Swift.db.prepare(command)
+    end
+
+    # Execute a statement.
+    #
+    # @example
+    #   statement = Swift.db.prepare(User, "select * from users where id > ?")
+    #   statement.execute(10)
+    #
+    # @param  [*Object]         bind    Bind values
+    # @return [Swift::Result]
+    def execute *bind, &block
+      Result.new(@record, @statement.execute(*bind), &block)
+    end
+  end # Statement
+end # Swift

data/lib/swift/synchrony.rb

@@ -0,0 +1,38 @@
+require 'em-synchrony'
+require 'swift/eventmachine'
+
+module Swift
+  # em-synchrony support for Swift::Adapter
+  #
+  # This replaces the default Adapter#execute with a version that uses EM::Synchrony.sync to wait for the
+  # defered command to complete. It assumes that the execute method is called inside a em-synchrony Fiber.
+  class Adapter
+    alias :aexecute :execute
+
+    # Execute a command asynchronously and pause the Fiber until the command finishes.
+    #
+    # @example
+    #   EM.run do
+    #     3.times.each do |n|
+    #       EM.synchrony do
+    #         db     = Swift.setup(:default, Swift::Adapter::Postgres, db: "swift_test")
+    #         result = db.execute("select pg_sleep(3 - #{n}), #{n + 1} as qid")
+    #
+    #         p result.first
+    #         EM.stop if n == 0
+    #       end
+    #     end
+    #   end
+    #
+    # @see [Swift::Adapter]
+    def execute *args
+      res = EM::Synchrony.sync aexecute(*args)
+      raise res if res.kind_of?(Error)
+      yield res if block_given?
+      res
+    rescue => e
+      $stderr.puts e, e.backtrace.join($/)
+      nil
+    end
+  end
+end