sbf-dm-sql-finders 0.0.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 665a67daa8f15e23b7aab76eba4254701a2cfc1a48a7a713eec4416802f7e22e
+  data.tar.gz: d25d3a27c1887c90a0c619d9e97c856de90ca41477406af55ee1de7a118baf9a
+SHA512:
+  metadata.gz: 8209b337ad35dd5f9a5cfc827cc48873488da5b2946b229e20c925e2485c099150f86424820618e41b83f87230f4c4efd0e9832b981563da23e76bef3278c0a2
+  data.tar.gz: 0efb3a89f66debd66f878807e227c4ed894d011d0ffb2654f486205f59a15ae000040e9eb7ab56a3ebb2fe50cc7569f4978a082d85279f5647f46eda5c17f834

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/.rspec

@@ -0,0 +1 @@
+--colour

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in dm-sql-finders.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Chris Corbyn
+
+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

@@ -0,0 +1,271 @@
+# DataMapper SQL Finders
+
+DataMapper SQL Finders adds `#by_sql` to your models, as a compliment to the standard pure-ruby
+query system used by DataMapper.  The SQL you write will be executed directly against the adapter,
+but you do not need to lose the benefit of the field and table name abstraction offered by DM.
+When you invoke `#by_sql`, one or more table representations are yielded into a block, which you
+provide.  These objects are interpolated into your SQL, such that you use DataMapper properties in
+the SQL and make no direct reference to the real field names in the database schema.
+
+I wrote this gem because my original reason for using DataMapper was that I needed to work with a
+large, existing database schema belonging to an old PHP application, subsequently ported to Rails.
+We need the naming abstraction offered by DataMapper, but we also prefer its design. That said, we
+run some queries that are less than trivial, mixing LEFT JOINs and inline derived tables…
+something which DataMapper does not currently handle at all.  `#by_sql` allows us to drop down to
+SQL in places where we need it, but where we don't want to by-pass DataMapper entirely.
+
+The `#by_sql` method returns a DataMapper `Collection` wrapping a `Query`, in just the same way
+`#all` does.  Just like using `#all`, no SQL is executed until a kicker triggers its execution
+(e.g. beginning to iterate over a Collection).
+
+Because the implementation is based around a real DataMapper Query object, you can chain other
+DataMapper methods, such as `#all`, or methods or relationships defined on your Model.
+
+It looks like this:
+
+``` ruby
+class Post
+  include DataMapper::Resource
+
+  property :id,    Serial
+  property :title, String
+
+  belongs_to :user
+end
+
+class User
+  include DataMapper::Resource
+
+  property :id,       Serial
+  property :username, String
+
+  has n, :posts
+
+
+  def self.never_posted
+    by_sql(Post) { |u, p| "SELECT #{u.*} FROM #{u} LEFT JOIN #{p} ON #{p.user_id} = #{u.id} WHERE #{p.id} IS NULL" }
+  end
+end
+
+User.never_posted.each do |user|
+  puts "#{user.username} has never created a Post"
+end
+```
+
+The first block argument is always the current Model.  You can optionally pass additional models to `#by_sql` and have
+them yielded into the block if you need to join.
+
+You may chain regular DataMapper finders onto the result (the original SQL is modified with the additions):
+
+``` ruby
+User.never_posted.all(:username.like => "%bob%")
+```
+
+## A note about DataMapper 2.0
+
+The DataMapper guys are hard at work creating DataMapper 2.0, which involves a lot of under-the-surface changes, most
+notably building DM's query interface atop [Veritas](https://github.com/dkubb/veritas), with the adapter layer generating
+SQL by walking a Veritas relation (an AST - abstract syntax tree).  Because of the way DM 1 handles queries, it is not
+trivial to support SQL provided by the user (except for the trival case of it being in the WHERE clause).  With any hope,
+gems like this will either not be needed in DM 2.0, or at least will be easy to implement cleanly, since SQL and Veritas
+play nicely with each other.
+
+## Installation
+
+Via rubygems:
+
+    gem install dm-sql-finders
+
+## Detailed Usage
+
+Note that in the following examples, you are not forced to use the table representations yielded into the block, but you
+are encouraged to.  They respond to the following methods:
+
+  - `tbl.*`: expands the splat to only the known fields defined in your model. Other fields in the database are excluded.
+  - `tbl.to_s`: represents the name of the table in the database.  `#to_s` is invoked implcitly in String context. Note
+     that if you join to the same table multiple times, DataMapper SQL Finders will alias them accordingly.
+  - `tbl.property_name`: represents the field name in the database mapping to `property_name` in your model.
+
+Writing the field/table names directly, while it will work, is not advised, since it will significantly hamper any future
+efforts to chain onto the query (and it reads just like SQL anyway, right?).
+
+### Basic SELECT statements
+
+Returning a String from the block executes the SQL when a kicker is invoked (e.g. iterating the Collection).
+
+``` ruby
+def self.basically_everything
+  by_sql { |m| "SELECT #{m.*} FROM #{m}" }
+end
+```
+
+### Passing in variables
+
+The block may return an Array, with the first element as the SQL and the following elements as the bind values.
+
+``` ruby
+def self.created_after(time)
+  by_sql { |m| ["SELECT #{m.*} FROM #{m} WHERE #{m.created_at} > ?", time] }
+end
+```
+
+### Selecting less than all fields
+
+Just specify individual fields in the SQL.  The regular DM semantics apply (i.e. the rest will be lazy loaded, and omitting the
+primary key means your records are immutable).
+
+``` ruby
+def self.usernames_only
+  by_sql { |u| "SELECT #{u.username} FROM #{u}" }
+end
+```
+
+### Selecting *more* than all fields (experimental)
+
+This allows you to pre-load things like aggregate calculations you may otherwise add denormalizations for:
+
+``` ruby
+def self.with_post_counts
+  by_sql(Post) { |u, p| "SELECT #{u.*}, COUNT(#{p.id}) AS post_count FROM #{u} INNER JOIN #{p} ON #{p.user_id} = #{u.id} GROUP BY #{u.id}" }
+end
+```
+
+A `@post_count` instnace variable is set on all resources.  Currently this is always a String.  You will need to typecast manually.
+
+See the section on "Joins" for details on the join syntax.
+
+You should consider this feature experimental.  It takes advantage of the fact DM Property instances can be created and thrown-away
+on-the-fly.
+
+### Ordering
+
+DataMapper always adds an ORDER BY to your queries if you don't specify one.  DataMapper SQL Finders behaves no differently.
+The default ordering is always ascending by primary key.  You can override it in the SQL:
+
+``` ruby
+def self.backwards
+  by_sql { |m| "SELECT #{m.*} FROM #{m} ORDER BY #{m.id} DESC" }
+end
+```
+
+Or you can provide it as a regular option to `#by_sql`, just like you can with `#all`:
+
+``` ruby
+def self.backwards
+  by_sql(:order => [:id.desc]) { |m| "SELECT #{m.*} FROM #{m}" }
+end
+```
+
+Note that the `:order` option take precendence over anything specified in the SQL.  This allows method chains to override it.
+
+### Joins
+
+The additional models are passed to `#by_sql`, then you use them to construct the join.
+
+``` ruby
+class User
+  ... snip ...
+
+  def self.posted_today
+    by_sql(Post) { |u, p| ["SELECT #{u.*} FROM #{u} INNER JOIN #{p} ON #{p.user_id} = #{u.id} WHERE #{p.created_at} > ?", Date.today - 1] }
+  end
+end
+```
+
+The `:links` option will also be interpreted and added to the `FROM` clause in the SQL.  This is useful if you need to override the SQL.
+
+### Limits and offsets
+
+These can be specified in the SQL:
+
+``` ruby
+def self.penultimate_five
+  by_sql { |m| "SELECT #{m.*} FROM #{m} ORDER BY #{m.id} DESC LIMIT 5 OFFSET 5" }
+end
+```
+
+Or they can be provided as options to `#by_sql`:
+
+``` ruby
+def self.penultimate_five
+  by_sql(:limit => 5, :offset => 5) { |m| "SELECT #{m.*} FROM #{m}" }
+end
+```
+
+If `:limit` and/or `:offset` are passed to `#by_sql`, they take precedence over anything written in the SQL itself.
+
+### Method chaining
+
+Method chaining with `#by_sql`, for the most part, works just like with `#all`.  There are some current limitations,
+such as reversing the order of a query that used `ORDER BY` in the SQL, rather than via an `:order` option.
+
+Also note the you may not currently chain `#by_sql` calls together.  `#by_sql` must, logically, always be the first
+call in the chain.
+
+``` ruby
+User.by_sql{ |u| ["SELECT #{u.*} FROM #{u} WHERE #{u.role} = ?", "Manager"] }.all(:username.like => "%bob%", :order => [:username.desc])
+```
+
+### Unions, Intersections and Differences
+
+Unfortunately this is not currently supported, and will likely only be added after the other limitations are worked out.
+
+Specifically, queries like this:
+
+``` ruby
+User.by_sql { |u| ["SELECT #{u.*} FROM #{u} WHERE #{u.created_at} < ?", Date.today - 365] } | User.all(:admin => true)
+```
+
+Should really produce SQL of the nature:
+
+``` sql
+SELECT "users"."id", "users"."username", "users"."admin" FROM "users" WHERE ("created_at" < ?) OR (admin = TRUE)
+```
+
+I have no idea what will happen if it is attempted, but it almost certainly will not work ;)
+
+## Will it interfere with DataMapper?
+
+`#select_statement` on the adapter is overridden such that, when you use `#by_sql` query, code in the gem is executed, and
+when you execute a regular query, the original code pathways are followed.  I'd prefer some sort of extension API in
+DataObjectsAdapter to allow hooks into its SQL generation logic, but for now, this is how it works.
+
+DataMapper 2.0 *should* fix this.
+
+## Contributors
+
+DataMapper SQL Finders is currently written by [Chris Corbyn](https://github.com/d11wtq)
+
+Contributions are more than gladly accepted.  The primary goal is to support SQL in a way that does not break gems like dm-aggregates
+and dm-pager.  The more the SQL can be interpreted and turned into a native Query, the better.
+
+## TODO
+
+There are some known limitations, that are mostly edge-cases.  You will only run into them if you try to get too crazy combining regular
+DM queries with SQL (e.g. adding `:links` to a hand-written SQL query works, unless you have used bind values somewhere other than the
+WHERE clause *and if*, and *only if* DataMapper needs to use a bind value in the join, such as for special join conditions).  Real
+edge-cases.
+
+  - Support overriding `:fields` in a `#by_sql` query (complex if the query depends on RDBMS native functions in both the WHERE and the SELECT)
+  - Reverse the order when invoking `#reverse` in a `#by_sql` query that used `ORDER BY` in the SQL (note this will work just fine if
+    you use the `:order` option)
+  - Better support for `?` replacements in places other than the `WHERE` clause
+  - Support set operations (union, intersection, difference)
+  - Possibly (?) support crazy complex mass-updates (seems a little DB-specific though):
+    `User.by_sql { ... something with join conditions ... }.update!(:banned => true)` (MySQL, for one, can do `UPDATE ... INNER JOIN ...`)
+
+## Future Plans
+
+Before I started writing this, I wanted to implement something similar to Doctrine's (PHP) DQL, probably called DMQL.
+This is basically a strict superset of SQL that is pre-processed with DataMapper, having knowledge of your schema,
+therefore allowing you to simplify the query and let DMQL hande things like JOIN logic.  Say, for example:
+
+``` ruby
+Post.by_dmql("JOIN User u WHERE u.username = ?", "Bob")
+```
+
+Which would INNER JOIN posts with users and map `u.username` with the real field name of the `User#username` property.
+
+This gem would be a pre-requisite for that.
+
+Copyright (c) 2011 Chris Corbyn.

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/dm-sql-finders.gemspec

@@ -0,0 +1,35 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "data_mapper/sql_finders/version"
+
+Gem::Specification.new do |s|
+  s.name        = "sbf-dm-sql-finders"
+  s.version     = DataMapper::SQLFinders::VERSION
+  s.authors     = ['opensource_firespring']
+  s.email       = ['opensource@firespring.com']
+  s.homepage    = "https://github.com/d11wtq/dm-sql-finders"
+  s.summary     = %q{Query DataMapper models using raw SQL, without sacrificing property and table name abstraction}
+  s.description = %q{dm-sql-finders add #by_sql to your DataMapper models and provides a clean mechanism for using
+                     the names of the properties in your model, instead of the actual fields in the database. Any SQL
+                     is supported and actual DataMapper Query objects wrap the SQL, thus delaying its execution until
+                     a kicker method materializes the records for the query.  You can also chain standard DataMapper
+                     query methods onto the #by_sql call to refine the query.}
+  s.license = 'Nonstandard'
+
+  s.rubyforge_project = "dm-sql-finders"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  DM_VERSION ||= "~> 1.3"
+
+  s.add_runtime_dependency "sbf-dm-core",               DM_VERSION
+  s.add_runtime_dependency "sbf-dm-do-adapter",         DM_VERSION
+
+  s.add_development_dependency "rspec",             "~> 3.13"
+  s.add_development_dependency "sbf-dm-migrations",     DM_VERSION
+  s.add_development_dependency "sbf-dm-aggregates",     DM_VERSION
+  s.add_development_dependency "sbf-dm-sqlite-adapter", DM_VERSION
+end

data/lib/data_mapper/sql_finders/adapter.rb

@@ -0,0 +1,10 @@
+module DataMapper
+  class Adapters::DataObjectsAdapter
+    def select_statement_with_query(query)
+      SQLFinders::SQLBuilder.new(self, query).select_statement
+    end
+
+    alias_method :select_statement_without_query, :select_statement
+    alias_method :select_statement, :select_statement_with_query
+  end
+end

data/lib/data_mapper/sql_finders/query.rb

@@ -0,0 +1,74 @@
+require "forwardable"
+
+module DataMapper
+  module SQLFinders
+    class Query < DataMapper::Query
+      def sql=(parts, bind_values)
+        @sql_parts  = parts
+        @sql_values = bind_values
+      end
+
+      def sql
+        @sql_parts  ||= {}
+        @sql_values ||= []
+        return @sql_parts, @sql_values
+      end
+
+      def fields
+        return super if super.any? { |f| f.kind_of?(Operator) }
+        return super unless @sql_parts && @sql_parts.has_key?(:fields)
+
+        @sql_parts[:fields].map do |field|
+          if property = model.properties.detect { |p| p.field == field }
+            property
+          else
+            DataMapper::Property::String.new(model, field)
+          end
+        end
+      end
+
+      class DefaultDirection < Direction
+        extend Forwardable
+
+        def_delegators :@delegate, :target, :operator, :reverse!, :get
+
+        def initialize(delegate)
+          @delegate = delegate
+        end
+
+        def dup
+          self.class.new(@delegate.dup)
+        end
+      end
+    end
+  end
+
+  class Query
+    def normalize_order # temporary (will be removed in DM 1.3)
+      return if @order.nil?
+
+      @order = Array(@order)
+      @order = @order.map do |order|
+        case order
+          when Direction
+            order.dup
+
+          when Operator
+            target   = order.target
+            property = target.kind_of?(Property) ? target : @properties[target]
+
+            Direction.new(property, order.operator)
+
+          when Symbol, String
+            Direction.new(@properties[order])
+
+          when Property
+            Direction.new(order)
+
+          when Path
+            Direction.new(order.property)
+        end
+      end
+    end
+  end
+end

data/lib/data_mapper/sql_finders/sql_builder.rb

@@ -0,0 +1,86 @@
+module DataMapper
+  module SQLFinders
+    class SQLBuilder
+      def initialize(adapter, query)
+        @adapter                      = adapter
+        @query                        = query
+        @model                        = @query.model
+        @parts, @sql_values           = @query.respond_to?(:sql) ? @query.sql : [{}, []]
+        @fields                       = @query.fields
+        @conditions                   = @query.conditions
+        @qualify                      = @query.links.any? || !@parts[:from].nil?
+        @conditions_stmt, @qry_values = @adapter.send(:conditions_statement, @conditions, @qualify)
+        @order_by                     = @query.order
+        @limit                        = @query.limit
+        @offset                       = @query.offset
+        @bind_values                  = @sql_values + @qry_values
+        @group_by = if @query.unique?
+          @fields.select { |property| property.kind_of?(Property) && @model.properties[property.name] }
+        end
+      end
+
+      def select_statement
+        return @adapter.send(:select_statement_without_query, @query) unless @query.kind_of?(SQLFinders::Query)
+
+        statement = [
+          columns_fragment,
+          from_fragment,
+          join_fragment,
+          where_fragment,
+          group_fragment,
+          order_fragment
+        ].compact.join(" ")
+
+        @adapter.send(:add_limit_offset!, statement, @limit, @offset, @bind_values)
+
+        return statement, @bind_values
+      end
+
+      private
+
+      def columns_fragment
+        if @parts[:select] && @fields.none? { |f| f.kind_of?(DataMapper::Query::Operator) }
+          @parts[:select].strip
+        else
+          "SELECT #{@adapter.send(:columns_statement, @fields, @qualify)}"
+        end
+      end
+
+      def from_fragment
+        if @parts[:from]
+          @parts[:from].strip
+        else
+          "FROM #{@adapter.send(:quote_name, @model.storage_name(@adapter.name))}"
+        end
+      end
+
+      def join_fragment
+        @adapter.send(:join_statement, @query, @bind_values, @qualify) if @query.links.any?
+      end
+
+      def where_fragment
+        if @parts[:where]
+          [@parts[:where].strip, @conditions_stmt].reject{ |c| DataMapper::Ext.blank?(c) }.join(" AND ")
+        else
+          "WHERE #{@conditions_stmt}" unless DataMapper::Ext.blank?(@conditions_stmt)
+        end
+      end
+
+      def group_fragment
+        if @parts[:group_by]
+          @parts[:group_by].strip
+        else
+          "GROUP BY #{@adapter.send(:columns_statement, @group_by, @qualify)}" if @group_by && @group_by.any?
+        end
+      end
+
+      def order_fragment
+        if @parts[:order_by] && (@order_by.nil? || @order_by.all? { |o| o.kind_of?(Query::DefaultDirection) })
+          @parts[:order_by].strip
+        else
+          "ORDER BY #{@adapter.send(:order_statement, @order_by, @qualify)}" if @order_by && @order_by.any?
+        end
+      end
+    end
+  end
+end

data/lib/data_mapper/sql_finders/sql_parser.rb

@@ -0,0 +1,110 @@
+module DataMapper
+  module SQLFinders
+    class SQLParser
+      def initialize(sql)
+        @sql = sql.dup.to_s
+      end
+
+      def parse
+        tokens = {
+          :select       => "SELECT",
+          :from         => "FROM",
+          :where        => "WHERE",
+          :group_by     => "GROUP BY",
+          :having       => "HAVING",
+          :order_by     => "ORDER BY",
+          :limit_offset => "LIMIT"
+        }
+
+        parts = {}
+
+        tokens.each_with_index do |(key, initial), index|
+          parts[key] = scan_chunk(initial, tokens.values[(index + 1)..-1])
+        end
+
+        parse_fields!(parts)
+        parse_limit_offset!(parts)
+
+        parts
+      end
+
+      private
+
+      def scan_chunk(start_token, end_tokens)
+        scan_until(@sql, end_tokens) if @sql =~ /^\s*#{start_token}\b/i
+      end
+
+      def scan_until(str, tokens, include_delimiters = true)
+        delimiters = include_delimiters ? { "[" => "]", "(" => ")", "`" => "`", "'" => "'", '"' => '"', "--" => "\n", "/*" => "*/" } : { }
+        alternates = ["\\"]
+        alternates += delimiters.keys
+        alternates += tokens.dup
+        regex_body = alternates.map{ |v| v.kind_of?(Regexp) ? v.to_s : Regexp.escape(v) }.join("|")
+        pattern    = /^(?:#{regex_body}|.)/i
+
+        chunk = ""
+
+        while result = pattern.match(str)
+          token = result.to_s
+          case token
+            when "\\"
+              chunk << str.slice!(0, 2) # escape consumes following character, always
+            when *delimiters.keys
+              chunk << str.slice!(0, token.length) << scan_until(str, [delimiters[token]], false)
+            when *tokens
+              if include_delimiters
+                return chunk
+              else
+                return chunk << str.slice!(0, token.length)
+              end
+            else
+              chunk << str.slice!(0, token.length)
+          end
+        end
+
+        chunk
+      end
+
+      def parse_fields!(parts)
+        return unless fragment = parts[:select]
+
+        if m = /^\s*SELECT(?:\s+DISTINCT)?\s+(.*)/is.match(fragment)
+          full_fields_str = m[1].dup
+          fields_with_aliases = []
+          while full_fields_str.length > 0
+            fields_with_aliases << scan_until(full_fields_str, [","]).strip
+            full_fields_str.slice!(0, 1) if full_fields_str.length > 0
+          end
+          parts[:fields] = fields_with_aliases.collect { |f| extract_field_name(f) }
+        end
+      end
+
+      def extract_field_name(field)
+        # simple hack: the last token in a SELECT expression is always (conveniently) the alias, regardless of whether an AS is used, or an alias even given at all
+        full_str_rtl = field.dup.reverse
+        qualified_alias_str_rtl = scan_until(full_str_rtl, [/\s+/])
+        alias_str = scan_until(qualified_alias_str_rtl, ["."]).reverse
+        case alias_str[0]
+          when '"', '"', "`"
+            alias_str[1...-1].gsub(/\\(.)/, "\\1")
+          else
+            alias_str
+        end
+      end
+
+      def parse_limit_offset!(parts)
+        return unless fragment = parts[:limit_offset]
+
+        if m = /^\s*LIMIT\s+(\d+)\s*,\s*(\d+)/i.match(fragment)
+          parts[:limit]  = m[2].to_i
+          parts[:offset] = m[1].to_i
+        elsif m = /^\s*LIMIT\s+(\d+)\s+OFFSET\s+(\d+)/i.match(fragment)
+          parts[:limit]  = m[1].to_i
+          parts[:offset] = m[2].to_i
+        elsif m = /^\s*LIMIT\s+(\d+)/i.match(fragment)
+          parts[:limit]  = m[1].to_i
+        end
+      end
+    end
+  end
+end

data/lib/data_mapper/sql_finders/table_representation.rb

@@ -0,0 +1,49 @@
+module DataMapper
+  module SQLFinders
+    class TableRepresentation
+      class << self
+        def from_models(*models)
+          seen = {}
+          models.map do |model|
+            seen[model] ||= -1
+            new(model, seen[model] += 1)
+          end
+        end
+      end
+
+      def initialize(model, idx = 0)
+        @model = model
+        @idx   = idx
+      end
+
+      def to_s
+        @model.repository.adapter.send(:quote_name, @model.storage_name).dup.tap do |tbl|
+          tbl << " AS #{storage_alias}" unless tbl == storage_alias
+        end
+      end
+
+      def storage_alias
+        name = @model.storage_name.dup.tap do |name|
+          name << "_#{@idx}" if @idx > 0
+        end
+        @model.repository.adapter.send(:quote_name, name)
+      end
+
+      def *
+        @model.properties.map { |p| "#{storage_alias}.#{@model.repository.adapter.send(:quote_name, p.field)}" }.join(", ")
+      end
+
+      def method_missing(name, *args, &block)
+        return super unless args.size == 0 && !block_given?
+
+        if property = @model.properties[name]
+          "#{storage_alias}.#{@model.repository.adapter.send(:quote_name, property.field)}"
+        elsif @model.method_defined?(name)
+          @model.repository.adapter.send(:quote_name, name)
+        else
+          super
+        end
+      end
+    end
+  end
+end

data/lib/data_mapper/sql_finders/version.rb

@@ -0,0 +1,5 @@
+module DataMapper
+  module SQLFinders
+    VERSION = "0.0.4"
+  end
+end

data/lib/data_mapper/sql_finders.rb

@@ -0,0 +1,28 @@
+module DataMapper
+  module SQLFinders
+    def sql(*models)
+      raise ArgumentError, "Block required" unless block_given?
+      yield *TableRepresentation.from_models(*models)
+    end
+
+    def by_sql(*additional_models, &block)
+      options = if additional_models.last.kind_of?(Hash)
+        additional_models.pop
+      else
+        {}
+      end
+
+      sql, *bind_values = sql(self, *additional_models, &block)
+      parts = SQLParser.new(sql).parse
+
+      options[:limit]  ||= parts[:limit]  if parts[:limit]
+      options[:offset] ||= parts[:offset] if parts[:offset]
+
+      Collection.new(Query.new(repository, self, options).tap { |q| q.send(:sql=, parts, bind_values) })
+    end
+
+    def default_order(repository_name = default_repository_name)
+      Array(super).map { |d| Query::DefaultDirection.new(d) }.freeze
+    end
+  end
+end

data/lib/dm-sql-finders.rb

@@ -0,0 +1,11 @@
+require "dm-core"
+require "dm-do-adapter"
+require "data_mapper/sql_finders/sql_builder"
+require "data_mapper/sql_finders/sql_parser"
+require "data_mapper/sql_finders/table_representation"
+require "data_mapper/sql_finders/adapter"
+require "data_mapper/sql_finders/query"
+require "data_mapper/sql_finders/version"
+require "data_mapper/sql_finders"
+
+DataMapper::Model.append_extensions(DataMapper::SQLFinders)

data/spec/public/adapter_spec.rb

@@ -0,0 +1,331 @@
+require "spec_helper"
+
+describe DataMapper::Adapters::DataObjectsAdapter do
+  before(:each) do
+    @bob  = User.create(:username => "Bob",  :role => "Manager")
+    @fred = User.create(:username => "Fred", :role => "Tea Boy")
+  end
+
+  context "query without SQL" do
+    before(:each) do
+      @users = User.all(:username => "Bob")
+      @sql, @bind_values = User.repository.adapter.send(:select_statement, @users.query)
+    end
+
+    it "behaves unchanged" do
+      @users.to_a.count.should == 1
+      @users.to_a.first.should == @bob
+      @sql.should == %{SELECT "id", "username", "role" FROM "users" WHERE "username" = ? ORDER BY "id"}
+      @bind_values.should == ["Bob"]
+    end
+  end
+
+  context "querying by SQL" do
+    context "with a basic SELECT statement" do
+      before(:each) do
+        @users = User.by_sql { |u| ["SELECT #{u.*} FROM #{u} WHERE #{u.role} = ?", "Manager"] }
+        @sql, @bind_values = User.repository.adapter.send(:select_statement, @users.query)
+      end
+
+      it "executes the original query" do
+        @sql.should == %q{SELECT "users"."id", "users"."username", "users"."role" FROM "users" WHERE "users"."role" = ? ORDER BY "users"."id"}
+        @bind_values.should == ["Manager"]
+      end
+
+      it "finds the matching resources" do
+        @users.should include(@bob)
+      end
+
+      it "does not find incorrect resources" do
+        @users.should_not include(@fred)
+      end
+
+      describe "chaining" do
+        describe "to #all" do
+          before(:each) do
+            @jim   = User.create(:username => "Jim", :role => "Manager")
+            @users = @users.all(:username => "Jim")
+            @sql, @bind_values = User.repository.adapter.send(:select_statement, @users.query)
+          end
+
+          it "merges the conditions with the original SQL" do
+            @sql.should == %q{SELECT "users"."id", "users"."username", "users"."role" FROM "users" WHERE "users"."role" = ? AND "users"."username" = ? ORDER BY "users"."id"}
+            @bind_values.should == ["Manager", "Jim"]
+          end
+
+          it "finds the matching resources" do
+            @users.should include(@jim)
+          end
+
+          it "does not find incorrect resources" do
+            @users.should_not include(@bob)
+          end
+        end
+      end
+    end
+
+    describe "ordering" do
+      context "with an ORDER BY clause" do
+        before(:each) do
+          @users = User.by_sql { |u| "SELECT #{u.*} FROM #{u} ORDER BY #{u.username} DESC" }
+          @sql, @bind_values = User.repository.adapter.send(:select_statement, @users.query)
+        end
+
+        it "uses the order from the SQL" do
+          @sql.should == %q{SELECT "users"."id", "users"."username", "users"."role" FROM "users" ORDER BY "users"."username" DESC}
+        end
+
+        it "loads the resources in the correct order" do
+          @users.to_a.first.should == @fred
+          @users.to_a.last.should == @bob
+        end
+      end
+
+      context "with :order specified on the query" do
+        before(:each) do
+          @users = User.by_sql(:order => [:role.asc]) { |u| "SELECT #{u.*} FROM #{u}" }
+          @sql, @bind_values = User.repository.adapter.send(:select_statement, @users.query)
+        end
+
+        it "uses the order from the options" do
+          @sql.should == %q{SELECT "users"."id", "users"."username", "users"."role" FROM "users" ORDER BY "users"."role"}
+        end
+
+        it "loads the resources in the correct order" do
+          @users.to_a.first.should == @bob
+          @users.to_a.last.should == @fred
+        end
+      end
+
+      context "with both :order and an ORDER BY clause" do
+        before(:each) do
+          @users = User.by_sql(:order => [:role.desc]) { |u| "SELECT #{u.*} FROM #{u} ORDER BY #{u.username} ASC" }
+          @sql, @bind_values = User.repository.adapter.send(:select_statement, @users.query)
+        end
+
+        it "gives the :order option precendence" do
+          @sql.should == %q{SELECT "users"."id", "users"."username", "users"."role" FROM "users" ORDER BY "users"."role" DESC}
+        end
+      end
+
+      describe "chaining" do
+        describe "overriding a previous :order option" do
+          before(:each) do
+            @users = User.by_sql(:order => [:role.desc]) { |u| "SELECT #{u.*} FROM #{u}" }.all(:order => [:id.asc])
+            @sql, @bind_values = User.repository.adapter.send(:select_statement, @users.query)
+          end
+
+          specify "the last :order specified is used" do
+            @sql.should == %q{SELECT "users"."id", "users"."username", "users"."role" FROM "users" ORDER BY "users"."id"}
+          end
+        end
+
+        describe "overriding the order specified in the SQL" do
+          before(:each) do
+            @users = User.by_sql { |u| "SELECT #{u.*} FROM #{u} ORDER BY #{u.role} DESC" }.all(:order => [:id.asc])
+            @sql, @bind_values = User.repository.adapter.send(:select_statement, @users.query)
+          end
+
+          specify "the last :order specified is used" do
+            @sql.should == %q{SELECT "users"."id", "users"."username", "users"."role" FROM "users" ORDER BY "users"."id"}
+          end
+        end
+      end
+    end
+
+    describe "limits" do
+      context "with a limit specified by the SQL" do
+        before(:each) do
+          @users = User.by_sql { |u| "SELECT #{u.*} FROM #{u} LIMIT 1" }
+          @sql, @bind_values = User.repository.adapter.send(:select_statement, @users.query)
+        end
+
+        it "uses the limit from the SQL" do
+          @sql.should == %q{SELECT "users"."id", "users"."username", "users"."role" FROM "users" ORDER BY "users"."id" LIMIT ?}
+          @bind_values.should == [1]
+        end
+
+        it "finds the matching resources" do
+          expect(@users.to_a).not_to be_empty
+          @users.to_a.first.should == @bob
+        end
+      end
+
+      context "with a :limit option to #by_sql" do
+        before(:each) do
+          @users = User.by_sql(:limit => 1) { |u| "SELECT #{u.*} FROM #{u}" }
+          @sql, @bind_values = User.repository.adapter.send(:select_statement, @users.query)
+        end
+
+        it "uses the :limit option" do
+          @sql.should == %q{SELECT "users"."id", "users"."username", "users"."role" FROM "users" ORDER BY "users"."id" LIMIT ?}
+          @bind_values.should == [1]
+        end
+
+        it "finds the matching resources" do
+          expect(@users.to_a).not_to be_empty
+          @users.to_a.first.should == @bob
+        end
+      end
+
+      context "with both a :limit option and a LIMIT in the SQL" do
+        before(:each) do
+          @users = User.by_sql(:limit => 1) { |u| "SELECT #{u.*} FROM #{u} LIMIT 2" }
+          @sql, @bind_values = User.repository.adapter.send(:select_statement, @users.query)
+        end
+
+        it "the :limit option takes precedence" do
+          @sql.should == %q{SELECT "users"."id", "users"."username", "users"."role" FROM "users" ORDER BY "users"."id" LIMIT ?}
+          @bind_values.should == [1]
+        end
+      end
+
+      context "with an OFFSET in the SQL" do
+        before(:each) do
+          @users = User.by_sql { |u| "SELECT #{u.*} FROM #{u} LIMIT 1 OFFSET 1" }
+          @sql, @bind_values = User.repository.adapter.send(:select_statement, @users.query)
+        end
+
+        it "uses the offset from the SQL" do
+          @sql.should == %q{SELECT "users"."id", "users"."username", "users"."role" FROM "users" ORDER BY "users"."id" LIMIT ? OFFSET ?}
+          @bind_values.should == [1, 1]
+        end
+
+        it "finds the matching resources" do
+          expect(@users.to_a).not_to be_empty
+          @users.to_a.first.should == @fred
+        end
+      end
+
+      context "with an argument to LIMIT in the SQL" do
+        before(:each) do
+          @users = User.by_sql { |u| "SELECT #{u.*} FROM #{u} LIMIT 1, 2" }
+          @sql, @bind_values = User.repository.adapter.send(:select_statement, @users.query)
+        end
+
+        it "interprets the offset in the SQL" do
+          @sql.should == %q{SELECT "users"."id", "users"."username", "users"."role" FROM "users" ORDER BY "users"."id" LIMIT ? OFFSET ?}
+          @bind_values.should == [2, 1]
+        end
+      end
+
+      context "with an :offset option to #by_sql" do
+        before(:each) do
+          @users = User.by_sql(:offset => 1) { |u| "SELECT #{u.*} FROM #{u} LIMIT 1" }
+          @sql, @bind_values = User.repository.adapter.send(:select_statement, @users.query)
+        end
+
+        it "uses the offset from the options hash" do
+          @sql.should == %q{SELECT "users"."id", "users"."username", "users"."role" FROM "users" ORDER BY "users"."id" LIMIT ? OFFSET ?}
+          @bind_values.should == [1, 1]
+        end
+
+        it "finds the matching resources" do
+          expect(@users.to_a).not_to be_empty
+          @users.to_a.first.should == @fred
+        end
+      end
+
+      context "with both an OFFSET in the SQL and an :offset option" do
+        before(:each) do
+          @users = User.by_sql(:offset => 1) { |u| "SELECT #{u.*} FROM #{u} LIMIT 1 OFFSET 0" }
+          @sql, @bind_values = User.repository.adapter.send(:select_statement, @users.query)
+        end
+
+        it "the :offset in the options takes precendence" do
+          @sql.should == %q{SELECT "users"."id", "users"."username", "users"."role" FROM "users" ORDER BY "users"."id" LIMIT ? OFFSET ?}
+          @bind_values.should == [1, 1]
+        end
+      end
+
+      describe "chaining" do
+        describe "to override a previous :limit option" do
+          before(:each) do
+            @users = User.by_sql(:limit => 2) { |u| "SELECT #{u.*} FROM #{u}" }.all(:limit => 1)
+            @sql, @bind_values = User.repository.adapter.send(:select_statement, @users.query)
+          end
+
+          it "the last :limit option takes precedence" do
+            @sql.should == %q{SELECT "users"."id", "users"."username", "users"."role" FROM "users" ORDER BY "users"."id" LIMIT ?}
+            @bind_values.should == [1]
+          end
+        end
+
+        describe "to override a limit applied in SQL" do
+          before(:each) do
+            @users = User.by_sql { |u| "SELECT #{u.*} FROM #{u} LIMIT 1" }.all(:limit => 2)
+            @sql, @bind_values = User.repository.adapter.send(:select_statement, @users.query)
+          end
+
+          it "the last :limit option takes precedence" do
+            @sql.should == %q{SELECT "users"."id", "users"."username", "users"."role" FROM "users" ORDER BY "users"."id" LIMIT ?}
+            @bind_values.should == [2]
+          end
+        end
+      end
+    end
+
+    context "with an INNER JOIN" do
+      before(:each) do
+        @bobs_post  = @bob.posts.create(:title => "Bob can write posts")
+        @freds_post = @fred.posts.create(:title => "Fred likes to write too")
+
+        @posts = Post.by_sql(User) { |p, u| ["SELECT #{p.*} FROM #{p} INNER JOIN #{u} ON #{p.user_id} = #{u.id} WHERE #{u.id} = ?", @bob.id] }
+        @sql, @bind_values = Post.repository.adapter.send(:select_statement, @posts.query)
+      end
+
+      it "executes the original query" do
+        @sql.should == %q{SELECT "posts"."id", "posts"."title", "posts"."user_id" FROM "posts" INNER JOIN "users" ON "posts"."user_id" = "users"."id" WHERE "users"."id" = ? ORDER BY "posts"."id"}
+        @bind_values.should == [@bob.id]
+      end
+
+      it "finds the matching resources" do
+        @posts.should include(@bobs_post)
+      end
+
+      it "does not find incorrect resources" do
+        @posts.should_not include(@freds_post)
+      end
+
+      context "to the same table" do
+        before(:each) do
+          @posts = Post.by_sql(Post) { |p1, p2| "SELECT #{p1.*} FROM #{p1} INNER JOIN #{p2} ON #{p1.id} = #{p2.id}" }
+          @sql, @bind_values = Post.repository.adapter.send(:select_statement, @posts.query)
+        end
+
+        it "creates alises for the subsequent tables" do
+          @sql.should == %q{SELECT "posts"."id", "posts"."title", "posts"."user_id" FROM "posts" INNER JOIN "posts" AS "posts_1" ON "posts"."id" = "posts_1"."id" ORDER BY "posts"."id"}
+        end
+      end
+    end
+
+    describe "aggregate queries" do
+      it "supports calculating counts" do
+        User.by_sql { |u| "SELECT #{u.*} FROM #{u}" }.count(:id).should == 2
+      end
+
+      it "supports multiple aggregates" do
+        User.by_sql { |u| "SELECT #{u.*} FROM #{u}" }.aggregate(:id.count, :id.min, :username.max).should == [2, 1, "Fred"]
+      end
+    end
+
+    describe "with virtual attributes" do
+      before(:each) do
+        @bob.posts.create(:title => "Test")
+        @users = User.by_sql(Post) { |u, p| "SELECT #{u.*}, COUNT(#{p.id}) AS #{u.post_count} FROM #{u} INNER JOIN #{p} ON #{p.user_id} = #{u.id}" }
+      end
+
+      it "loads the virtual attributes" do
+        @users.to_a.first.post_count.should == 1
+      end
+    end
+
+    # fixed an obscure bug with state leakage here
+    describe "#reverse!" do
+      it "is consistent between invocations" do
+        User.all.query.reverse.order.first.operator.should == :desc
+        User.all.query.reverse.order.first.operator.should == :desc
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,22 @@
+require "dm-migrations"
+require "dm-aggregates"
+require "dm-sql-finders"
+
+DataMapper.setup(:default, "sqlite::memory:")
+
+Dir[File.join(File.dirname(__FILE__), "support/**/*.rb")].each { |file| require file }
+
+RSpec.configure do |config|
+  config.mock_with :rspec
+
+  config.before(:suite) do
+    DataMapper.finalize
+  end
+
+  config.before(:each) do
+    DataMapper.auto_migrate!
+  end
+
+  config.after(:each) do
+  end
+end

data/spec/support/fixtures/post.rb

@@ -0,0 +1,8 @@
+class Post
+  include DataMapper::Resource
+
+  property :id,    Serial
+  property :title, String
+
+  belongs_to :user
+end

data/spec/support/fixtures/user.rb

@@ -0,0 +1,13 @@
+class User
+  include DataMapper::Resource
+
+  property :id,       Serial
+  property :username, String
+  property :role,     String
+
+  has n, :posts
+
+  def post_count
+    @post_count.to_i
+  end
+end

metadata

@@ -0,0 +1,156 @@
+--- !ruby/object:Gem::Specification
+name: sbf-dm-sql-finders
+version: !ruby/object:Gem::Version
+  version: 0.0.4
+platform: ruby
+authors:
+- opensource_firespring
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-01-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sbf-dm-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: sbf-dm-do-adapter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: sbf-dm-migrations
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: sbf-dm-aggregates
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: sbf-dm-sqlite-adapter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+description: |-
+  dm-sql-finders add #by_sql to your DataMapper models and provides a clean mechanism for using
+                       the names of the properties in your model, instead of the actual fields in the database. Any SQL
+                       is supported and actual DataMapper Query objects wrap the SQL, thus delaying its execution until
+                       a kicker method materializes the records for the query.  You can also chain standard DataMapper
+                       query methods onto the #by_sql call to refine the query.
+email:
+- opensource@firespring.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- dm-sql-finders.gemspec
+- lib/data_mapper/sql_finders.rb
+- lib/data_mapper/sql_finders/adapter.rb
+- lib/data_mapper/sql_finders/query.rb
+- lib/data_mapper/sql_finders/sql_builder.rb
+- lib/data_mapper/sql_finders/sql_parser.rb
+- lib/data_mapper/sql_finders/table_representation.rb
+- lib/data_mapper/sql_finders/version.rb
+- lib/dm-sql-finders.rb
+- spec/public/adapter_spec.rb
+- spec/spec_helper.rb
+- spec/support/fixtures/post.rb
+- spec/support/fixtures/user.rb
+homepage: https://github.com/d11wtq/dm-sql-finders
+licenses:
+- Nonstandard
+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: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Query DataMapper models using raw SQL, without sacrificing property and table
+  name abstraction
+test_files:
+- spec/public/adapter_spec.rb
+- spec/spec_helper.rb
+- spec/support/fixtures/post.rb
+- spec/support/fixtures/user.rb