rom-sql 2.0.0.beta3 → 2.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3c40812f8e5e3a90dbb8a24608845b06a69f2e7c
-  data.tar.gz: 0675140e980842b9bfe70aae46826b7e1c4ccb4c
+  metadata.gz: 6220c48972476b2eb922c0520c59eab29768cd3d
+  data.tar.gz: 4cc6885f74372fd464ffe85600350c6c64ba29ba
 SHA512:
-  metadata.gz: 872afeaa13eb89ce9bb8606b5dc88f599d01169201464b66f746784baef1dd297fb2cfdf4f1da5f3772e54427d8a19168bd6266444b969b5cf5dbac4f781efec
-  data.tar.gz: b344cad962d4db308295b01c37ec7efdbcfd41d30c7aeeb51cae997188238fa73cc4273c07b12a088c283fbc25035d1afdc63b1bd7734711b70344b2cefef72c
+  metadata.gz: 44814022262e8f88ae6e7def5049f3e18790c71bab8fcd5f0c1bc1a06934ebac57715f511ac0929ad276055d185ab229e29e3312c8c38f4269d2eaf9273d22d7
+  data.tar.gz: 4e37a732f6291c6e37349262dccda67842441c3c34ead4076c9ca8a6ca8ed7d54d3c5bc6da92e76793bf2ad4714102a9406a6b6f2314d93860e872d565031618

data/CHANGELOG.md

@@ -66,6 +66,13 @@
     employees.select { [dep_no, salary, int::avg(salary).over(partition: dep_no, order: id).as(:avg_salary)] }
   ```
 
+* Function result can be negated, also `ROM::SQL::Function#not` was added (flash-gordon)
+
+  ```ruby
+     users.where { !lower(name).is('John') }
+     users.where { lower(name).not('John') }
+  ```
+
 
 ### Changed
 
@@ -73,6 +80,7 @@
 * [BREAKING] `Associates` command plugin requires associations now (solnic)
 * [BREAKING] `Command#transaction` is gone in favor of `Relation#transaction` (solnic)
 * [BREAKING] `PG::JSONArray`, `PG::JSONBArray`, `PG::JSONHash`, and `PG::JSONBHash` types were dropped, use `PG::JSON` and `PG::JSONB` instead (flash-gordon)
+* [BREAKING] The `pg_hstore` extension now doesn't get loaded automatically, use the `:extension` option to load it on config initialization (flash-gordon)
 * `ManyToOne` no longer uses a join (solnic)
 * `AutoCombine` and `AutoWrap` plugins were removed as this functionality is provided by core API (solnic)
 * Foreign keys are indexed by default (flash-gordon)
@@ -84,6 +92,7 @@
 * Self-ref associations work correctly with custom FKs (solnic)
 * Aliased associations with custom FKs work correctly (solnic)
 * Defining a custom dataset block no longer prevents default views like `by_pk` to be defined (solnic)
+* `Relation#group` uses canonical schema now (solnic)
 
 [Compare v1.3.3...master](https://github.com/rom-rb/rom-sql/compare/v1.3.3...master)
 

data/lib/rom/plugins/relation/sql/auto_restrictions.rb

@@ -36,6 +36,7 @@ module ROM
             methods.each { |meth| relation.auto_curry(meth) }
           end
 
+          # @api private
           def self.restriction_methods(schema)
             mod = Module.new
 

data/lib/rom/plugins/relation/sql/postgres/explain.rb

@@ -3,6 +3,8 @@ module ROM
     module Relation
       module SQL
         module Postgres
+          # PG-specific extensions which adds `Relation#explain` method
+          #
           # @api public
           module Explain
             # Show the execution plan

data/lib/rom/sql/attribute.rb

@@ -77,7 +77,7 @@ module ROM
       # Whenever you join two schemas, the right schema's attribute
       # will be marked as joined using this method
       #
-      # @return [SQL::Attribute]
+      # @return [SQL::Attribute] Original attribute marked as joined
       #
       # @api public
       def joined
@@ -168,6 +168,13 @@ module ROM
         self =~ other
       end
 
+      # Return a new attribute with an equality expression
+      #
+      # @example
+      #   users.where { email =~ 1 }
+      #
+      # @return [Attribute]
+      #
       # @api public
       def =~(other)
         meta(sql_expr: sql_expr =~ binary_operation_arg(other))
@@ -214,7 +221,7 @@ module ROM
       #   users.where { id.in(1, 2, 3) }
       #   users.where(users[:id].in(1, 2, 3))
       #
-      # @param [Array<Object>] *args A range or a list of values for an inclusion check
+      # @param [Array<Object>] args A range or a list of values for an inclusion check
       #
       # @api public
       def in(*args)
@@ -260,7 +267,7 @@ module ROM
 
       # Sequel calls this method to coerce an attribute into SQL string
       #
-      # @param [Sequel::Dataset]
+      # @param [Sequel::Dataset] ds
       #
       # @api private
       def sql_literal(ds)

data/lib/rom/sql/commands/error_wrapper.rb

@@ -7,6 +7,10 @@ module ROM
       module ErrorWrapper
         # Handle Sequel errors and re-raise ROM-specific errors
         #
+        # @return [Hash, Array<Hash>]
+        #
+        # @raise SQL::Error
+        #
         # @api public
         def call(*args)
           super

data/lib/rom/sql/dsl.rb

@@ -21,6 +21,17 @@ module ROM
         end
       end
 
+      # Return a string literal that will be used directly in an ORDER clause
+      #
+      # @param [String] value
+      #
+      # @return [Sequel::LiteralString]
+      #
+      # @api public
+      def `(value)
+        ::Sequel.lit(value)
+      end
+
       # @api private
       def respond_to_missing?(name, include_private = false)
         super || schema.key?(name)

data/lib/rom/sql/extensions/postgres/types/array.rb

@@ -98,7 +98,7 @@ module ROM
         #     #   Translates to an `array_to_string` call
         #     #
         #     #   @param [Object] delimiter
-        #     #   @param [Object] null
+        #     #   @param [Object] null_repr
         #     #
         #     #   @return [SQL::Attribute<Types::String>]
         #     #

data/lib/rom/sql/extensions/sqlite/type_builder.rb

@@ -4,6 +4,7 @@ module ROM
       class TypeBuilder < Schema::TypeBuilder
         NO_TYPE = EMPTY_STRING
 
+        # @api private
         def map_type(_, db_type, **_kw)
           if db_type.eql?(NO_TYPE)
             ROM::SQL::Types::SQLite::Any

data/lib/rom/sql/function.rb

@@ -2,6 +2,8 @@ require 'rom/attribute'
 
 module ROM
   module SQL
+    # Specialized attribute type for defining SQL functions
+    #
     # @api public
     class Function < ROM::Attribute
       class << self
@@ -49,6 +51,8 @@ module ROM
         meta[:alias] || super
       end
 
+      # @see Attribute#qualified
+      #
       # @api private
       def qualified(table_alias = nil)
         meta(
@@ -56,9 +60,20 @@ module ROM
         )
       end
 
-      # @api private
+      # @see ROM::SQL::Attribute#is
+      #
+      # @api public
       def is(other)
-        ::Sequel::SQL::BooleanExpression.new(:'=', func, other)
+        ::ROM::SQL::Attribute[::ROM::SQL::Types::Bool].meta(
+          sql_expr: ::Sequel::SQL::BooleanExpression.new(:'=', func, other)
+        )
+      end
+
+      # @see ROM::SQL::Attribute#not
+      #
+      # @api public
+      def not(other)
+        !is(other)
       end
 
       # Add an OVER clause making a window function call

data/lib/rom/sql/gateway.rb

@@ -21,7 +21,7 @@ module ROM
       adapter :sql
 
       CONNECTION_EXTENSIONS = {
-        postgres: %i(pg_array pg_json pg_enum pg_hstore)
+        postgres: %i(pg_array pg_json pg_enum)
       }.freeze
 
       # @!attribute [r] logger

data/lib/rom/sql/migration.rb

@@ -47,8 +47,9 @@ module ROM
       #     end
       #   end
       #
-      # @param [ROM::Container] container The container instance used for accessing gateways
-      # @param [Symbol] gateway The gateway name, :default by default
+      # @overload migration(container, gateway)
+      #   @param [ROM::Container] container The container instance used for accessing gateways
+      #   @param [Symbol] gateway The gateway name, :default by default
       #
       # @api public
       def migration(*args, &block)

data/lib/rom/sql/plugin/associates.rb

@@ -10,6 +10,7 @@ module ROM
         class AssociateOptions
           attr_reader :name, :assoc, :opts
 
+          # @api private
           def initialize(name, relation, opts)
             @name = name
             @assoc = relation.associations[name]
@@ -42,6 +43,7 @@ module ROM
           super
         end
 
+        # @api public
         module ClassMethods
           # @see ROM::Command::ClassInterface.build
           #
@@ -134,6 +136,12 @@ module ROM
             result_type == :one ? output_tuples[0] : output_tuples
           end
 
+          # Return a new command with the provided association
+          #
+          # @param [Symbol, Relation::Name] name The name of the association
+          #
+          # @return [Command]
+          #
           # @api public
           def with_association(name, opts = EMPTY_HASH)
             self.class.build(

data/lib/rom/sql/plugin/pagination.rb

@@ -3,34 +3,76 @@ require 'rom/initializer'
 module ROM
   module SQL
     module Plugin
+      # Pagination plugin for Relations
+      #
+      # @api public
       module Pagination
+        # Pager object provides the underlying pagination API for relations
+        #
+        # @api public
         class Pager
           extend Initializer
           include Dry::Equalizer(:dataset, :options)
 
+          # @!attribute [r] dataset
+          #   @return [Sequel::Dataset] Relation's dataset
           param :dataset
 
+          # @!attribute [r] current_page
+          #   @return [Integer] Current page number
           option :current_page, default: -> { 1 }
+
+          # @!attribute [r] per_page
+          #   @return [Integer] Current per-page number
           option :per_page
 
+          # Return next page number
+          #
+          # @example
+          #   users.page(2).pager.next_page
+          #   # => 3
+          #
+          # @return [Integer]
+          #
+          # @api public
           def next_page
             num = current_page + 1
             num if total_pages >= num
           end
 
+          # Return previous page number
+          #
+          # @example
+          #   users.page(2).pager.prev_page
+          #   # => 1
+          #
+          # @return [Integer]
+          #
+          # @api public
           def prev_page
             num = current_page - 1
             num if num > 0
           end
 
+          # Return total number of tuples
+          #
+          # @return [Integer]
+          #
+          # @api public
           def total
             dataset.unlimited.count
           end
 
+          # Return total number of pages
+          #
+          # @return [Integer]
+          #
+          # @api public
           def total_pages
             (total / per_page.to_f).ceil
           end
 
+          # @api private
           def at(dataset, current_page, per_page = self.per_page)
             current_page = current_page.to_i
             per_page = per_page.to_i
@@ -44,6 +86,7 @@ module ROM
           alias_method :limit_value, :per_page
         end
 
+        # @api private
         def self.included(klass)
           super
 
@@ -59,9 +102,8 @@ module ROM
         # Paginate a relation
         #
         # @example
-        #   rom.relations[:users].class.per_page(10)
-        #   rom.relations[:users].page(1)
-        #   rom.relations[:users].pager # => info about pagination
+        #   users.page(1)
+        #   users.pager # => info about pagination
         #
         # @return [Relation]
         #
@@ -74,7 +116,9 @@ module ROM
         # Set limit for pagination
         #
         # @example
-        #   rom.relations[:users].page(2).per_page(10)
+        #   users.per_page(10).page(2)
+        #
+        # @return [Relation]
         #
         # @api public
         def per_page(num)

data/lib/rom/sql/plugin/timestamps.rb

@@ -38,11 +38,11 @@ module ROM
           #   result = create_user.call
           #   result[:created_at]  #=> Time.now.utc
           #
-          # @param [Symbol] name of the attribute to set
+          # @param [Array<Symbol>] names A list of attribute names
           #
           # @api public
-          def timestamps(*args)
-            timestamp_columns timestamp_columns.merge(args)
+          def timestamps(*names)
+            timestamp_columns timestamp_columns.merge(names)
 
             include InstanceMethods
           end
@@ -62,11 +62,11 @@ module ROM
           #   result = create_user.call
           #   result[:created_at]  #=> Date.today
           #
-          # @param [Symbol] name of the attribute to set
+          # @param [Array<Symbol>] names A list of attribute names
           #
           # @api public
-          def datestamps(*args)
-            datestamp_columns datestamp_columns.merge(args)
+          def datestamps(*names)
+            datestamp_columns datestamp_columns.merge(names)
 
             include InstanceMethods
           end

data/lib/rom/sql/projection_dsl.rb

@@ -3,8 +3,20 @@ require 'rom/sql/function'
 
 module ROM
   module SQL
-    # @api private
+    # Projection DSL used in reading API (`select`, `select_append` etc.)
+    #
+    # @api public
     class ProjectionDSL < DSL
+      # Return a string literal that will be directly used in an SQL statement or query
+      #
+      # @example
+      #   users.select { `FOO`.as(:foo) }.first
+      #   # => { :foo => "FOO" }
+      #
+      # @param [String] value A string object
+      #
+      # @return [Attribute] An SQL attribute with a string literal expression
+      #
       # @api public
       def `(value)
         expr = ::Sequel.lit(value)

data/lib/rom/sql/relation.rb

@@ -61,7 +61,7 @@ module ROM
           #   @api public
           class_eval <<-RUBY, __FILE__, __LINE__ + 1
             def by_pk(#{schema.primary_key.map(&:name).join(', ')})
-              where(#{schema.primary_key.map { |attr| "self.class.schema[:#{attr.name}] => #{attr.name}" }.join(', ')})
+              where(#{schema.primary_key.map { |attr| "schema.canonical[:#{attr.name}] => #{attr.name}" }.join(', ')})
             end
           RUBY
         else
@@ -80,7 +80,7 @@ module ROM
                   "Missing primary key for :\#{schema.name}"
                 )
               end
-              where(self.class.schema[self.class.schema.primary_key_name].qualified => pk)
+              where(schema.canonical[schema.canonical.primary_key_name].qualified => pk)
             end
           RUBY
         end
@@ -116,6 +116,26 @@ module ROM
         associations[name].()
       end
 
+      # Open a database transaction
+      #
+      # @param [Hash] opts
+      # @option opts [Boolean] :auto_savepoint Automatically use a savepoint for Database#transaction calls inside this transaction block.
+      # @option opts [Symbol] :isolation The transaction isolation level to use for this transaction, should be :uncommitted, :committed, :repeatable, or :serializable, used if given and the database/adapter supports customizable transaction isolation levels.
+      # @option opts [Integer] :num_retries The number of times to retry if the :retry_on option is used. The default is 5 times. Can be set to nil to retry indefinitely, but that is not recommended.
+      # @option opts [Proc] :before_retry Proc to execute before rertrying if the :retry_on option is used. Called with two arguments: the number of retry attempts (counting the current one) and the error the last attempt failed with.
+      # @option opts [String] :prepare A string to use as the transaction identifier for a prepared transaction (two-phase commit), if the database/adapter supports prepared transactions.
+      # @option opts [Class] :retry_on An exception class or array of exception classes for which to automatically retry the transaction. Can only be set if not inside an existing transaction. Note that this should not be used unless the entire transaction block is idempotent, as otherwise it can cause non-idempotent behavior to execute multiple times.
+      # @option opts [Symbol] :rollback Can the set to :reraise to reraise any Sequel::Rollback exceptions raised, or :always to always rollback even if no exceptions occur (useful for testing).
+      # @option opts [Symbol] :server The server to use for the transaction. Set to :default, :read_only, or whatever symbol you used in the connect string when naming your servers.
+      # @option opts [Boolean] :savepoint Whether to create a new savepoint for this transaction, only respected if the database/adapter supports savepoints. By default Sequel will reuse an existing transaction, so if you want to use a savepoint you must use this option. If the surrounding transaction uses :auto_savepoint, you can set this to false to not use a savepoint. If the value given for this option is :only, it will only create a savepoint if it is inside a transacation.
+      # @option opts [Boolean] :deferrable **PG 9.1+ only** If present, set to DEFERRABLE if true or NOT DEFERRABLE if false.
+      # @option opts [Boolean] :read_only **PG only** If present, set to READ ONLY if true or READ WRITE if false.
+      # @option opts [Symbol] :synchronous **PG only** if non-nil, set synchronous_commit appropriately. Valid values true, :on, false, :off, :local (9.1+), and :remote_write (9.2+).
+      #
+      # @yield [t] Transaction
+      #
+      # @return [Mixed]
+      #
       # @api public
       def transaction(opts = EMPTY_HASH, &block)
         Transaction.new(dataset.db).run(opts, &block)

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

@@ -241,7 +241,7 @@ module ROM
         #
         # @api public
         def select_append(*args, &block)
-          schema.merge(self.class.schema.project(*args, &block)).(self)
+          schema.merge(schema.canonical.project(*args, &block)).(self)
         end
 
         # Returns a copy of the relation with a SQL DISTINCT clause.
@@ -273,7 +273,7 @@ module ROM
         # @example
         #   users.sum(:age)
         #
-        # @param [Array<Symbol>] *args A list with column names
+        # @param [Array<Symbol>] args A list with column names
         #
         # @return [Integer]
         #
@@ -287,7 +287,7 @@ module ROM
         # @example
         #   users.min(:age)
         #
-        # @param [Array<Symbol>] *args A list with column names
+        # @param [Array<Symbol>] args A list with column names
         #
         # @return Number
         #
@@ -301,7 +301,7 @@ module ROM
         # @example
         #   users.max(:age)
         #
-        # @param [Array<Symbol>] *args A list with column names
+        # @param [Array<Symbol>] args A list with column names
         #
         # @return Number
         #
@@ -315,7 +315,7 @@ module ROM
         # @example
         #   users.avg(:age)
         #
-        # @param [Array<Symbol>] *args A list with column names
+        # @param [Array<Symbol>] args A list with column names
         #
         # @return Number
         #
@@ -354,7 +354,7 @@ module ROM
         # @api public
         def where(*args, &block)
           if block
-            where(*args).where(self.class.schema.restriction(&block))
+            where(*args).where(schema.canonical.restriction(&block))
           elsif args.size == 1 && args[0].is_a?(Hash)
             new(dataset.where(coerce_conditions(args[0])))
           elsif !args.empty?
@@ -369,7 +369,7 @@ module ROM
         # @example
         #   users.exclude(name: 'Jane')
         #
-        # @param [Hash] *args A hash with conditions for exclusion
+        # @param [Hash] args A hash with conditions for exclusion
         #
         # @return [Relation]
         #
@@ -413,7 +413,7 @@ module ROM
         # @api public
         def having(*args, &block)
           if block
-            new(dataset.having(*args, *self.class.schema.restriction(&block)))
+            new(dataset.having(*args, *schema.canonical.restriction(&block)))
           else
             new(dataset.__send__(__method__, *args))
           end
@@ -468,7 +468,7 @@ module ROM
         # @api public
         def order(*args, &block)
           if block
-            new(dataset.order(*args, *self.class.schema.order(&block)))
+            new(dataset.order(*args, *schema.canonical.order(&block)))
           else
             new(dataset.__send__(__method__, *args, &block))
           end
@@ -678,10 +678,10 @@ module ROM
             if args.size > 0
               group(*args).group_append(&block)
             else
-              new(dataset.__send__(__method__, *schema.group(&block)))
+              new(dataset.__send__(__method__, *schema.canonical.group(&block)))
             end
           else
-            new(dataset.__send__(__method__, *schema.project(*args).canonical))
+            new(dataset.__send__(__method__, *schema.canonical.project(*args)))
           end
         end
 
@@ -717,7 +717,7 @@ module ROM
             if args.size > 0
               group_append(*args).group_append(&block)
             else
-              new(dataset.group_append(*schema.group(&block)))
+              new(dataset.group_append(*schema.canonical.group(&block)))
             end
           else
             new(dataset.group_append(*args))
@@ -730,7 +730,7 @@ 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
+        # @param [Array<Symbol>] args A list of column names
         #
         # @return [Relation]
         #
@@ -745,7 +745,7 @@ module ROM
         #   tasks.select_group(:user_id)
         #   # => [{ user_id: 1 }, { user_id: 2 }]
         #
-        # @param [Array<Symbol>] *args A list of column names
+        # @param [Array<Symbol>] args A list of column names
         #
         # @return [Relation]
         #
@@ -949,8 +949,8 @@ module ROM
         # @api private
         def coerce_conditions(conditions)
           conditions.each_with_object({}) { |(k, v), h|
-            if k.is_a?(Symbol) && self.class.schema.key?(k)
-              type = self.class.schema[k]
+            if k.is_a?(Symbol) && schema.canonical.key?(k)
+              type = schema.canonical[k]
               h[k] = v.is_a?(Array) ? v.map { |e| type[e] } : type[v]
             else
               h[k] = v

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

@@ -11,6 +11,8 @@ module ROM
         #   users.upsert({ name: 'Jane', email: 'jane@foo.com' },
         #                { target: :email, update: { name: :excluded__name } }
         #
+        # @return [Integer] Number of affected rows
+        #
         # @api public
         def upsert(*args, &block)
           if args.size > 1 && args[-1].is_a?(Hash)
@@ -28,9 +30,9 @@ module ROM
         # @example
         #   users.insert(name: 'Jane')
         #
-        # @param [Hash] tuple
+        # @param [Hash] args
         #
-        # @return [Relation]
+        # @return [Hash] Inserted tuple
         #
         # @api public
         def insert(*args, &block)
@@ -42,9 +44,9 @@ module ROM
         # @example
         #   users.multi_insert([{name: 'Jane'}, {name: 'Jack'}])
         #
-        # @param [Array] tuples
+        # @param [Array<Hash>] args
         #
-        # @return [Relation]
+        # @return [Array<String>] A list of executed SQL statements
         #
         # @api public
         def multi_insert(*args, &block)
@@ -57,7 +59,7 @@ module ROM
         #   users.update(name: 'Jane')
         #   users.where(name: 'Jane').update(name: 'Jane Doe')
         #
-        # @return [Relation]
+        # @return [Integer] Number of updated rows
         #
         # @api public
         def update(*args, &block)
@@ -71,7 +73,7 @@ module ROM
         #   users.where(name: 'Jane').delete # delete tuples
         #                                      from restricted relation
         #
-        # @return [Relation]
+        # @return [Integer] Number of deleted tuples
         #
         # @api public
         def delete(*args, &block)
@@ -79,6 +81,7 @@ module ROM
         end
 
         # Insert tuples from other relation
+        #
         # NOTE: The method implicitly uses a transaction
         #
         # @example
@@ -89,7 +92,7 @@ module ROM
         #   the INSERT ... SELECT statement will
         #   be used for importing the data
         #
-        #   @params [SQL::Relation] other_sql_relation
+        #   @param [SQL::Relation] other_sql_relation
         #
         #   @option [Integer] :slice
         #     Split loading into batches of provided size,
@@ -100,10 +103,12 @@ module ROM
         #   Import data from another relation. The source
         #   relation will be materialized before loading
         #
-        #   @params [Relation] other
+        #   @param [Relation] other
         #
         #   @option [Integer] :slice
         #
+        # @return [Integer] Number of imported tuples
+        #
         # @api public
         def import(other, options = EMPTY_HASH)
           if other.gateway.eql?(gateway)

data/lib/rom/sql/restriction_dsl.rb

@@ -14,7 +14,7 @@ module ROM
       # @example
       #   users.where { exists(users.where(name: 'John')) }
       def exists(relation)
-        relation.dataset.exists
+        ::ROM::SQL::Attribute[Types::Bool].meta(sql_expr: relation.dataset.exists)
       end
 
       private

data/lib/rom/sql/schema.rb

@@ -11,6 +11,9 @@ require 'rom/sql/schema/inferrer'
 
 module ROM
   module SQL
+    # Specialized schema for SQL databases
+    #
+    # @api public
     class Schema < ROM::Schema
       # @!attribute [r] indexes
       #   @return [Array<Index>] Array with schema indexes
@@ -20,16 +23,34 @@ module ROM
       #   @return [Array<ForeignKey>] Array with foreign keys
       option :foreign_keys, default: -> { EMPTY_SET }
 
+      # Open restriction DSL for defining query conditions using schema attributes
+      #
+      # @see Relation#where
+      #
+      # @return [Mixed] Result of the block call
+      #
       # @api public
       def restriction(&block)
         RestrictionDSL.new(self).call(&block)
       end
 
+      # Open Order DSL for setting ORDER clause in queries
+      #
+      # @see Relation#order
+      #
+      # @return [Mixed] Result of the block call
+      #
       # @api public
       def order(&block)
         OrderDSL.new(self).call(&block)
       end
 
+      # Open Group DSL for setting GROUP BY clause in queries
+      #
+      # @see Relation#group
+      #
+      # @return [Mixed] Result of the block call
+      #
       # @api public
       def group(&block)
         GroupDSL.new(self).call(&block)
@@ -44,15 +65,13 @@ module ROM
         new(map { |attr| attr.qualified(table_alias) })
       end
 
-      # Return a new schema with attributes restored to canonical form
+      # Project a schema
       #
-      # @return [Schema]
+      # @see ROM::Schema#project
+      # @see Relation#select
+      #
+      # @return [Schema] A new schema with projected attributes
       #
-      # @api public
-      def canonical
-        new(map(&:canonical))
-      end
-
       # @api public
       def project(*names, &block)
         if block
@@ -62,21 +81,39 @@ module ROM
         end
       end
 
+      # Project schema so that it only contains primary key
+      #
+      # @return [Schema]
+      #
       # @api private
       def project_pk
         project(*primary_key_names)
       end
 
+      # Project schema so that it only contains renamed foreign key
+      #
+      # @return [Schema]
+      #
       # @api private
       def project_fk(mapping)
         new(rename(mapping).map(&:foreign_key))
       end
 
+      # Join with another schema
+      #
+      # @param [Schema] other The other schema to join with
+      #
+      # @return [Schema]
+      #
       # @api public
       def join(other)
         merge(other.joined)
       end
 
+      # Return a new schema with all attributes marked as joined
+      #
+      # @return [Schema]
+      #
       # @api public
       def joined
         new(map(&:joined))
@@ -102,6 +139,8 @@ module ROM
         new(EMPTY_ARRAY)
       end
 
+      # Finalize all attributes by qualifying them and initializing primary key names
+      #
       # @api private
       def finalize_attributes!(options = EMPTY_HASH)
         super do
@@ -110,6 +149,8 @@ module ROM
         end
       end
 
+      # Finalize associations
+      #
       # @api private
       def finalize_associations!(relations:)
         super do

data/lib/rom/sql/schema/dsl.rb

@@ -3,14 +3,26 @@ require 'rom/sql/schema/index_dsl'
 module ROM
   module SQL
     class Schema < ROM::Schema
+      # Specialized schema DSL with SQL-specific features
+      #
       # @api public
       class DSL < ROM::Schema::DSL
+        # @!attribute [r] index_dsl
+        #   @return [IndexDSL] Index DSL instance (created only if indexes block is called)
         attr_reader :index_dsl
 
+        # Define indexes within a block
+        #
+        # @api public
         def indexes(&block)
           @index_dsl = IndexDSL.new(options, &block)
         end
 
+        private
+
+        # Return schema options
+        #
+        # @api private
         def opts
           if index_dsl
             opts = super

data/lib/rom/sql/type_dsl.rb

@@ -1,8 +1,12 @@
 module ROM
   module SQL
+    # Type DSL used by Types.define method
+    #
+    # @api public
     class TypeDSL
       attr_reader :definition, :input_constructor, :output_constructor
 
+      # @api private
       def initialize(value_type)
         if value_type.class < ::Dry::Types::Type
           @definition = value_type
@@ -11,6 +15,7 @@ module ROM
         end
       end
 
+      # @api private
       def call(&block)
         instance_exec(&block)
 
@@ -18,10 +23,12 @@ module ROM
           .meta(read: definition.constructor(output_constructor))
       end
 
+      # @api private
       def input(&block)
         @input_constructor = block
       end
 
+      # @api private
       def output(&block)
         @output_constructor = block
       end

data/lib/rom/sql/type_extensions.rb

@@ -7,7 +7,7 @@ module ROM
       class << self
         # Gets extensions for a type
         #
-        # @param [Dry::Types::Type] type
+        # @param [Dry::Types::Type] wrapped
         #
         # @return [Hash]
         #

data/lib/rom/sql/types.rb

@@ -9,18 +9,32 @@ module ROM
     module Types
       include ROM::Types
 
-      def self.Constructor(*args, &block)
-        ROM::Types.Constructor(*args, &block)
-      end
-
-      def self.Definition(*args, &block)
-        ROM::Types.Definition(*args, &block)
-      end
-
+      # Define a foreign key attribute type
+      #
+      # @example with default Int type
+      #   attribute :user_id, Types.ForeignKey(:users)
+      #
+      # @example with a custom type
+      #   attribute :user_id, Types.ForeignKey(:users, Types::UUID)
+      #
+      # @return [Dry::Types::Definition]
+      #
+      # @api public
       def self.ForeignKey(relation, type = Types::Int.meta(index: true))
         super
       end
 
+      # Define a complex attribute type using Type DSL
+      #
+      # @example
+      #   attribute :meta, Types.define(Types::JSON) do
+      #     input { Types::PG::JSON }
+      #     output { Types::Coercible::Hash }
+      #   end
+      #
+      # @return [Dry::Types::Definition]
+      #
+      # @api public
       def self.define(value_type, &block)
         TypeDSL.new(value_type).call(&block)
       end

data/lib/rom/sql/version.rb

@@ -1,5 +1,5 @@
 module ROM
   module SQL
-    VERSION = '2.0.0.beta3'.freeze
+    VERSION = '2.0.0.rc1'.freeze
   end
 end

data/lib/rom/sql/wrap.rb

@@ -2,21 +2,32 @@ require 'rom/relation/wrap'
 
 module ROM
   module SQL
+    # Specialized wrap relation for SQL
+    #
+    # This type of relations is returned when using `Relation#wrap` and it uses
+    # a join, unlike `Relation#combine`, which means a relation is restricted
+    # only to tuples which have associated tuples. It should be used in cases
+    # where you want to rely on this restriction.
+    #
+    # @api public
     class Wrap < Relation::Wrap
+      # Return a schema which includes attributes from wrapped relations
+      #
+      # @return [Schema]
+      #
       # @api public
       def schema
         root.schema.merge(nodes.map(&:schema).reduce(:merge)).qualified
       end
 
+      # Internal method used by abstract `ROM::Relation::Wrap`
+      #
+      # @return [Relation]
+      #
       # @api private
       def relation
         relation = nodes.reduce(root) do |a, e|
-          if associations.key?(e.name.key)
-            a.associations[e.name.key].join(:join, a, e)
-          else
-            # TODO: deprecate this before 2.0
-            a.qualified.join(e.name.dataset, e.meta[:keys])
-          end
+          a.associations[e.name.key].join(:join, a, e)
         end
         schema.(relation)
       end

metadata

@@ -1,29 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: rom-sql
 version: !ruby/object:Gem::Version
-  version: 2.0.0.beta3
+  version: 2.0.0.rc1
 platform: ruby
 authors:
 - Piotr Solnica
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-08-14 00:00:00.000000000 Z
+date: 2017-09-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sequel
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '4.43'
+        version: '4.49'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '4.43'
+        version: '4.49'
 - !ruby/object:Gem::Dependency
   name: dry-equalizer
   requirement: !ruby/object:Gem::Requirement
@@ -44,20 +44,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.11'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.11.1
+        version: '0.12'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.11'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.11.1
+        version: '0.12'
 - !ruby/object:Gem::Dependency
   name: dry-core
   requirement: !ruby/object:Gem::Requirement
@@ -78,14 +72,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 4.0.0.beta
+        version: 4.0.0.rc
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 4.0.0.beta
+        version: 4.0.0.rc
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -228,7 +222,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">"