rom-sql 0.7.0 → 0.8.0

data/lib/rom/sql/qualified_attribute.rb

@@ -0,0 +1,53 @@
+require 'rom/support/cache'
+
+module ROM
+  module SQL
+    # Used as a pair table name + field name.
+    # Similar to Sequel::SQL::QualifiedIdentifier but we don't want
+    # Sequel types to leak into ROM
+    #
+    # @api private
+    class QualifiedAttribute
+      include Dry::Equalizer(:dataset, :attribute)
+
+      extend Cache
+
+      # Dataset (table) name
+      #
+      # @api private
+      attr_reader :dataset
+
+      # Attribute (field, column) name
+      #
+      # @api private
+      attr_reader :attribute
+
+      # @api private
+      def self.[](*args)
+        fetch_or_store(args) { new(*args) }
+      end
+
+      # @api private
+      def initialize(dataset, attribute)
+        @dataset = dataset
+        @attribute = attribute
+      end
+
+      # Used by Sequel for building SQL statements
+      #
+      # @api private
+      def sql_literal_append(ds, sql)
+        ds.qualified_identifier_sql_append(sql, dataset, attribute)
+      end
+
+      # Convinient interface for attribute names
+      #
+      # @return [Symbol]
+      #
+      # @api private
+      def to_sym
+        attribute
+      end
+    end
+  end
+end

data/lib/rom/sql/relation.rb

@@ -1,4 +1,7 @@
 require 'rom/sql/header'
+require 'rom/sql/types'
+
+require 'rom/sql/schema'
 
 require 'rom/sql/relation/reading'
 require 'rom/sql/relation/writing'
@@ -9,11 +12,17 @@ require 'rom/plugins/relation/sql/base_view'
 require 'rom/plugins/relation/sql/auto_combine'
 require 'rom/plugins/relation/sql/auto_wrap'
 
+require 'rom/support/deprecations'
+require 'rom/support/constants'
+
 module ROM
   module SQL
     # Sequel-specific relation extensions
     #
+    # @api public
     class Relation < ROM::Relation
+      include SQL
+
       adapter :sql
 
       use :key_inference
@@ -25,14 +34,6 @@ module ROM
       include Writing
       include Reading
 
-      # @attr_reader [Header] header Internal lazy-initialized header
-      attr_reader :header
-
-      # Name of the table used in FROM clause
-      #
-      # @attr_reader [Symbol] table
-      attr_reader :table
-
       # Set default dataset for a relation sub-class
       #
       # @api private
@@ -40,38 +41,74 @@ module ROM
         super
 
         klass.class_eval do
+          schema_dsl SQL::Schema::DSL
+          schema_inferrer ROM::SQL::Schema::Inferrer
+
           dataset do
             table = opts[:from].first
 
             if db.table_exists?(table)
-              # quick fix for dbs w/o primary_key inference
-              #
-              # TODO: add a way of setting a pk explicitly on a relation
-              pk =
-                if db.respond_to?(:primary_key)
-                  Array(db.primary_key(table))
-                else
-                  [:id]
-                end.map { |name| :"#{table}__#{name}" }
-
-                select(*columns).order(*pk)
+              pk_header = klass.primary_key_header(db, table)
+              select(*columns).order(*pk_header.qualified)
             else
               self
             end
           end
+
+          # @!method by_pk(pk)
+          #   Return a relation restricted by its primary key
+          #   @param [Object] pk The primary key value
+          #   @return [SQL::Relation]
+          #   @api public
+          view(:by_pk, attributes[:base]) do |pk|
+            where(primary_key => pk)
+          end
         end
       end
 
+      # @api private
+      def self.associations
+        schema.associations
+      end
+
+      # @api private
+      def self.primary_key_header(db, table)
+        names =
+          if schema
+            schema.primary_key_names
+          elsif db.respond_to?(:primary_key)
+            Array(db.primary_key(table))
+          else
+            [:id]
+          end
+        Header.new(names, table)
+      end
+
+      # Set primary key
+      #
+      # @deprecated
+      #
+      # @api public
       def self.primary_key(value)
+        Deprecations.announce(
+          :primary_key, "use schema definition to configure primary key"
+        )
         option :primary_key, reader: true, default: value
       end
 
-      primary_key :id
+      option :primary_key, reader: true, default: -> rel {
+        rel.schema? ? rel.schema.primary_key_name : :id
+      }
 
+      # Return table name from relation's sql statement
+      #
+      # This value is used by `header` for prefixing column names
+      #
+      # @return [Symbol]
+      #
       # @api private
-      def initialize(dataset, registry = {})
-        super
-        @table = dataset.opts[:from].first
+      def table
+        @table ||= dataset.opts[:from].first
       end
 
       # Return a header for this relation
@@ -80,7 +117,7 @@ module ROM
       #
       # @api private
       def header
-        @header ||= Header.new(dataset.opts[:select] || dataset.columns, table)
+        @header ||= Header.new(selected_columns, table)
       end
 
       # Return raw column names
@@ -89,7 +126,21 @@ module ROM
       #
       # @api private
       def columns
-        dataset.columns
+        @columns ||= dataset.columns
+      end
+
+      protected
+
+      # Return a list of columns from *the sql select* statement or default to
+      # dataset columns
+      #
+      # This is used to construct relation's header
+      #
+      # @return [Array<Symbol>]
+      #
+      # @api private
+      def selected_columns
+        @selected_columns ||= dataset.opts.fetch(:select, columns)
       end
     end
   end

data/lib/rom/sql/relation/reading.rb

@@ -1,11 +1,30 @@
 module ROM
   module SQL
     class Relation < ROM::Relation
+      # Query API for SQL::Relation
+      #
+      # @api public
       module Reading
+        # Fetch a tuple identified by the pk
+        #
+        # @example
+        #   users.fetch(1)
+        #   # {:id => 1, name: "Jane"}
+        #
+        # @return [Relation]
+        #
+        # @raise [ROM::TupleCountMismatchError] When 0 or more than 1 tuples were found
+        #
+        # @api public
+        def fetch(pk)
+          by_pk(pk).one!
+        end
+
         # Return relation count
         #
         # @example
-        #   users.count # => 12
+        #   users.count
+        #   # => 12
         #
         # @return [Relation]
         #
@@ -18,8 +37,9 @@ module ROM
         #
         # @example
         #   users.first
+        #   # {:id => 1, :name => "Jane"}
         #
-        # @return [Relation]
+        # @return [Hash]
         #
         # @api public
         def first
@@ -30,8 +50,9 @@ module ROM
         #
         # @example
         #   users.last
+        #   # {:id => 2, :name => "Joe"}
         #
-        # @return [Relation]
+        # @return [Hash]
         #
         # @api public
         def last
@@ -43,7 +64,8 @@ module ROM
         # This method is intended to be used internally within a relation object
         #
         # @example
-        #   rom.relation(:users) { |r| r.prefix(:user) }
+        #   users.prefix(:user).to_a
+        #   # {:user_id => 1, :user_name => "Jane"}
         #
         # @param [Symbol] name The prefix
         #
@@ -59,7 +81,7 @@ module ROM
         # This method is intended to be used internally within a relation object
         #
         # @example
-        #   rom.relation(:users) { |r| r.qualified }
+        #   users.qualified
         #
         # @return [Relation]
         #
@@ -72,39 +94,49 @@ module ROM
         #
         # This method is intended to be used internally within a relation object
         #
-        # @return [Relation]
+        # @example
+        #   users.qualified_columns
+        #   # [:users__id, :users__name]
+        #
+        # @return [Array<Symbol>]
         #
         # @api public
         def qualified_columns
           header.qualified.to_a
         end
 
-        # Return if a restricted relation has 0 tuples
+        # Map tuples from the relation
         #
         # @example
-        #   users.unique?(email: 'jane@doe.org') # true
+        #   users.map { |user| user[:id] }
+        #   # [1, 2, 3]
         #
-        #   users.insert(email: 'jane@doe.org')
+        #   users.map(:id).to_a
+        #   # [1, 2, 3]
         #
-        #   users.unique?(email: 'jane@doe.org') # false
-        #
-        # @param [Hash] criteria hash for the where clause
-        #
-        # @return [Relation]
+        # @param [Symbol] key An optional name of the key for extracting values
+        #                     from tuples
         #
         # @api public
-        def unique?(criteria)
-          where(criteria).count.zero?
+        def map(key = nil, &block)
+          if key
+            dataset.map(key, &block)
+          else
+            dataset.map(&block)
+          end
         end
 
-        # Map tuples from the relation
+        # Pluck values from a specific column
         #
         # @example
-        #   users.map { |user| ... }
+        #   users.pluck(:id)
+        #   # [1, 2, 3]
+        #
+        # @return [Array]
         #
         # @api public
-        def map(&block)
-          dataset.map(&block)
+        def pluck(name)
+          map(name)
         end
 
         # Project a relation
@@ -112,9 +144,9 @@ module ROM
         # This method is intended to be used internally within a relation object
         #
         # @example
-        #   rom.relation(:users) { |r| r.project(:id, :name) }
+        #   users.project(:id, :name) }
         #
-        # @param [Symbol] names A list of symbol column names
+        # @param [Symbol] *names A list of symbol column names
         #
         # @return [Relation]
         #
@@ -128,9 +160,10 @@ module ROM
         # This method is intended to be used internally within a relation object
         #
         # @example
-        #   rom.relation(:users) { |r| r.rename(name: :user_name) }
+        #   users.rename(name: :user_name).first
+        #   # {:id => 1, :user_name => "Jane" }
         #
-        # @param [Hash] options A name => new_name map
+        # @param [Hash<Symbol=>Symbol>] options A name => new_name map
         #
         # @return [Relation]
         #
@@ -142,7 +175,8 @@ module ROM
         # Select specific columns for select clause
         #
         # @example
-        #   users.select(:id, :name)
+        #   users.select(:id, :name).first
+        #   # {:id => 1, :name => "Jane" }
         #
         # @return [Relation]
         #
@@ -155,6 +189,9 @@ module ROM
         #
         # @example
         #   users.select(:id, :name).select_append(:email)
+        #   # {:id => 1, :name => "Jane", :email => "jane@doe.org"}
+        #
+        # @param [Array<Symbol>] *args A list with column names
         #
         # @return [Relation]
         #
@@ -168,6 +205,8 @@ module ROM
         # @example
         #   users.distinct(:country)
         #
+        # @param [Array<Symbol>] *args A list with column names
+        #
         # @return [Relation]
         #
         # @api public
@@ -180,7 +219,9 @@ module ROM
         # @example
         #   users.sum(:age)
         #
-        # @return Number
+        # @param [Array<Symbol>] *args A list with column names
+        #
+        # @return [Integer]
         #
         # @api public
         def sum(*args)
@@ -192,6 +233,8 @@ module ROM
         # @example
         #   users.min(:age)
         #
+        # @param [Array<Symbol>] *args A list with column names
+        #
         # @return Number
         #
         # @api public
@@ -204,6 +247,8 @@ module ROM
         # @example
         #   users.max(:age)
         #
+        # @param [Array<Symbol>] *args A list with column names
+        #
         # @return Number
         #
         # @api public
@@ -216,6 +261,8 @@ module ROM
         # @example
         #   users.avg(:age)
         #
+        # @param [Array<Symbol>] *args A list with column names
+        #
         # @return Number
         #
         # @api public
@@ -225,11 +272,20 @@ module ROM
 
         # Restrict a relation to match criteria
         #
+        # If block is passed it'll be executed in the context of a condition
+        # builder object.
+        #
         # @example
         #   users.where(name: 'Jane')
         #
+        #   users.where { age >= 18 }
+        #
+        # @param [Hash] *args An optional hash with conditions for WHERE clause
+        #
         # @return [Relation]
         #
+        # @see http://sequel.jeremyevans.net/rdoc/files/doc/dataset_filtering_rdoc.html
+        #
         # @api public
         def where(*args, &block)
           __new__(dataset.__send__(__method__, *args, &block))
@@ -240,6 +296,8 @@ module ROM
         # @example
         #   users.exclude(name: 'Jane')
         #
+        # @param [Hash] *args A hash with conditions for exclusion
+        #
         # @return [Relation]
         #
         # @api public
@@ -247,7 +305,8 @@ module ROM
           __new__(dataset.__send__(__method__, *args, &block))
         end
 
-        # Inverts a request
+        # Inverts the current WHERE and HAVING clauses. If there is neither a
+        # WHERE or HAVING clause, adds a WHERE clause that is always false.
         #
         # @example
         #   users.exclude(name: 'Jane').invert
@@ -258,8 +317,8 @@ module ROM
         # @return [Relation]
         #
         # @api public
-        def invert(*args, &block)
-          __new__(dataset.__send__(__method__, *args, &block))
+        def invert
+          __new__(dataset.invert)
         end
 
         # Set order for the relation
@@ -267,6 +326,8 @@ module ROM
         # @example
         #   users.order(:name)
         #
+        # @param [Array<Symbol>] *args A list with column names
+        #
         # @return [Relation]
         #
         # @api public
@@ -291,6 +352,11 @@ module ROM
         # @example
         #   users.limit(1)
         #
+        #   users.limit(10, 2)
+        #
+        # @param [Integer] limit The limit value
+        # @param [Integer] offset An optional offset
+        #
         # @return [Relation]
         #
         # @api public
@@ -303,6 +369,8 @@ module ROM
         # @example
         #   users.limit(10).offset(2)
         #
+        # @param [Integer] num The offset value
+        #
         # @return [Relation]
         #
         # @api public
@@ -310,7 +378,10 @@ module ROM
           __new__(dataset.__send__(__method__, *args, &block))
         end
 
-        # Join other relation using inner join
+        # Join with another relation using INNER JOIN
+        #
+        # @example
+        #   users.inner_join(:tasks, id: :user_id)
         #
         # @param [Symbol] relation name
         # @param [Hash] join keys
@@ -322,7 +393,10 @@ module ROM
           __new__(dataset.__send__(__method__, *args, &block))
         end
 
-        # Join other relation using left outer join
+        # Join other relation using LEFT OUTER JOIN
+        #
+        # @example
+        #   users.left_join(:tasks, id: :user_id)
         #
         # @param [Symbol] relation name
         # @param [Hash] join keys
@@ -339,6 +413,8 @@ module ROM
         # @example
         #   tasks.group(:user_id)
         #
+        # @param [Array<Symbol>] *args A list of column names
+        #
         # @return [Relation]
         #
         # @api public
@@ -352,6 +428,8 @@ module ROM
         #   tasks.group_and_count(:user_id)
         #   # => [{ user_id: 1, count: 2 }, { user_id: 2, count: 3 }]
         #
+        # @param [Array<Symbol>] *args A list of column names
+        #
         # @return [Relation]
         #
         # @api public
@@ -365,6 +443,8 @@ module ROM
         #   tasks.select_group(:user_id)
         #   # => [{ user_id: 1 }, { user_id: 2 }]
         #
+        # @param [Array<Symbol>] *args A list of column names
+        #
         # @return [Relation]
         #
         # @api public
@@ -374,17 +454,40 @@ module ROM
 
         # Adds a UNION clause for relation dataset using second relation dataset
         #
-        # @param [Relation] relation object
-        #
         # @example
         #   users.where(id: 1).union(users.where(id: 2))
         #   # => [{ id: 1, name: 'Piotr' }, { id: 2, name: 'Jane' }]
         #
+        # @param [Relation] relation Another relation
+        #
+        # @param [Hash] options Options for union
+        # @option options [Symbol] :alias Use the given value as the #from_self alias
+        # @option options [TrueClass, FalseClass] :all Set to true to use UNION ALL instead of UNION, so duplicate rows can occur
+        # @option options [TrueClass, FalseClass] :from_self Set to false to not wrap the returned dataset in a #from_self, use with care.
+        #
         # @return [Relation]
         #
         # @api public
-        def union(relation, *args, &block)
-          __new__(dataset.__send__(__method__, relation.dataset, *args, &block))
+        def union(relation, options = EMPTY_HASH, &block)
+          __new__(dataset.__send__(__method__, relation.dataset, options, &block))
+        end
+
+        # Return if a restricted relation has 0 tuples
+        #
+        # @example
+        #   users.unique?(email: 'jane@doe.org') # true
+        #
+        #   users.insert(email: 'jane@doe.org')
+        #
+        #   users.unique?(email: 'jane@doe.org') # false
+        #
+        # @param [Hash] criteria The condition hash for  WHERE clause
+        #
+        # @return [TrueClass, FalseClass]
+        #
+        # @api public
+        def unique?(criteria)
+          where(criteria).count.zero?
         end
       end
     end