flounder 0.8.1 → 0.9.0

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

@@ -1,14 +1,14 @@
-module Flounder
+
+require_relative 'base'
+
+module Flounder::Query
 
   # A query obtained by calling any of the chain methods on an entity.
   #
-  class Query
+  class Select < Base
     def initialize domain, from_entity
-      @domain = domain
-      @from_entity = from_entity
-      @engine = Engine.new(from_entity.domain.connection_pool)
-      @manager = Arel::SelectManager.new(@engine)
-    
+      super domain, Arel::SelectManager, from_entity
+  
       @has_projection = false
 
       @projection_prefixes = Hash.new
@@ -19,15 +19,8 @@ module Flounder
       manager.from from_entity.table
     end
 
-    # Domain that this query was issued from. 
-    attr_reader :domain
-    # Entity that this query acts on.
-    attr_reader :from_entity
-
     # Arel SqlManager that accumulates this query. 
     attr_reader :manager
-    # Database engine that links Arel to Postgres.
-    attr_reader :engine
 
     # All projected fields if no custom projection is made. Fields are encoded
     # so that they can be traced back to the entity that contributed them. 
@@ -37,13 +30,6 @@ module Flounder
     # prefix during this query. 
     attr_reader :projection_prefixes
 
-    def where conditions
-      conditions.each do |k, v|
-        manager.where(transform_hash(k, v))
-      end
-      self
-    end    
-
     def _join join_node, entity
       @last_join = entity
 
@@ -53,6 +39,7 @@ module Flounder
 
       self
     end
+
     def add_fields_to_default entity
       prefix = entity.name.to_s
       table = entity.table
@@ -79,12 +66,12 @@ module Flounder
     def on join_conditions
       join_conditions.each do |k, v|
         manager.on(
-          transform_hash(k, join_field(v)))
+          transform_tuple(k, join_field(v)))
       end
       self
     end
     def anchor
-      @from_entity = @last_join
+      @entity = @last_join
       self
     end
 
@@ -115,14 +102,7 @@ module Flounder
       self
     end
 
-    # Kickers
-    def to_sql
-      prepare_kick
-      
-      manager.to_sql.tap { |sql| 
-        domain.log_sql(sql) }
-    end
-    alias sql to_sql
+    alias all kick
 
     def each &block
       all.each(&block)
@@ -140,46 +120,20 @@ module Flounder
 
       all.first.count
     end
-    def delete
-      # things.where(...).delete.all
-      #
-      # Code that I actually want:
-      #
-      # @manager = manager.compile_delete
-      # self
-      #
-      # But for now it's a kicker:
-      #
-      engine.exec(manager.compile_delete.to_sql)
-    end
 
-    # Returns all rows of the query result as an array. Individual rows are
-    # mapped to objects using the row mapper. 
-    #
-    def all
-      all = nil
-      engine.exec(sql) do |result|
-        all = Array.new(result.ntuples, nil)
-        result.ntuples.times do |row_idx|
-          all[row_idx] = engine.connection.
-            objectify_result_row(from_entity, result, row_idx) do |name|
-              unless default_projection.empty?
-                extract_source_info_from_name(name)
-              end
-            end
-        end
-      end
+  private
 
-      all
+    def column_name_to_entity name
+      unless default_projection.empty?
+        extract_source_info_from_name(name)
+      end
     end
-
-  private
   
     # Transforms a simple symbol into either a field of the last .join table, 
     # or respects field values passed in. 
     #
     def join_field name
-      return name if name.kind_of? Field
+      return name if name.kind_of? Flounder::Field
       @last_join[name]
     end
 
@@ -201,13 +155,14 @@ module Flounder
     def map_to_field field_ref
       case field_ref 
         when Symbol
-          from_entity[field_ref]
+          entity[field_ref]
         when String
           Immediate.new(field_ref)
-        when Field
+        when Flounder::Field
           field_ref
       else
-        fail InvalidFieldReference, "Cannot resolve #{field_ref.inspect} to a field."
+        fail Flounder::InvalidFieldReference, 
+          "Cannot resolve #{field_ref.inspect} to a field."
       end
     end
 
@@ -251,47 +206,9 @@ module Flounder
         when Flounder::Field
           field.fully_qualified_name
         when Flounder::SymbolExtensions::Modifier
-          field.to_arel_field(from_entity).send field.kind
-      else
-        from_entity[field].arel_field
-      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_hash field, value
-      if value.kind_of? Field
-        value = value.arel_field
-      end
-
-      case field
-        when Symbol
-          join_and_condition_part(from_entity[field].arel_field, value)
-        when Flounder::Field
-          join_and_condition_part(field.arel_field, value)
-        when Flounder::SymbolExtensions::Modifier
-          join_and_condition_part(
-            field.to_arel_field(from_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
-        when Symbol
-          value_field = from_entity[value].arel_field
-          arel_field.send(kind, value_field)
-        when Range
-          arel_field.in(value)
+          field.to_arel_field(entity).send field.kind
       else
-        arel_field.send(kind, value)
+        entity[field].arel_field
       end
     end
 

data/lib/flounder/query/update.rb

@@ -0,0 +1,45 @@
+require_relative 'base'
+require_relative 'returning'
+
+module Flounder::Query
+
+  # An update obtained by calling any of the chain methods on an entity.
+  #
+  class Update < Base
+    def initialize domain, entity
+      super(domain, Arel::UpdateManager, entity)
+
+      manager.table entity.table
+    end
+
+    # Add one row to the updates.
+    #
+    def set fields
+      manager.set(
+        fields.map { |k, v| 
+          transform_attributes(k, v) })
+    end
+
+    include Returning
+
+  private
+
+    # Called on each key/value pair of an update clause, this returns a 
+    # hash that can be passed to Arel #update. 
+    #
+    def transform_attributes field, value
+      if value.kind_of? Flounder::Field
+        value = value.arel_field
+      end
+
+      case field
+        when Symbol, String
+          [entity[field.to_sym].arel_field, value]
+        when Flounder::Field
+          [field.arel_field, value]
+      else
+        fail "Could not transform condition part. (#{field.inspect}, #{value.inspect})"
+      end
+    end
+  end # class
+end # module Flounder

data/lib/flounder/symbol_extensions.rb

@@ -13,6 +13,9 @@ module Flounder
       end
     end
 
+    # NOTE mixing comparison ops with asc and desc is nasty, but not really 
+    # relevant. Errors will get raised later on - we're not in the business of 
+    # checking your SQL for validity. 
     [:not_eq, :lt, :gt, :gteq, :lteq, :matches, :asc, :desc].each do |kind|
       define_method kind do
         Modifier.new(self, kind)

data/lib/flounder.rb

@@ -12,10 +12,12 @@ require 'flounder/engine'
 require 'flounder/entity'
 require 'flounder/entity_alias'
 require 'flounder/field'
-require 'flounder/immediate'
-require 'flounder/query'
-require 'flounder/insert'
-require 'flounder/update'
+
+require 'flounder/query/immediate'
+require 'flounder/query/select'
+require 'flounder/query/insert'
+
+require 'flounder/query/update'
 require 'flounder/exceptions'
 
 module Flounder

data/qed/applique/ae.rb

@@ -2,6 +2,6 @@ require 'ae'
 
 def generates_sql(expected)
   -> (given) {
-    given.sql.gsub(/^SELECT.*FROM/, 'SELECT [fields] FROM').assert == expected
+    given.to_sql.gsub(/^SELECT.*FROM/, 'SELECT [fields] FROM').assert == expected
   }
 end

data/qed/atomic_insert_update.md

@@ -0,0 +1,33 @@
+
+THIS IS A TODO, NOT A FEATURE
+
+# Atomic INSERT, then UPDATE
+
+As an experimental feature, `Flounder` allows you to combine `INSERT` and `UPDATE` statements into one statement. This is executed as atomically as possible on the database. Two methods are responsible for this bit of magic, both composed of parts of the word 'INSERT' and 'UPDATE': `#insdate` and `#upsert`. We'll expose the difference between these two later on, for now, let's just jump right ahead and use them as intended.
+
+For example, let's look at inserting a user only if it doesn't exist on the database yet.
+
+~~~ruby
+#  pre = users.count
+#
+#  users.insdate(:name, name: 'upsert')
+#  users.insdate(:name, name: 'upsert')
+#  
+#  post = users.count
+#  post.assert == pre+1
+~~~
+
+# Intricacies of design
+
+Here's a decomposition of what the insdate is behind the scenes, into its parts: It serves as an illustration for turtles all the way down:
+~~~ruby
+  update = users.update(name: 'FooBar').where(name: 'BarBaz')
+
+  users.insert(name: 'FooBar').
+    with(:upsert, update).
+    where(:id.not_in => 'upsert.id').
+    assert generates_sql(
+      %Q(WITH upsert AS ()))
+~~~
+
+Note that the above code does strictly nothing, since Arel (our SQL generator) currently does not support `WITH` for `INSERT`/`UPDATE`. For this reason, we decide not to implement upsert/insdate at this point. 

data/qed/conditions.md

@@ -5,9 +5,15 @@ A simple use case.
   s2013.user.id.assert == 1
 ~~~
 
-# Using strings in where to allow for cases not covered in Flounder/Arel.
-#
-# ~~~ruby
-#   posts = domain[:posts].where('id == (?) OR title == "(?)"', 1, "Hello").all
-#   posts.first.id.assert == 1
-# ~~~
+# Complex Conditions
+
+Complex conditions can be written in SQL directly. You can use the postgres positional bind syntax to bind values to your conditions safely.
+
+~~~ruby
+  query = domain[:posts].where(["id = ($1) OR title = ($2)", 1, "Hello"])
+  query.assert generates_sql(
+      %Q(SELECT [fields] FROM "posts"  WHERE id = ($1) OR title = ($2)))
+
+  post = query.first
+  post.id.assert == 1
+~~~

data/qed/exceptions.md

@@ -9,4 +9,25 @@ All of these statements raise an `InvalidFieldReference` exception.
   expect Flounder::InvalidFieldReference do
     users.project(1, 2, 3)
   end
-~~~
+~~~
+
+# Double projection
+
+You cannot have the same field name twice in a result. 
+
+~~~ruby
+  expect Flounder::DuplicateField do
+    users.project('id, id').all
+  end
+~~~
+
+# Bind Index out of Bounds
+
+Indices of bind expressions in `#where` need to be relative to the argument list given. 
+
+~~~ruby
+  expect Flounder::BindIndexOutOfBounds do
+    users.where('id = $100', 1)
+  end
+~~~
+

data/qed/index.md

@@ -55,7 +55,12 @@ Fields can be used fully qualified by going through the entity.
     assert generates_sql(%Q(SELECT [fields] FROM "users"  WHERE "users"."id" = 10))
 
   domain[:users].where(domain[:users][:name].matches => 'a%').
-    assert generates_sql(%Q(SELECT [fields] FROM "users"  WHERE "users"."name" LIKE 'a%'))
+    assert generates_sql(%Q(SELECT [fields] FROM "users"  WHERE "users"."name" ILIKE 'a%'))
+~~~
+
+~~~ruby
+  domain[:users].where(:user_id => :approver_id).
+  assert generates_sql("SELECT [fields] FROM \"users\"  WHERE \"users\".\"user_id\" = \"users\".\"approver_id\"")
 ~~~
 
 # Some JOINs
@@ -90,7 +95,7 @@ So just doing `A.B.C` will give you the first of the above possibilities. Here's
 
 The call to `#anchor` anchors all further joins at that point. 
 
-# ORDER BY
+# Ordering records
 
 ~~~ruby
   domain[:users].where(id: 2013).order_by(domain[:users][:id]).
@@ -104,5 +109,34 @@ The call to `#anchor` anchors all further joins at that point.
 
 ~~~ruby
   domain[:users].where(id: 2013).project(domain[:users][:id]).
-    sql.assert == %Q(SELECT "users"."id" FROM "users"  WHERE "users"."id" = 2013)
+    to_sql.assert == %Q(SELECT "users"."id" FROM "users"  WHERE "users"."id" = 2013)
+~~~
+
+# Transactions
+
+Transactions are supported on the domain and on entities. Since you need to make sure that your transaction uses only one connection, you will need to handle connections explicitly. 
+
+~~~ruby
+  expect RuntimeError do
+    domain.with_connection do |conn|
+      conn.transaction do
+        posts.update(title: 'A single title for everyone').kick(conn)
+        fail 'rollback'
+      end
+    end
+  end
+
+  posts.first.title.assert != 'A single title for everyone'
 ~~~
+
+The same works on any entity from the domain. Please note that there is a shortcut for getting at a transaction.
+
+~~~ruby
+  domain.transaction do |conn| 
+    posts.all(conn)
+  end
+
+  posts.transaction do |conn|
+    posts.all(conn)
+  end
+~~~

data/qed/inserts.md

@@ -3,13 +3,13 @@ An insert creates a state from which SQL can be extracted.
 ~~~ruby
   sql = users.insert(:name => 'Mr. Insert SQL').to_sql
 
-  sql.assert == "INSERT INTO \"users\" (\"name\") VALUES ('Mr. Insert SQL')"
+  sql.assert == "INSERT INTO \"users\" (\"name\") VALUES ('Mr. Insert SQL') RETURNING *"
 ~~~
 
 Using returning will return the inserted object.
 
 ~~~ruby
-  results = users.insert(:name => 'Mr. Returning Asterisk').returning
+  results = users.insert(:name => 'Mr. Returning Asterisk').kick
 
   results.first.name.assert == 'Mr. Returning Asterisk'
 ~~~
@@ -17,7 +17,7 @@ Using returning will return the inserted object.
 Returning all fields is the default, but you can provide that explicitly.
 
 ~~~ruby
-  results = users.insert(:name => 'Mr. Returning Asterisk').returning '*'
+  results = users.insert(:name => 'Mr. Returning Asterisk').returning('*').kick
 
   results.first.name.assert == 'Mr. Returning Asterisk'
 ~~~
@@ -25,7 +25,7 @@ Returning all fields is the default, but you can provide that explicitly.
 Using returning with a field name will return those fields of the inserted object.
 
 ~~~ruby
-  results = users.insert(:name => 'Mr. Returning').returning(:id)
+  results = users.insert(:name => 'Mr. Returning').returning(:id).kick
 
   id = results.first.id
 
@@ -35,7 +35,7 @@ Using returning with a field name will return those fields of the inserted objec
 Flounder fields can be used as keys.
 
 ~~~ruby
-  results = users.insert(users[:name] => 'Mr. Flounder Field').returning
+  results = users.insert(users[:name] => 'Mr. Flounder Field').kick
 
   results.first.name.assert == 'Mr. Flounder Field'
 ~~~

data/qed/ordering.md

@@ -17,9 +17,9 @@ They can be ordered ASC.
 They can also be ordered DESC.
 
 ~~~ruby
-  sql = domain[:posts].order_by(:title.desc).to_sql
-
-  sql.assert == 'SELECT "posts"."id" AS _posts_id, "posts"."title" AS _posts_title, "posts"."text" AS _posts_text, "posts"."user_id" AS _posts_user_id, "posts"."approver_id" AS _posts_approver_id FROM "posts"   ORDER BY "posts"."title" DESC'
+  domain[:posts].order_by(:title.desc).
+    assert generates_sql(
+      'SELECT [fields] FROM "posts"   ORDER BY "posts"."title" DESC')
 ~~~
 
 Multiple fields can be used.
@@ -43,15 +43,22 @@ Ordering can be defined in many ways.
 ~~~ruby
   user = users.first
 
-  inserted = posts.insert(:title => 'ABC', :text => 'Alphabet', :user_id => user.id).returning '*'
-
-  domain[:posts].order_by(:title).map(&:title).assert == ['ABC', 'First Light']
-  domain[:posts].order_by(:title.asc).map(&:title).assert == ['ABC', 'First Light']
-  domain[:posts].order_by(:title.desc).map(&:title).assert == ['First Light', 'ABC']
-  domain[:posts].order_by('title').map(&:title).assert == ['ABC', 'First Light']
-  domain[:posts].order_by('title ASC').map(&:title).assert == ['ABC', 'First Light']
-  domain[:posts].order_by('title DESC').map(&:title).assert == ['First Light', 'ABC']
-  domain[:posts].order_by(posts[:title]).map(&:title).assert == ['ABC', 'First Light']
-  domain[:posts].order_by(posts[:title].asc).map(&:title).assert == ['ABC', 'First Light']
-  domain[:posts].order_by(posts[:title].desc).map(&:title).assert == ['First Light', 'ABC']
+  inserted = posts.insert(
+    title: 'ABC', text: 'Alphabet', user_id: user.id).kick
+
+  def titles_by *args
+    domain[:posts].order_by(*args).map(&:title)
+  end
+
+  titles_by(:title).assert == ['ABC', 'First Light']
+  titles_by(:title.asc).assert == ['ABC', 'First Light']
+  titles_by(:title.desc).assert == ['First Light', 'ABC']
+
+  titles_by('title').assert == ['ABC', 'First Light']
+  titles_by('title ASC').assert == ['ABC', 'First Light']
+  titles_by('title DESC').assert == ['First Light', 'ABC']
+
+  titles_by(posts[:title]).assert == ['ABC', 'First Light']
+  titles_by(posts[:title].asc).assert == ['ABC', 'First Light']
+  titles_by(posts[:title].desc).assert == ['First Light', 'ABC']
 ~~~

data/qed/projection.md

@@ -1,3 +1,4 @@
+
 Without projection, result objects will be packaged in a subhash.
 
 ~~~ruby

data/qed/updates.md

@@ -5,7 +5,7 @@ An update creates a state from which SQL can be extracted.
   
   sql = posts.update(:title => 'Update SQL').where(:id => post.id).to_sql
 
-  sql.assert == 'UPDATE "posts" SET "title" = \'Update SQL\' WHERE "posts"."id" = 1'
+  sql.assert == 'UPDATE "posts" SET "title" = \'Update SQL\' WHERE "posts"."id" = 1 RETURNING *'
 ~~~
 
 Flounder fields are ok.
@@ -13,17 +13,20 @@ Flounder fields are ok.
 ~~~ruby
   post = posts.first
   
-  sql = posts.update(posts[:title] => 'Update Flounder SQL').where(:id => post.id).to_sql
+  sql = posts.
+    update(posts[:title] => 'Update Flounder SQL').
+    where(:id => post.id).to_sql
 
-  sql.assert == 'UPDATE "posts" SET "title" = \'Update Flounder SQL\' WHERE "posts"."id" = 1'
+  sql.assert == 'UPDATE "posts" SET "title" = \'Update Flounder SQL\' WHERE "posts"."id" = 1 RETURNING *'
 ~~~
 
 It can update a single field.
 
 ~~~ruby
-  post = posts.first
-  
-  post = posts.update(:title => 'Update Field').where(:id => post.id).returning.first
+  post_id = posts.first.id
+  post = posts.
+    update(title: 'Update Field').
+    where(id: post_id).kick.first
 
   post.title.assert == 'Update Field'
 ~~~
@@ -33,7 +36,9 @@ Flounder fields are ok here too.
 ~~~ruby
   post = posts.first
   
-  post = posts.update(posts[:title] => 'Update Flounder Field').where(:id => post.id).returning.first
+  post = posts.
+    update(posts[:title] => 'Update Flounder Field').
+    where(:id => post.id).kick.first
 
   post.title.assert == 'Update Flounder Field'
 ~~~
@@ -45,7 +50,7 @@ An update can take multiple fields.
   
   sql = posts.update(:title => 'Update SQL', :text => 'Update Multiple Fields Text').where(:id => post.id).to_sql
 
-  sql.assert == 'UPDATE "posts" SET "title" = \'Update SQL\', "text" = \'Update Multiple Fields Text\' WHERE "posts"."id" = 1'
+  sql.assert == 'UPDATE "posts" SET "title" = \'Update SQL\', "text" = \'Update Multiple Fields Text\' WHERE "posts"."id" = 1 RETURNING *'
 ~~~
 
 Updating a single row is possible.
@@ -53,7 +58,7 @@ Updating a single row is possible.
 ~~~ruby
   post = posts.first
   
-  post = posts.update(:title => 'Updated Title', :text => 'Update Single Row Possible').where(:id => post.id).returning.first
+  post = posts.update(:title => 'Updated Title', :text => 'Update Single Row Possible').where(:id => post.id).kick.first
 
   post.title.assert == 'Updated Title'
   post.text.assert == 'Update Single Row Possible'
@@ -62,7 +67,7 @@ Updating a single row is possible.
 Updating multiple rows is possible.
 
 ~~~ruby
-  updated = users.update(:name => 'Update Multiple Rows').where(:name.not_eq => nil).returning
+  updated = users.update(:name => 'Update Multiple Rows').where(:name.not_eq => nil).kick
 
   updated.map(&:name).assert == ['Update Multiple Rows']*6
 ~~~