flounder 0.8.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d747ac7404138eb5d0dd5adf3e1a936f70381c84
-  data.tar.gz: 6186aeaf643c3f6a2e7f42d18bc7d3b903d3038c
+  metadata.gz: 97e8380edd41a2232f500fc61ceb3f49e2dd3211
+  data.tar.gz: e0330758a5aac5eba5d509cdffa778f0dca41735
 SHA512:
-  metadata.gz: 54e0c5140cbef2595cd5b32333166220f233098c8e5f158f8499538009f2f8a306f5fd6fee026297f509b401e2662998aac17e02b6de4a3ffc6b87b1f21f2a75
-  data.tar.gz: 5bf99fed4005c03b21df75d39adffe4099b83ab032bb207689cdbf249434237db92f577a2927668a15b4a997b0e5061faf8407959d0fe3ed5b9a1deecb491240
+  metadata.gz: c17571110ffbe588b794f026e5eddfc244bd479c37d1a09e4f01639caa4e6031bbb82a1ff5512a616fc4c0069cab4c0165eeddcd5a39535275376c8e8dcf5509
+  data.tar.gz: 76e6e016a4ac6bcaa9f2c8679909a63cd1564efeed5b5ce970d6a41e845cdc77d43c09cc188e0fbd3e367bff6725c382fae2fa223b07b15ce25c15947766417e

data/HISTORY

@@ -0,0 +1,7 @@
+
+# 0.9
+
+ + Allows expressions of the form `where('id=$1', 1)`.
+ + You now need to call `#kick` when performing an insert or an update 
+   to get it to really happen. Please see our documentation in qed/*.
+ + `domain.transaction do |conn| ... end`

data/flounder.gemspec

@@ -2,10 +2,10 @@
 
 Gem::Specification.new do |s|
   s.name     = "flounder"
-  s.version  = '0.8.1'
+  s.version  = '0.9.0'
   s.summary  = "Flounder is a way to write SQL simply in Ruby. It deals with everything BUT object relational mapping. "
   s.email    = "kaspar.schiess@technologyastronauts.ch"
-  s.homepage = "https://bitbucket.org/technologyastronauts/laboratory_flounder"
+  s.homepage = "https://bitbucket.org/technologyastronauts/oss_flounder"
   s.authors  = ['Kaspar Schiess', 'Florian Hanke']
   
   # s.description = <<-EOF

data/lib/flounder/connection.rb

@@ -6,11 +6,14 @@ module Flounder
 
     def initialize pg_conn_args
       @pg = PG.connect(*pg_conn_args)
-      @visitor = Arel::Visitors::ToSql.new(self)
+      @visitor = Arel::Visitors::PostgreSQL.new(self)
     end
 
     attr_reader :visitor
 
+    def transaction &block
+      pg.transaction(&block)
+    end
     def exec *args, &block
       pg.exec *args, &block
     end
@@ -42,7 +45,6 @@ module Flounder
 
     def primary_key name
       fail NotImplementedError
-      @primary_keys[name.to_s]
     end
 
     def table_exists? table_name
@@ -52,7 +54,6 @@ module Flounder
 
     def columns name, message = nil
       fail NotImplementedError
-      @columns[name.to_s]
     end
 
     def quote_table_name name
@@ -63,25 +64,51 @@ module Flounder
       pg.quote_ident name.to_s
     end
 
-    def schema_cache
+     def schema_cache
       self
     end
 
     def quote thing, column = nil
+      # require 'pp '
       # p [:quote, thing, column]
+      # pp caller.first(10)
       pg.escape_literal(thing.to_s)
     end
-    
+
+    # ------------------------------------------------------------------------
+
+    # Turns a PG result row into a hash-like object. There are some transformation
+    # rules that govern this conversion: 
+    #
+    # * All data types are converted to their closest Ruby equivalent 
+    #   (type conversion)
+    # * Fields from the main entity (the entity that started the select)
+    #   are returned on the top level of the hash. 
+    # * Fields from joined entities are returned in a subhash stored under the
+    #   singular name of the joined entity. 
+    # 
+    # Example: 
+    #     row = users.join(posts).on(:id => :user_id).first 
+    #     row[:id]            # refers to users.id, also as row.id
+    #     row[:post][:id]     # refers to posts.id, also as row.post.id
+    #     
+    #     row.keys            # hash keys of the row, not equal to row[:keys]!
+    # 
+    # @param ent [Entity] entity that the query originated from
+    # @param result [PG::Result]
+    # @param row_idx [Fixnum] row we're interested in
+    # @return [Hashie::Mash] result row as hash-like object
+    #    
     def objectify_result_row ent, result, row_idx
       obj = Hashie::Mash.new
   
       each_field(ent, result, row_idx) do 
         |entity, name, value, type_oid, binary, idx|
-        # TODO remove entity resolution from each_field?
 
-        # TODO This is currently here to cover the special case of a query.
-        # Certainly needs refactoring.
-        #
+        # NOTE entity resolution is done both through aliasing and through
+        # postgres column reporting. The above entity variable carries what
+        # postgres reports to us; the block below resolves aliased entity 
+        # names:
         processed_entity, processed_name = yield name if block_given?
         entity = processed_entity if processed_entity
         name   = processed_name if processed_name
@@ -100,8 +127,9 @@ module Flounder
         # The main entity and custom fields (AS something) are available on the
         # top-level of the result. 
         if !entity || entity == ent
-          warn "#{name.inspect} already defined in result set, aliasing occurs." \
+          raise DuplicateField, "#{name.inspect} already defined in result set, aliasing occurs." \
             if obj.has_key? name
+
           obj[name] = typecast_value
         end
       end

data/lib/flounder/connection_pool.rb

@@ -11,18 +11,27 @@ module Flounder
       }
     end
 
-    Spec = Struct.new(:config)
-
+    # Checks out a connection from the pool and yields it to the block. The
+    # connection is returned to the pool at the end of the block; don't hold
+    # on to it. 
+    #
     def with_connection
       @pool.with do |conn|
         yield conn
       end
     end
 
+    # Checks out a connection from the pool. You have to return this
+    # connection manually.
+    #
     def checkout
       @pool.checkout
     end
 
+    Spec = Struct.new(:config)
+
+    # This is needed to conform to arels interface. 
+    #
     def spec
       Spec.new(adapter: 'pg')
     end

data/lib/flounder/domain.rb

@@ -1,4 +1,5 @@
 
+require 'forwardable'
 require 'logger'
 
 module Flounder
@@ -19,15 +20,33 @@ module Flounder
     
     def initialize connection_pool
       @connection_pool = connection_pool
+
+      # maps from plural/singular names to entities in this domain
       @plural = {}
       @singular = {}
+
+      # maps OIDs of entities to entities
       @oids_entity_map = {}
+
       @logger = Logger.new(NilDevice.new)
     end
 
     attr_reader :connection_pool
     attr_accessor :logger
 
+    extend Forwardable
+    def_delegators :connection_pool, :with_connection
+
+    def transaction &block
+      with_connection do |conn|
+        conn.transaction do
+          block.call(conn)
+        end
+      end
+    end
+
+    # Returns the entity with the given plural name. 
+    #
     def [] name
       raise NoSuchEntity, "No such entity #{name.inspect} in this domain." \
         unless @plural.has_key?(name)

data/lib/flounder/engine.rb

@@ -1,4 +1,8 @@
 module Flounder
+
+  # Intermediary class that arel wants us to create. Mostly supports the 
+  # #connection_pool message returning our connection pool. 
+  #
   class Engine
     attr_reader :connection_pool
     attr_reader :connection
@@ -18,6 +22,10 @@ module Flounder
 
     # ---------------------------------------------------- official Engine iface
 
+    # Returns the connection pool. 
+    # 
+    # @return [ConnectionPool]
+    #
     def connection_pool
       @connection_pool
     end

data/lib/flounder/entity.rb

@@ -1,33 +1,58 @@
+require 'forwardable'
+
 module Flounder
+
+  # An entity corresponds to a table in the database. On top of its table 
+  # name, an entity will know its code name (plural) and its singular name, 
+  # what to call a single row returned from this entity. 
+  #
+  # An entity is not a model. In fact, it is what you need to completely
+  # hand-roll your models, without being the model itself.
+  #
+  # Entities are mainly used to start a query via one of the query initiators. 
+  # Almost all of the chain methods on the Query object can be used here as
+  # well - they will return a query object. Entities, like queries, can be 
+  # used as enumerables. 
+  #
+  # Example: 
+  #
+  #   foo = domain.entity(:plural, :singular, 'table_name')
+  # 
+  #   foo.all # SELECT * FROM table_name
+  #   foo.where(id: 1).first  # SELECT * FROM table_name WHERE "table_name"."id" = 1
+  #
   class Entity
-    # Domain this entity is defined in.
+    def initialize domain, plural, singular, table_name
+      @domain = domain
+      @name = plural
+      @singular = singular
+      @table_name = table_name
+      @columns_hash = nil
+
+      @table = Arel::Table.new(table_name)
+    end
+
+    # @return [Domain] Domain this entity is defined in.
     attr_reader :domain
 
-    # Name of the entity in plural form. 
+    # @return [Symbol] Name of the entity in plural form. 
     attr_reader :name
     
     # Also, the name is the plural, so we'll support that as well. 
     alias plural name
 
-    # Name of the entity in singular form. 
+    # @return [Symbol] Name of the entity in singular form. 
     attr_reader :singular
 
-    # Arel table that underlies this entity. 
+    # @return [Arel::Table] Arel table that underlies this entity. 
     attr_reader :table
-    # Name of the table that underlies this entity. 
+    # @return [String] Name of the table that underlies this entity. 
     attr_reader :table_name
 
-    def initialize domain, plural, singular, table_name
-      @domain = domain
-      @name = plural
-      @singular = singular
-      @table_name = table_name
-      @columns_hash = nil
-
-      @table = Arel::Table.new(table_name)
-    end
+    extend Forwardable
+    def_delegators :domain, :transaction, :with_connection
 
-    # Returns a field of the entity.
+    # @return [Field] Field with name of the entity.
     #
     def [] name
       Field.new(self, name, table[name])
@@ -37,51 +62,28 @@ module Flounder
       "entity(#{name}/#{table_name})"
     end
 
-    def query
-      Query.new(domain, self).tap { |q| 
+    # Starts a new select query and yields it to the block. Note that you don't 
+    # need to call this method to obtain a select query - any of the methods
+    # on Query::Select should work on the entity and return a new query object. 
+    #
+    # @return [Query::Select]
+    #
+    def select
+      Query::Select.new(domain, self).tap { |q| 
         yield q if block_given? 
       }
     end
     
     def insert hash
-      Insert.new(domain, self).tap { |i|
-        yield i if block_given?
-        i.insert(hash)
-      }
+      Query::Insert.new(domain, self).tap { |q| 
+        q.row(hash) }
     end
     
     def update hash
-      Update.new(domain, self).tap  { |u|
-        yield u if block_given?
-        u.update(hash)
-      }
+      Query::Update.new(domain, self).tap { |u|
+        u.set(hash) }
     end
-    
-    # Insert or update.
-    #
-    def insdate fields, hash
-      with_transaction do
-        found = where(hash.select { |k, _| fields.include?(k) }).first
-        if found
-          update(hash).where(:id => found.id).returning
-        else
-          result = insert(hash).returning
-          yield result if block_given?
-          result
-        end
-      end
-    end
-    
-    def with_transaction &block
-      result = nil
-      domain.connection_pool.with_connection do |conn|
-        conn.exec 'START TRANSACTION'
-        result = block.call
-        conn.exec 'COMMIT TRANSACTION'
-      end
-      result
-    end
-
+        
     # Temporarily creates a new entity that is available as if it was declared
     # with the given plural and singular, but referencing to the same
     # underlying relation.
@@ -104,14 +106,14 @@ module Flounder
     # Query initiators
     [:where, :join, :outer_join, :project, :order_by].each do |name|
       define_method name do |*args|
-        query { |q| q.send(name, *args) }
+        select { |q| q.send(name, *args) }
       end
     end
 
     # Kickers
     [:first, :all, :size, :delete].each do |name|
       define_method name do |*args|
-        q = query
+        q = select
         q.send(name, *args)
       end
     end

data/lib/flounder/exceptions.rb

@@ -5,4 +5,12 @@ module Flounder
   # to a real field on the underlying relation. 
   #
   class InvalidFieldReference < StandardError; end
+
+  # Indicates that a where clause with bind variables went out of bounds. 
+  class BindIndexOutOfBounds < StandardError; end
+
+  # Exception raised whenever a result set contains two columns with the 
+  # same name. 
+  #
+  class DuplicateField < StandardError; end
 end

data/lib/flounder/field.rb

@@ -6,13 +6,21 @@ module Flounder
       @arel_field = arel_field
     end
 
+    # @return [Entity] entity this field belongs to
     attr_reader :entity
+
+    # @return [Arel::Attribute] arel attribute that corresponds to this field
     attr_reader :arel_field
+
+    # @return [String] name of this field
     attr_reader :name
 
+    # Returns a fully qualified name (table.field).
+    #
+    # @return [String] fully qualified field name
+    #
     def fully_qualified_name
-      # TBD quoting? Demeter?
-      entity.domain.connection_pool.with_connection do |conn|
+      entity.with_connection do |conn|
         table = conn.quote_table_name(entity.table_name)
         column = conn.quote_column_name(name)
         "#{table}.#{column}"

data/lib/flounder/query/base.rb

@@ -0,0 +1,157 @@
+
+module Flounder::Query
+  class Base
+    def initialize domain, manager_klass, entity
+      @domain = domain
+      @engine = Flounder::Engine.new(domain.connection_pool)
+      @manager = manager_klass.new(engine)
+      @entity = entity
+
+      @bind_values = []
+    end
+
+    # Domain that this query was issued from. 
+    attr_reader :domain
+    # Database engine that links Arel to Postgres.
+    attr_reader :engine
+    # Bound values in this query.
+    attr_reader :bind_values
+    # Arel *Manager that accumulates this query.
+    attr_reader :manager
+    # Entity this query operates on.
+    attr_reader :entity
+
+    # Restricts the result returned to only those records that match the 
+    # conditions.
+    #
+    # Example: 
+    #   
+    #   query.where(id: 1)            # ... WHERE id = 1 ...
+    #   query.where(:id => :user_id)  # ... WHERE id = user_id
+    #   query.where(:id.noteq => 1)   # ... WHERE id != 1 
+    #
+    def where *conditions
+      # is this a hash? extract the first element
+      if conditions.size == 1 && conditions.first.kind_of?(Hash)
+        conditions = conditions.first 
+
+        conditions.each do |k, v|
+          manager.where(transform_tuple(k, v))
+        end
+        return self
+      end
+
+      # maybe conditions is of the second form?
+      conditions.each do |cond_str, *values|
+        manager.where(
+          Arel::Nodes::SqlLiteral.new(
+            rewrite_bind_variables(cond_str, bind_values.size, values.size)))
+        bind_values.concat values
+      end
+    end 
+
+    def with name, query
+      # Nodes::TableAlias.new(relation, name)
+      manager.with(query.manager)
+    end   
+
+   # Kickers
+    def to_sql
+      prepare_kick
+      
+      manager.to_sql.tap { |sql| 
+        domain.log_sql(sql) }
+    end
+
+    # Returns all rows of the query result as an array. Individual rows are
+    # mapped to objects using the row mapper. 
+    #
+    def kick connection=nil
+      all = nil
+
+      (connection || engine).exec(self.to_sql, bind_values) do |result|
+        all = Array.new(result.ntuples, nil)
+        result.ntuples.times do |row_idx|
+          all[row_idx] = engine.connection.
+            objectify_result_row(entity, result, row_idx) do |name|
+              column_name_to_entity(name)
+            end
+        end
+      end
+
+      all
+    end
+    def column_name_to_entity name
+      # Implement this if your column names in the query allow inferring
+      # the entity and the column name. Return them as a tuple <entity, name>.
+    end
+
+  private
+    # Prepares a kick - meaning an execution on the database or a transform
+    # to an sql string. Ready Set... 
+    #
+    def prepare_kick
+      # should be overridden
+    end
+
+     # Rewrites a statement that contains bind placeholders like '$1' to
+    # contain placeholders starting at offset+1. Also checks that no
+    # placeholder exceeds the limit.
+    # 
+    def rewrite_bind_variables str, offset, limit
+      str.gsub(%r(\$(?<idx>\d+))) do |match|
+        idx = Integer($~[:idx])
+
+        raise Flounder::BindIndexOutOfBounds, 
+          "Binding to $#{idx} in #{str.inspect}, but only #{limit} variables provided" \
+          if idx-1 >= limit
+
+        "$#{idx + offset}" 
+      end
+    end
+
+    # Called on each key/value pair of a
+    #  * condition
+    #  * join
+    # clause, this returns a field that can be passed to Arel
+    #  * #where
+    #  * #on
+    #
+    def transform_tuple field, value
+      if value.kind_of? Flounder::Field
+        value = value.arel_field
+      end
+
+      case field
+        # covers: :field_a => ...
+        when Symbol
+          join_and_condition_part(entity[field].arel_field, value)
+        # covers: entity[:field] => ...
+        when Flounder::Field
+          join_and_condition_part(field.arel_field, value)
+        # covers: :field_a.noteq => ...
+        when Flounder::SymbolExtensions::Modifier
+          join_and_condition_part(
+            field.to_arel_field(entity), 
+            value, 
+            field.kind)
+      else
+        fail "Could not transform condition part. (#{field.inspect}, #{value.inspect})"
+      end
+    end
+    def join_and_condition_part arel_field, value, kind=:eq
+      case value
+        # covers :field_a => :field_b
+        when Symbol
+          value_field = entity[value].arel_field
+          arel_field.send(kind, value_field)
+        # covers: :field => (1..100)
+        when Range
+          arel_field.in(value)
+      else
+        arel_field.send(kind, value)
+      end
+    end
+
+  end
+end

data/lib/flounder/{immediate.rb → query/immediate.rb}

@@ -1,5 +1,5 @@
 
-module Flounder
+module Flounder::Query
   # An immmediate string that needs to be passed around and _not_ quoted or
   # escaped when going to the database. 
   #

data/lib/flounder/query/insert.rb

@@ -0,0 +1,41 @@
+
+require_relative 'base'
+require_relative 'returning'
+
+module Flounder::Query
+
+  # An insert.
+  #
+  class Insert < Base
+    def initialize domain, into_entity
+      super domain, Arel::InsertManager, into_entity
+
+      manager.into entity.table
+    end
+
+    # Add one row to the inserts.
+    #
+    def row fields
+      manager.insert(
+        fields.map { |k, v| 
+          transform_values(k, v) })
+    end
+
+    include Returning
+  private
+  
+    # Called on each key/value pair of an insert clause, this returns a 
+    # hash that can be passed to Arel #insert. 
+    #
+    def transform_values field, value
+      case field
+        when Symbol, String
+          [entity[field.to_sym].arel_field, value]
+        when Flounder::Field
+          [field.arel_field, value]
+      else
+        fail "Could not transform value. (#{field.inspect}, #{value.inspect})"
+      end
+    end
+  end # class
+end # module Flounder

data/lib/flounder/query/returning.rb

@@ -0,0 +1,19 @@
+
+
+module Flounder::Query
+  module Returning
+    def returning_fields
+      @returning_fields || '*'
+    end
+
+    def returning fields
+      @returning_fields = fields
+
+      self
+    end
+
+    def to_sql
+      super << " RETURNING #{returning_fields}"
+    end
+  end
+end