rom-sql 2.5.0 → 3.3.0

data/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2015-2020 rom-rb team
+
+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.md

@@ -1,38 +1,28 @@
 [gem]: https://rubygems.org/gems/rom-sql
-[travis]: https://travis-ci.org/rom-rb/rom-sql
-[codeclimate]: https://codeclimate.com/github/rom-rb/rom-sql
+[actions]: https://github.com/rom-rb/rom-sql/actions
+[codacy]: https://www.codacy.com/gh/rom-rb/rom-sql
+[chat]: https://rom-rb.zulipchat.com
 [inchpages]: http://inch-ci.org/github/rom-rb/rom-sql
 
-# rom-sql
+# rom-sql [![Join the chat at https://rom-rb.zulipchat.com](https://img.shields.io/badge/rom--rb-join%20chat-%23346b7a.svg)][chat]
 
 [![Gem Version](https://badge.fury.io/rb/rom-sql.svg)][gem]
-[![Build Status](https://travis-ci.org/rom-rb/rom-sql.svg?branch=master)][travis]
-[![Code Climate](https://codeclimate.com/github/rom-rb/rom-sql/badges/gpa.svg)][codeclimate]
-[![Test Coverage](https://codeclimate.com/github/rom-rb/rom-sql/badges/coverage.svg)][codeclimate]
+[![CI Status](https://github.com/rom-rb/rom-sql/workflows/ci/badge.svg)][actions]
+[![Codacy Badge](https://api.codacy.com/project/badge/Grade/8e2cbaf78af44185876c8fa41540d7ea)][codacy]
+[![Codacy Badge](https://api.codacy.com/project/badge/Coverage/8e2cbaf78af44185876c8fa41540d7ea)][codacy]
 [![Inline docs](http://inch-ci.org/github/rom-rb/rom-sql.svg?branch=master)][inchpages]
 
-SQL support for [rom-rb](https://github.com/rom-rb/rom).
+## Links
 
-Resources:
+* [User documentation](http://rom-rb.org/learn/sql)
+* [API documentation](http://rubydoc.info/gems/rom-sql)
 
-- [User Documentation](http://rom-rb.org/learn/sql/)
-- [API Documentation](http://rubydoc.info/gems/rom-sql)
+## Supported Ruby versions
 
-## Installation
+This library officially supports the following Ruby versions:
 
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'rom-sql'
-```
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install rom-sql
+* MRI >= `2.5`
+* jruby >= `9.2`
 
 ## License
 

data/lib/rom-sql.rb

@@ -1 +1,3 @@
+# frozen_string_literal: true
+
 require 'rom/sql'

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'rom/support/notifications'
 
 module ROM

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ROM
   module Plugins
     module Relation

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ROM
   module Plugins
     module Relation
@@ -24,14 +26,11 @@ module ROM
             #
             # @api public
             def explain(format: :text, **options)
-              bool_options = options.map { |opt, value| "#{ opt.to_s.upcase } #{ !!value }" }
-              format_option = "FORMAT #{ format.to_s.upcase }"
+              bool_options = options.map { |opt, value| "#{opt.to_s.upcase} #{!!value}" }
+              format_option = "FORMAT #{format.to_s.upcase}"
+              explain_value = [format_option, *bool_options].join(', ')
 
-              query =
-                "EXPLAIN (" <<
-                [format_option, *bool_options].join(', ') <<
-                ") " <<
-                dataset.sql
+              query = "EXPLAIN (#{explain_value}) #{dataset.sql}"
 
               rows = dataset.with_sql(query).map(:'QUERY PLAN')
 

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module ROM
+  module Plugins
+    module Relation
+      module SQL
+        module Postgres
+          # PG-specific extensions which adds `Relation#full_text_search` method
+          #
+          # @api public
+          module FullTextSearch
+            # Run a full text search on PostgreSQL.
+            # By default, searching for the inclusion of any of the terms in any of the cols.
+            #
+            # @example
+            #   posts.full_text_search([:title, :content], 'apples', language: 'english') # => Relation which match the 'apples' phrase
+            #
+            # @option :headline [String] Append a expression to the selected columns aliased to headline that contains an extract of the matched text.
+            #
+            # @option :language [String] The language to use for the search (default: 'simple')
+            #
+            # @option :plain [Boolean] Whether a plain search should be used (default: false).  In this case, terms should be a single string, and it will do a search where cols contains all of the words in terms.  This ignores search operators in terms.
+            #
+            # @option :phrase [Boolean] Similar to :plain, but also adding an ILIKE filter to ensure that returned rows also include the exact phrase used.
+            #
+            # @option :rank [Boolean] Set to true to order by the rank, so that closer matches are returned first.
+            #
+            # @option :to_tsquery [Symbol] Can be set to :plain or :phrase to specify the function to use to convert the terms to a ts_query.
+            #
+            # @option :tsquery [Boolean] Specifies the terms argument is already a valid SQL expression returning a tsquery, and can be used directly in the query.
+            #
+            # @option :tsvector [Boolean] Specifies the cols argument is already a valid SQL expression returning a tsvector, and can be used directly in the query.
+            #
+            # @return [Relation]
+            #
+            # @see https://www.postgresql.org/docs/current/textsearch.html PostgreSQL docs
+            #
+            # @api public
+            def full_text_search(*args, &block)
+              new dataset.__send__(__method__, *args, &block)
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+ROM.plugins do
+  adapter :sql do
+    register :pg_full_text_search, ROM::Plugins::Relation::SQL::Postgres::FullTextSearch, type: :relation
+  end
+end

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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module ROM
+  module Plugins
+    module Relation
+      module SQL
+        module Postgres
+          # PG-specific extensions which adds `Relation#stream` method
+          #
+          # @api public
+          module Streaming
+            extend Notifications::Listener
+
+            class StreamingNotSupportedError < StandardError; end
+
+            subscribe("configuration.gateway.connected") do |opts|
+              conn = opts[:connection]
+
+              next unless conn.database_type.to_sym == :postgres
+
+              next if defined?(JRUBY_VERSION)
+
+              begin
+                require "sequel_pg"
+              rescue LoadError
+                raise StreamingNotSupportedError, "add sequel_pg to Gemfile to use pg_streaming"
+              end
+
+              unless Sequel::Postgres.supports_streaming?
+                raise StreamingNotSupportedError, "postgres version does not support streaming"
+              end
+
+              conn.extension(:pg_streaming)
+            end
+
+            def self.included(klass)
+              super
+              ROM::Relation::Graph.include(Combined)
+            end
+
+            if defined?(JRUBY_VERSION)
+              # Allows you to stream returned rows one at a time, instead of
+              # collecting the entire result set in memory. Requires the `sequel_pg` gem
+              #
+              # @see https://github.com/jeremyevans/sequel_pg#streaming- sequel_pg docs
+              #
+              # @example
+              #   posts.steam_each { |post| puts CSV.generate_line(post) }
+              #
+              # @return [Relation]
+              #
+              # @api publicY_VERSION
+              def stream_each
+                raise StreamingNotSupportedError, "not supported on jruby"
+              end
+            else
+              # Allows you to stream returned rows one at a time, instead of
+              # collecting the entire result set in memory. Requires the `sequel_pg` gem
+              #
+              # @see https://github.com/jeremyevans/sequel_pg#streaming- sequel_pg docs
+              #
+              # @example
+              #   posts.steam_each { |post| puts CSV.generate_line(post) }
+              #
+              # @return [Relation]
+              #
+              # @api public
+              def stream_each
+                return to_enum unless block_given?
+
+                ds = dataset.stream
+
+                if auto_map?
+                  ds.each { |tuple| yield(mapper.([output_schema[tuple]]).first) }
+                else
+                  ds.each { |tuple| yield(output_schema[tuple]) }
+                end
+              end
+
+              module Combined
+                def stream_each
+                  raise StreamingNotSupportedError, "not supported on combined relations"
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+ROM.plugins do
+  adapter :sql do
+    register :pg_streaming, ROM::Plugins::Relation::SQL::Postgres::Streaming, type: :relation
+  end
+end

data/lib/rom/sql.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'dry/equalizer'
 
 require 'rom/core'

data/lib/rom/sql/associations.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'rom/sql/associations/many_to_many'
 require 'rom/sql/associations/many_to_one'
 require 'rom/sql/associations/one_to_many'

data/lib/rom/sql/associations/core.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ROM
   module SQL
     module Associations
@@ -14,6 +16,14 @@ module ROM
 
           target.where(target_key => target_pks)
         end
+
+        # @api private
+        def wrapped
+          new_target = view ? target.send(view) : target
+          to_wrap = self.class.allocate
+          to_wrap.send(:initialize, definition, **options, target: new_target)
+          to_wrap.wrap
+        end
       end
     end
   end

data/lib/rom/sql/associations/many_to_many.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'rom/associations/many_to_many'
 require 'rom/sql/associations/core'
 require 'rom/sql/associations/self_ref'
@@ -18,7 +20,7 @@ module ROM
               if target != self.target
                 target.schema.merge(join_schema)
               else
-                left.schema.project(*columns)
+                left.schema.uniq.project(*columns)
               end
             else
               target_schema
@@ -36,8 +38,14 @@ module ROM
         # @api public
         def join(type, source = self.source, target = self.target)
           through_assoc = source.associations[through]
+
+          # first we join source to intermediary
           joined = through_assoc.join(type, source)
-          joined.__send__(type, target.name.dataset, join_keys).qualified
+
+          # then we join intermediary to target
+          target_ds  = target.name.dataset
+          through_jk = through_assoc.target.associations[target_ds].join_keys
+          joined.__send__(type, target_ds, through_jk).qualified
         end
 
         # @api public

data/lib/rom/sql/associations/many_to_one.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'rom/associations/many_to_one'
 require 'rom/sql/associations/core'
 require 'rom/sql/associations/self_ref'

data/lib/rom/sql/associations/one_to_many.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'rom/associations/one_to_many'
 require 'rom/sql/associations/core'
 require 'rom/sql/associations/self_ref'

data/lib/rom/sql/associations/one_to_one.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'rom/sql/associations/one_to_many'
 
 module ROM

data/lib/rom/sql/associations/one_to_one_through.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'rom/sql/associations/many_to_many'
 
 module ROM

data/lib/rom/sql/associations/self_ref.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ROM
   module SQL
     module Associations

data/lib/rom/sql/attribute.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'sequel/core'
 require 'dry/core/cache'
 
@@ -5,6 +7,8 @@ require 'rom/attribute'
 
 require 'rom/sql/type_extensions'
 require 'rom/sql/projection_dsl'
+require 'rom/sql/attribute_wrapping'
+require 'rom/sql/attribute_aliasing'
 
 module ROM
   module SQL
@@ -12,41 +16,31 @@ module ROM
     #
     # @api public
     class Attribute < ROM::Attribute
+      include AttributeWrapping
+      include AttributeAliasing
+
       OPERATORS = %i[>= <= > <].freeze
       NONSTANDARD_EQUALITY_VALUES = [true, false, nil].freeze
-      META_KEYS = %i(index foreign_key target sql_expr qualified).freeze
+      META_KEYS = %i[index foreign_key target sql_expr qualified].freeze
 
       # Error raised when an attribute cannot be qualified
       QualifyError = Class.new(StandardError)
 
       extend Dry::Core::Cache
 
-      # @api private
-      def self.[](*args)
-        fetch_or_store(args) { new(*args) }
-      end
-
-      option :extensions, type: Types::Hash, default: -> { TypeExtensions[type] }
-
-      # Return a new attribute with an alias
-      #
-      # @example
-      #   users[:id].aliased(:user_id)
-      #
-      # @return [SQL::Attribute]
-      #
-      # @api public
-      def aliased(name)
-        super.meta(name: meta.fetch(:name, name), sql_expr: sql_expr.as(name))
+      class << self
+        # @api private
+        def [](type, options = EMPTY_HASH)
+          fetch_or_store([type, options]) { new(type, **options) }
+        end
       end
-      alias_method :as, :aliased
 
       # Return a new attribute in its canonical form
       #
       # @api public
       def canonical
         if aliased?
-          meta(alias: nil, sql_expr: nil)
+          with(alias: nil).meta(sql_expr: nil)
         else
           self
         end
@@ -62,16 +56,32 @@ module ROM
       # @api public
       def qualified(table_alias = nil)
         return self if qualified? && table_alias.nil?
+        return meta(qualified: false) unless qualifiable?
 
         case sql_expr
         when Sequel::SQL::AliasedExpression, Sequel::SQL::Identifier, Sequel::SQL::QualifiedIdentifier
-          type = meta(qualified: table_alias || true)
-          type.meta(sql_expr: type.to_sql_name)
+          attr = meta(qualified: table_alias || true)
+          attr.meta(sql_expr: attr.to_sql_name)
         else
           raise QualifyError, "can't qualify #{name.inspect} (#{sql_expr.inspect})"
         end
       end
 
+      # Return a new attribute that is aliased and marked as qualified
+      #
+      # Intended to be used when passing attributes to `dataset#select`
+      #
+      # @return [SQL::Attribute]
+      #
+      # @api public
+      def qualified_projection(table_alias = nil)
+        if aliased?
+          qualified(table_alias).aliased(self.alias)
+        else
+          qualified(table_alias)
+        end
+      end
+
       # Return a new attribute marked as joined
       #
       # Whenever you join two schemas, the right schema's attribute
@@ -114,6 +124,15 @@ module ROM
         meta[:qualified].equal?(true) || meta[:qualified].is_a?(Symbol)
       end
 
+      # Return if an attribute is qualifiable
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      def qualifiable?
+        !source.nil?
+      end
+
       # Return a new attribute marked as a FK
       #
       # @return [SQL::Attribute]
@@ -239,7 +258,7 @@ module ROM
       # Create a function DSL from the attribute
       #
       # @example
-      #   users[:id].func { int::count(id).as(:count) }
+      #   users[:id].func { integer::count(id).as(:count) }
       #
       # @return [SQL::Function]
       #
@@ -281,12 +300,12 @@ module ROM
       # @api private
       def to_sql_name
         @_to_sql_name ||=
-          if qualified? && aliased?
-            Sequel.qualify(table_name, name).as(meta[:alias])
+          if qualified? && aliased_projection?
+            Sequel.qualify(table_name, name).as(self.alias)
           elsif qualified?
             Sequel.qualify(table_name, name)
-          elsif aliased?
-            Sequel.as(name, meta[:alias])
+          elsif aliased_projection?
+            Sequel.as(name, self.alias)
           else
             Sequel[name]
           end
@@ -305,7 +324,7 @@ module ROM
       end
 
       # @api private
-      def meta_ast
+      def meta_options_ast
         meta = super
         meta[:index] = true if indexed?
         meta
@@ -318,7 +337,41 @@ module ROM
         cleaned_meta = meta.reject { |k, _| META_KEYS.include?(k) }
         type = optional? ? right : self.type
 
-        self.class.new(type.with(meta: cleaned_meta), options)
+        self.class.new(type.with(meta: cleaned_meta), **options)
+      end
+
+      # Wrap a value with the type, it allows using attribute and type specific methods
+      # on literals and things like this
+      #
+      # @param [Object] value any SQL-serializable value
+      # @return [SQL::Attribute]
+      #
+      # @api public
+      def value(value)
+        meta(sql_expr: Sequel[value])
+      end
+
+      # Build a case expression based on attribute. See SQL::Function#case
+      # when you don't have a specific expression after the CASE keyword.
+      # Pass the :else keyword to provide the catch-all case, it's mandatory
+      # because of the Sequel's API used underneath.
+      #
+      # @example
+      #   users.select_append { id.case(1 => `'first'`, else: `'other'`).as(:first_or_not) }
+      #
+      # @param [Hash] mapping mapping between SQL expressions
+      # @return [SQL::Attribute]
+      #
+      # @api public
+      def case(mapping)
+        mapping = mapping.dup
+        otherwise = mapping.delete(:else) do
+          raise ArgumentError, 'provide the default case using the :else keyword'
+        end
+
+        type = mapping.values[0].type
+
+        Attribute[type].meta(sql_expr: ::Sequel.case(mapping, otherwise, self))
       end
 
       private
@@ -376,6 +429,11 @@ module ROM
         end
       end
 
+      # @api private
+      def extensions
+        TypeExtensions[type]
+      end
+
       memoize :joined, :to_sql_name, :table_name, :canonical
     end
   end