flounder 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6b703e899203d9243eed106f9cb6cf3d4b58e2c7
+  data.tar.gz: 1cc85a58b7942aea21f9b684c11320f355e92ab0
+SHA512:
+  metadata.gz: e86c577be0793530e9aa64b518c0c62e954728b230434d874e87275e767437050f676b630d6dbc96cbc28ff70390224e9b04336deff504842cdc39b428b83b5f
+  data.tar.gz: 4a2e9d534c6acdd851b7344a75f2099eae066beebbe118045a05f8a6bb1be25633c1d3a1516bff8a3ea89bd7e7b5049575f3eaaf64fae7564319dd4cc9a32731

data/Gemfile

@@ -0,0 +1,8 @@
+source "https://rubygems.org"
+
+group :test do
+  gem 'qed'
+  gem 'ae'
+end
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,33 @@
+PATH
+  remote: .
+  specs:
+    flounder (0.2.0)
+      arel (~> 5, > 5.0.1)
+      connection_pool (~> 2)
+      hashie (~> 3, >= 3.2)
+      pg (> 0.17)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ae (1.8.2)
+      ansi
+    ansi (1.4.3)
+    arel (5.0.1.20140414130214)
+    brass (1.2.1)
+    connection_pool (2.0.0)
+    facets (2.9.3)
+    hashie (3.2.0)
+    pg (0.17.1)
+    qed (2.9.1)
+      ansi
+      brass
+      facets (>= 2.8)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  ae
+  flounder!
+  qed

data/HACKING

@@ -0,0 +1,13 @@
+
+
+# Running the tests
+
+This project uses QED for testing. Please create a database called 'flounder'
+and then run the SQL in `qed/flounder.sql` in that database context. 
+
+Then do a 
+
+    qed 
+
+and the tests will run. 
+

data/LICENSE

@@ -0,0 +1,23 @@
+
+ Copyright (c) 2014 Kaspar Schiess
+
+ Permission is hereby granted, free of charge, to any person
+ obtaining a copy of this software and associated documentation
+ files (the "Software"), to deal in the Software without
+ restriction, including without limitation the rights to use,
+ copy, modify, merge, publish, distribute, sublicense, and/or sell
+ copies of the Software, and to permit persons to whom the
+ Software is furnished to do so, subject to the following
+ conditions:
+
+ The above copyright notice and this permission notice shall be
+ included in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+ OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+ HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+ WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+ OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -0,0 +1,21 @@
+
+Flounder is a way to write SQL simply in Ruby. It deals with everything BUT
+object relational mapping. 
+
+SYNOPSIS
+
+  require 'flounder'
+  d = Flounder.domain do |dom|
+    dom.entity(:users, 'users')
+  end
+
+  d[:users].where(:id.lt => 10).to_a
+
+STATUS
+
+Company-wide private alpha. 
+
+LICENSE
+
+  Private code for now. No use permitted.
+

data/flounder.gemspec

@@ -0,0 +1,22 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name     = "flounder"
+  s.version  = '0.2.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.authors  = ['Kaspar Schiess']
+  
+  # s.description = <<-EOF
+  # EOF
+
+  s.add_runtime_dependency 'arel', '~> 5', '> 5.0.1'
+  s.add_runtime_dependency 'pg', '> 0.17'
+  s.add_runtime_dependency 'hashie', '~> 3', '>= 3.2'
+  s.add_runtime_dependency 'connection_pool', '~> 2'
+  
+  s.files         = Dir['**/*']
+  s.test_files    = Dir['qed/**/*']
+  s.require_paths = ["lib"]
+end

data/lib/flounder/connection.rb

@@ -0,0 +1,81 @@
+
+module Flounder
+  class Connection
+    attr_reader :pg
+    attr_reader :visitor
+
+    def initialize pg_conn_args
+      @pg = PG.connect(*pg_conn_args)
+      @visitor = Arel::Visitors::ToSql.new(self)
+    end
+
+    attr_reader :visitor
+
+    def exec *args, &block
+      pg.exec *args, &block
+    end
+
+    # ------------------------------------------------ official Connection iface
+    def schema_cache
+      self
+    end
+
+    Column = Struct.new(:name, :type)
+    def columns_hash table_name
+      hash = {}
+      pg.exec(%Q(select * from #{quote_table_name(table_name)} limit 0)) do |result|
+
+        # TBD This is a duplicate from the code in Query.
+        result.nfields.times do |idx|
+          name = result.fname(idx)
+          type_oid = result.ftype(idx)
+          mod  = result.fmod(idx)
+          typesym = type_oid_to_sym(type_oid)
+
+          unless typesym
+            type_string = type_name(type_oid, mod)
+            fail "No map for oid #{type_oid} found, type(#{type_string})."
+          end
+
+          hash[name] = Column.new(name, typesym)
+        end
+      end
+      
+      hash
+    end
+
+    def primary_key name
+      fail
+      @primary_keys[name.to_s]
+    end
+
+    def table_exists? table_name
+      # TBD Centralize these direct SQL statements in some class
+      ! pg.exec(%Q(select count(*) from pg_class where relname = #{quote(table_name)})).getvalue(0,0).nil?
+    end
+
+    def columns name, message = nil
+      fail
+      @columns[name.to_s]
+    end
+
+    def quote_table_name name
+      pg.quote_ident name.to_s
+    end
+
+    def quote_column_name name
+      pg.quote_ident name.to_s
+    end
+
+    def schema_cache
+      self
+    end
+
+    def quote thing, column = nil
+      # p [:quote, thing, column]
+      pg.escape_literal(thing.to_s)
+    end
+  private 
+    include PostgresUtils
+  end
+end

data/lib/flounder/connection_pool.rb

@@ -0,0 +1,30 @@
+require 'connection_pool'
+
+module Flounder
+  class ConnectionPool
+    attr_reader :pg_conn_args
+
+    def initialize pg_conn_args
+      @pg_conn_args = pg_conn_args
+      @pool = ::ConnectionPool.new(size: 5, timeout: 5) {
+        Connection.new(pg_conn_args)
+      }
+    end
+
+    Spec = Struct.new(:config)
+
+    def with_connection
+      @pool.with do |conn|
+        yield conn
+      end
+    end
+
+    def checkout
+      @pool.checkout
+    end
+
+    def spec
+      Spec.new(adapter: 'pg')
+    end
+  end
+end

data/lib/flounder/domain.rb

@@ -0,0 +1,74 @@
+
+require 'logger'
+
+module Flounder
+  # Raised when an entity name cannot be found in this domain. 
+  class NoSuchEntity < StandardError
+  end
+
+  class Domain
+    attr_reader :connection_pool
+    attr_accessor :logger
+
+    # A device that discards all logging made to it. This is used to be silent
+    # by default while still allowing the logging of all queries. 
+    #
+    class NilDevice
+      def write *args
+      end
+      def close *args
+      end
+    end
+    
+    def initialize connection_pool
+      @connection_pool = connection_pool
+      @plural = {}
+      @singular = {}
+      @oids_entity_map = {}
+      @logger = Logger.new(NilDevice.new)
+    end
+    def [] name
+      raise NoSuchEntity, "No such entity #{name.inspect} in this domain." \
+        unless @plural.has_key?(name)
+
+      @plural.fetch(name)
+    end
+
+    # Logs sql statements that are prepared for execution. 
+    #
+    def log_sql sql
+      @logger.info sql
+    end
+
+    # Define a database entity and alias it to plural and singular names that 
+    # will be used in the code. 
+    #
+    def entity plural, singular, table_name
+      entity = Entity.new(self, plural, singular, table_name).
+        tap { |e| yield e if block_given? }
+
+      @plural[plural] = entity
+      @singular[singular] = entity
+
+      # Also maps OID to entities for field resolution
+      @oids_entity_map[table_oid(table_name)] = entity
+
+      entity
+    end
+
+    # Returns an entity by table oid.
+    #
+    def by_oid oid
+      @oids_entity_map[oid]
+    end
+
+  private
+    def table_oid table_name
+      connection_pool.with_connection do |conn|
+        # TBD
+        conn.exec(%Q(select oid from pg_class where relname = #{conn.quote(table_name)})).
+          getvalue(0,0).to_i        
+      end
+    end
+  end
+end

data/lib/flounder/engine.rb

@@ -0,0 +1,25 @@
+module Flounder
+  class Engine
+    attr_reader :connection_pool
+    attr_reader :connection
+
+    def initialize connection_pool
+      @connection_pool = connection_pool
+      # TBD This connection is currently never returned to the pool, Arel 
+      # is designed that way. 
+      @connection = connection_pool.checkout
+    end
+
+    def exec *args, &block
+      connection_pool.with_connection do |conn|
+        conn.exec *args, &block
+      end
+    end
+
+    # ---------------------------------------------------- official Engine iface
+
+    def connection_pool
+      @connection_pool
+    end
+  end
+end

data/lib/flounder/entity.rb

@@ -0,0 +1,57 @@
+module Flounder
+  class Entity
+    # Domain this entity is defined in.
+    attr_reader :domain
+
+    # Name of the entity in plural form. 
+    attr_reader :name
+    # Name of the entity in singular form. 
+    attr_reader :singular
+
+    # Arel table that underlies this entity. 
+    attr_reader :table
+    # 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
+      @table = Arel::Table.new(table_name)
+    end
+
+    # Returns a field of the entity.
+    #
+    def [] name
+      Field.new(self, name, table[name])
+    end
+
+    def belongs_to entity, fk
+    end
+
+    def to_s
+      "entity(#{name}/#{table_name})"
+    end
+
+    # Query initiators
+    [:where, :join, :outer_join, :project].each do |name|
+      define_method name do |*args|
+        Query.new(domain, self).tap { |q| q.send(name, *args) }
+      end
+    end
+
+    # Kickers
+    [:first, :all, :size].each do |name|
+      define_method name do |*args|
+        q = Query.new(domain, self)
+        q.send(name, *args)
+      end
+    end
+
+    def each &block
+      all.each &block
+    end
+    include Enumerable
+  end
+end

data/lib/flounder/field.rb

@@ -0,0 +1,24 @@
+module Flounder
+  class Field
+    attr_reader :entity
+    attr_reader :arel_field
+    attr_reader :name
+
+    def initialize entity, name, arel_field
+      @entity = entity
+      @name = name
+      @arel_field = arel_field
+    end
+
+    def fully_qualified_name
+      # TBD quoting? Demeter?
+      entity.domain.connection_pool.with_connection do |conn|
+        table = conn.quote_table_name(entity.table_name)
+        column = conn.quote_column_name(name)
+        "#{table}.#{column}"
+      end
+    end
+
+    include SymbolExtensions
+  end
+end

data/lib/flounder/postgres_utils.rb

@@ -0,0 +1,76 @@
+
+require 'time'
+require 'date'
+
+module Flounder
+  module PostgresUtils
+    OID_INTEGER = 23
+    OID_SMALLINT = 21
+    OID_VARCHAR = 1043
+    OID_BOOLEAN = 16
+    OID_TIMESTAMP = 1114
+    OID_DATE = 1082
+    OID_TIME = 1083
+
+    def typecast type_oid, value
+      return nil unless value
+      case type_oid
+        when OID_TIMESTAMP
+          value && DateTime.parse(value)
+        when OID_DATE
+          value && Date.parse(value)
+        when OID_TIME
+          value && Time.parse(value)
+        when OID_INTEGER, OID_SMALLINT
+          value.to_i
+        when OID_BOOLEAN
+          value == 't'
+      else
+        value
+      end
+    end
+
+    def type_oid_to_sym oid
+      case oid
+        when OID_TIMESTAMP
+          :datetime
+        when OID_DATE
+          :date
+        when OID_TIME
+          :time
+        when OID_INTEGER, OID_SMALLINT
+          :integer
+        when OID_VARCHAR
+          :string
+        when OID_BOOLEAN
+          :boolean
+      else
+        nil
+      end
+    end
+    
+    def each_field from_entity, result, row_idx
+      domain = from_entity.domain
+
+      result.nfields.times do |field_idx|
+        table_oid = result.ftable(field_idx)
+        entity = domain.by_oid(table_oid)
+
+        yield entity, 
+          result.fname(field_idx),
+          result.getvalue(row_idx, field_idx),
+          result.ftype(field_idx), 
+          result.fformat(field_idx) == 1, 
+          field_idx 
+      end
+    end
+
+    # Helper function for debugging
+    def type_name ftype, fmod
+      pg.
+        exec( "SELECT format_type($1,$2)", 
+          [ftype, fmod] ).
+        getvalue( 0, 0 )
+    end
+  end
+end

data/lib/flounder/query.rb

@@ -0,0 +1,195 @@
+module Flounder
+  class Query
+    # 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
+    
+
+    def initialize domain, from_entity
+      @domain = domain
+      @from_entity = from_entity
+      @engine = Engine.new(from_entity.domain.connection_pool)
+      @manager = Arel::SelectManager.new(@engine)
+      @has_projection = false
+
+      manager.from from_entity.table
+    end
+
+    def where conditions={}
+      conditions.each do |k, v|
+        manager.where(transform_hash_condition(k, v))
+      end
+      self
+    end    
+
+    def join entity, join_node=Arel::Nodes::InnerJoin
+      @last_join = entity
+
+      manager.join(entity.table, join_node)
+      self
+    end
+    def outer_join entity
+      join(entity, Arel::Nodes::OuterJoin)
+    end
+    def on join_conditions
+      join_conditions.each do |k, v|
+        manager.on(
+          transform_hash_condition(k, join_field(v)))
+      end
+      self
+    end
+    def anchor
+      @from_entity = @last_join
+      self
+    end
+
+    def project *field_list
+      # TBD: Clean up
+      @has_projection = true
+      manager.project *map_to_arel(field_list)
+      self
+    end
+
+    def group_by *field_list
+      manager.group *map_to_arel(field_list)
+      self
+    end
+
+    # 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
+      @last_join[name]
+    end
+
+    def order *field_list
+      field_list.each do |field|
+        field = from_entity[field] unless field.kind_of?(Field)
+        manager.order field.fully_qualified_name
+      end
+      self
+    end
+
+    # Kickers
+    def to_sql
+      prepare_kick
+
+      manager.to_sql.tap { |sql| 
+        domain.log_sql(sql) }
+    end
+    alias sql to_sql
+
+    def each &block
+      all.each(&block)
+    end
+    include Enumerable
+
+    def first
+      manager.take(1)
+
+      all.first
+    end
+    def size
+      manager.projections = []
+      project 'count(*) as count'
+
+      all.first.count
+    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] = objectify_result_row(result, row_idx)
+        end
+      end
+
+      all
+    end
+
+  private
+  
+    def map_to_arel field_list
+      field_list.map { |field| 
+        if field.kind_of? Field
+          field.arel_field
+        else
+          field
+        end
+      }
+    end
+
+    def prepare_kick
+      unless @has_projection
+        manager.project Arel.star
+      end
+    end
+
+    # Transforms things like :a => 1 into field('a').eq(1).
+    #
+    def transform_hash_condition field, value
+      if value.kind_of? Field
+        value = value.arel_field
+      end
+
+      case field
+        when Symbol
+          condition_part(from_entity[field].arel_field, value)
+        when Flounder::Field
+          condition_part(field.arel_field, value)
+        when Flounder::SymbolExtensions::Modifier
+          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 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)
+      else
+        arel_field.send(kind, value)
+      end
+    end
+
+    # Turns row (a hash) into something that can be treated like an object. 
+    # Also performs type coercion. 
+    #
+    def objectify_result_row result, row_idx
+      obj = Hashie::Mash.new
+
+      engine.connection.each_field(from_entity, result, row_idx) do 
+        |entity, name, value, type_oid, binary, idx|
+        
+        # p [entity.name, name, type_oid, type_name(result, idx)]
+        typecast_value = engine.connection.typecast(type_oid, value)
+
+        if entity
+          obj[entity.singular] ||= {}
+          obj[entity.singular][name] = typecast_value
+        else
+          obj[name] = typecast_value
+        end
+      end
+
+      return obj
+    end
+  end # class
+end # module Flounder

data/lib/flounder/symbol_extensions.rb

@@ -0,0 +1,22 @@
+module Flounder
+  module SymbolExtensions
+    class Modifier < Struct.new(:sym, :kind)
+      def to_arel_field from_entity
+        af = case sym
+          when Symbol
+            from_entity[sym].arel_field
+          when Flounder::Field
+            sym.arel_field
+        else
+          fail "ASSERTION FAILURE: Unknown type in field.sym: #{field.sym.inspect}."
+        end
+      end
+    end
+
+    [:not_eq, :lt, :gt, :gteq, :lteq, :matches].each do |kind|
+      define_method kind do
+        Modifier.new(self, kind)
+      end
+    end
+  end
+end

data/lib/flounder.rb

@@ -0,0 +1,27 @@
+require 'pg'
+require 'arel'
+require 'hashie/mash'
+
+require 'flounder/symbol_extensions'
+
+require 'flounder/postgres_utils'
+require 'flounder/connection'
+require 'flounder/connection_pool'
+require 'flounder/domain'
+require 'flounder/engine'
+require 'flounder/entity'
+require 'flounder/field'
+require 'flounder/query'
+
+module Flounder
+module_function
+  def connect *args
+    ConnectionPool.new(args)
+  end
+
+  def domain connection, &block
+    Domain.new(connection).tap { |d| yield d if block_given? }
+  end
+end
+
+Symbol.send(:include, Flounder::SymbolExtensions)

data/qed/applique/ae.rb

@@ -0,0 +1 @@
+require 'ae'

data/qed/applique/ahrel.rb

@@ -0,0 +1 @@
+require 'flounder'

data/qed/flounder.sql

@@ -0,0 +1,41 @@
+-- Database fixture for these tests. Please improt into a database that 
+-- should also be called 'flounder'.
+
+DROP TABLE IF EXISTS "users" CASCADE;
+CREATE TABLE "users" (
+  "id" serial PRIMARY KEY,
+  "name" varchar(40) NOT NULL
+);
+
+BEGIN;
+INSERT INTO "users" (name) VALUES ('John Snow');
+COMMIT;
+
+DROP TABLE IF EXISTS "posts" CASCADE;
+CREATE TABLE "posts" (
+  "id" serial PRIMARY KEY,
+  "title" varchar(100) NOT NULL,
+  "text" text NOT NULL,
+  "user_id" int NOT NULL REFERENCES users("id")
+);
+
+BEGIN;
+INSERT INTO "posts" (title, text, user_id) VALUES (
+  'First Light', 'This is the first post in our test system.', '1');
+COMMIT;
+
+DROP TABLE IF EXISTS "comments" CASCADE;
+CREATE TABLE "comments" (
+  "id" serial PRIMARY KEY, 
+  "post_id" int NOT NULL REFERENCES posts("id"),
+  "text" text NOT NULL
+);
+
+BEGIN; 
+INSERT INTO "comments" (post_id, text) VALUES (1, 'A silly comment.'); 
+COMMIT; 
+
+-- import using
+--
+--    cat qed/flounder.sql | psql flounder
+--

data/qed/index.md

@@ -0,0 +1,105 @@
+
+Flounder is a simple layer between you and the database. It abstracts syntax details and removes the need for string manipulation and parsing, but it does not 'map to objects' in the traditional sense. It still returns objects from queries, though - and it certainly allows influencing the mapping, but the core of flounder is about making querying and manipulating the database look nice and be maintainable. Here are our guiding principles: 
+
+* DSL should be close to SQL; we're not imitating Enumerables. 
+* Not the multitude of chain methods, but the composability of these methods makes Flounders power. 
+
+# A simple Domain
+
+Here's our domain definition. In which - yes - you specify both singular and plural variants for each entity. Once. 
+
+~~~ruby  
+  connection = Flounder.connect(dbname: 'flounder')
+  domain = Flounder.domain(connection) do |dom|
+    dom.entity(:users, :user, 'users')
+    dom.entity(:posts, :post, 'posts')
+    dom.entity(:comments, :comment, 'comments')
+  end
+~~~
+
+Now very simple selects should work as expected.
+
+~~~ruby
+  sql = domain[:users].where(id: 1).sql
+  sql.assert == %Q(SELECT * FROM "users"  WHERE "users"."id" = 1)
+~~~
+
+The `domain[:users]` bit refers to a relation in the database and when you append another square bracket pair, you'll refer to a field in the database - everywhere, in all flounder clauses. 
+
+~~~ruby
+  domain[:users][:id].assert.kind_of? Flounder::Field
+~~~
+
+Also, several conditions work as one would expect from DataMapper. 
+
+~~~ruby
+  domain[:users].where(id: 1..10).sql.assert == 
+    %Q(SELECT * FROM "users"  WHERE "users"."id" BETWEEN 1 AND 10)
+
+  domain[:users].where(:id.lt => 10).sql.assert == 
+    "SELECT * FROM \"users\"  WHERE \"users\".\"id\" < 10"
+  domain[:users].where(:id.lteq => 10).sql.assert == 
+    "SELECT * FROM \"users\"  WHERE \"users\".\"id\" <= 10"
+  domain[:users].where(:id.gt => 10).sql.assert == 
+    "SELECT * FROM \"users\"  WHERE \"users\".\"id\" > 10"
+  domain[:users].where(:id.gteq => 10).sql.assert == 
+    "SELECT * FROM \"users\"  WHERE \"users\".\"id\" >= 10"
+  domain[:users].where(:id.not_eq => 10).sql.assert == 
+    "SELECT * FROM \"users\"  WHERE \"users\".\"id\" != 10"
+~~~
+
+Fields can be used fully qualified by going through the entity.
+
+~~~ruby
+  domain[:users].where(domain[:users][:id] => 10).
+    sql.assert == %Q(SELECT * FROM "users"  WHERE "users"."id" = 10)
+
+  domain[:users].where(domain[:users][:name].matches => 'a%').
+    sql.assert == %Q(SELECT * FROM "users"  WHERE "users"."name" LIKE 'a%')
+~~~
+
+# Some JOINs
+
+Here are some non-crazy joins that also work. 
+
+~~~ruby
+  sql = domain[:users].join(domain[:posts]).on(:id => :user_id).sql
+  sql.assert == %Q(SELECT * FROM "users" INNER JOIN "posts" ON "users"."id" = "posts"."user_id")
+
+  sql = domain[:users].outer_join(domain[:posts]).on(:id => :user_id).sql
+  sql.assert == %Q(SELECT * FROM "users" LEFT OUTER JOIN "posts" ON "users"."id" = "posts"."user_id")
+~~~
+
+Joining presents an interesting dilemma. There are two ways of joining things together, given three tables. The sequence A.B.C might mean to join A to B and C; it might also be interpreted to mean to join A to B and B to C. Here's how we solve this. 
+
+~~~ruby
+  domain[:users].
+    join(domain[:posts]).on(:id => :user_id).
+    join(domain[:comments]).on(:id => :post_id).
+      sql.assert == %Q(SELECT * FROM "users" INNER JOIN "posts" ON "users"."id" = "posts"."user_id" INNER JOIN "comments" ON "users"."id" = "comments"."post_id")
+~~~
+
+So just doing `A.B.C` will give you the first of the above possibilities. Here's how to achive the second effect. 
+
+~~~ruby
+  domain[:users].
+    join(domain[:posts]).on(:id => :user_id).anchor.
+    join(domain[:comments]).on(:id => :post_id).
+      sql.assert == %Q(SELECT * FROM "users" INNER JOIN "posts" ON "users"."id" = "posts"."user_id" INNER JOIN "comments" ON "posts"."id" = "comments"."post_id")
+~~~
+
+The call to `#anchor` anchors all further joins at that point. 
+
+# ORDER BY
+
+~~~ruby
+  domain[:users].where(id: 2013).order(domain[:users][:id]).
+    sql.assert == %Q(SELECT * FROM "users"  WHERE "users"."id" = 2013  ORDER BY "users"."id")
+~~~
+
+# Selective projection
+
+~~~ruby
+  domain[:users].where(id: 2013).project(domain[:users][:id]).
+    sql.assert == %Q(SELECT "users"."id" FROM "users"  WHERE "users"."id" = 2013)
+~~~

data/qed/selects.md

@@ -0,0 +1,42 @@
+
+
+A simple domain definition.
+
+~~~ruby  
+  connection = Flounder.connect(dbname: 'flounder')
+  domain = Flounder.domain(connection) do |dom|
+    dom.entity(:users, :user, 'users')
+  end
+
+  # Enable this line if you want to see all statements executed.
+  # domain.logger = Logger.new(STDOUT)
+~~~
+
+And a simple use case. 
+
+~~~ruby
+  s2013 = domain[:users].where(:id => 1).first
+  s2013.user.id.assert == 1
+~~~
+
+If we want to see all records, we use the `all` kicker, which has some synonyms. You best discover those by treating the domain entity as an array.  
+
+~~~ruby
+  users = domain[:users].all 
+  users.size.assert == 1
+  users.assert.kind_of? Array
+
+  domain[:users].map(&:id).assert == users.map(&:id)
+~~~
+
+# Treat it like an array
+
+You can treat the entities and the queries like an array. 
+
+~~~ruby
+  entity = domain[:users]
+  entity.size.assert > 0
+
+  query = entity.where(:id => :id)
+  query.size.assert == entity.size
+~~~

metadata

@@ -0,0 +1,138 @@
+--- !ruby/object:Gem::Specification
+name: flounder
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Kaspar Schiess
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-07-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: arel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: 5.0.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: 5.0.1
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: '0.17'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: '0.17'
+- !ruby/object:Gem::Dependency
+  name: hashie
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: connection_pool
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+description: 
+email: kaspar.schiess@technologyastronauts.ch
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- Gemfile.lock
+- HACKING
+- LICENSE
+- README
+- flounder.gemspec
+- lib/flounder.rb
+- lib/flounder/connection.rb
+- lib/flounder/connection_pool.rb
+- lib/flounder/domain.rb
+- lib/flounder/engine.rb
+- lib/flounder/entity.rb
+- lib/flounder/field.rb
+- lib/flounder/postgres_utils.rb
+- lib/flounder/query.rb
+- lib/flounder/symbol_extensions.rb
+- qed/applique/ae.rb
+- qed/applique/ahrel.rb
+- qed/flounder.sql
+- qed/index.md
+- qed/selects.md
+homepage: https://bitbucket.org/technologyastronauts/laboratory_flounder
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Flounder is a way to write SQL simply in Ruby. It deals with everything BUT
+  object relational mapping.
+test_files:
+- qed/applique/ae.rb
+- qed/applique/ahrel.rb
+- qed/flounder.sql
+- qed/index.md
+- qed/selects.md
+has_rdoc: