Support custom queries in builder (#403)

* initial implementation

* fix single replacement

* implement custom SQL method for OR builder

* document where with SQL string

* Tweak where documentation

* Make custom where value optional

* specify database placeholders

* Add tests for raw SQL #where, #and, #or

* Make SQL placeholders DB specific

Author: Serdnad

docs/querying.md

@@ -16,6 +16,16 @@ Post.where(:created_at, :gt, Time.local - 7.days)
 
 Supported operators are :eq, :gteq, :lteq, :neq, :gt, :lt, :nlt, :ngt, :ltgt, :in, :nin, :like, :nlike
 
+Alternatively, `#where`, `#and`, and `#or` accept a raw SQL clause, with an optional placeholder (`?` for MySQL/SQLite, `$` for Postgres) to avoid SQL Injection.
+```crystal
+# Example using Postgres adapter
+Post.where(:created_at, :gt, Time.local - 7.days)
+  .where("LOWER(author_name) = $", name)
+  .where("tags @> '{"Journal", "Book"}') # PG's array contains operator
+```
+This is useful for building more sophisticated queries, including queries dependent on database specific features not supported by the operators above. However, **clauses built with this method are not validated.**
+
+
 ## Order
 
 Order is using the QueryBuilder and supports providing an ORDER BY clause:

spec/granite/query/assemblers/mysql_spec.cr

@@ -76,6 +76,16 @@ require "../spec_helper"
         assembler.where
         assembler.numbered_parameters.should eq [] of Granite::Columns::Type
       end
+
+      it "handles raw SQL" do
+        sql = "select #{query_fields} from table where name = 'bob' and age = ? and color = ? order by id desc"
+        query = builder.where("name = 'bob'").where("age = ?", 23).where("color = ?", "red")
+        query.raw_sql.should match ignore_whitespace sql
+
+        assembler = query.assembler
+        assembler.where
+        assembler.numbered_parameters.should eq [23, "red"]
+      end
     end
 
     context "order" do

spec/granite/query/assemblers/pg_spec.cr

@@ -76,6 +76,16 @@ require "../spec_helper"
         assembler.where
         assembler.numbered_parameters.should eq [] of Granite::Columns::Type
       end
+
+      it "handles raw SQL" do
+        sql = "select #{query_fields} from table where name = 'bob' and age = $1 and color = $2 order by id desc"
+        query = builder.where("name = 'bob'").where("age = $", 23).where("color = $", "red")
+        query.raw_sql.should match ignore_whitespace sql
+
+        assembler = query.assembler
+        assembler.where
+        assembler.numbered_parameters.should eq [23, "red"]
+      end
     end
 
     context "order" do

spec/granite/query/assemblers/sqlite_spec.cr

@@ -76,6 +76,16 @@ require "../spec_helper"
         assembler.where
         assembler.numbered_parameters.should eq [] of Granite::Columns::Type
       end
+
+      it "handles raw SQL" do
+        sql = "select #{query_fields} from table where name = 'bob' and age = ? and color = ? order by id desc"
+        query = builder.where("name = 'bob'").where("age = ?", 23).where("color = ?", "red")
+        query.raw_sql.should match ignore_whitespace sql
+
+        assembler = query.assembler
+        assembler.where
+        assembler.numbered_parameters.should eq [23, "red"]
+      end
     end
 
     context "order" do

spec/granite/query/builder_spec.cr

@@ -47,4 +47,36 @@ describe Granite::Query::Builder(Model) do
     query = builder.offset(17)
     query.offset.should eq 17
   end
+
+  context "raw SQL builder" do
+    placeholders = {
+      Granite::Query::Builder::DbType::Mysql  => "?",
+      Granite::Query::Builder::DbType::Sqlite => "?",
+      Granite::Query::Builder::DbType::Pg     => "$",
+    }
+
+    it "chains where statements" do
+      placeholder = placeholders[builder.db_type]
+      query = builder.where("name = #{placeholder}", "bob").where("age = #{placeholder}", 23)
+      expected = [{join: :and, stmt: "name = #{placeholder}", value: "bob"}, {join: :and, stmt: "age = #{placeholder}", value: 23}]
+
+      query.where_fields.should eq expected
+    end
+
+    it "chains and statements" do
+      placeholder = placeholders[builder.db_type]
+      query = builder.where("name = #{placeholder}", "bob").and("age = #{placeholder}", 23)
+      expected = [{join: :and, stmt: "name = #{placeholder}", value: "bob"}, {join: :and, stmt: "age = #{placeholder}", value: 23}]
+
+      query.where_fields.should eq expected
+    end
+
+    it "chains or statements" do
+      placeholder = placeholders[builder.db_type]
+      query = builder.where("name = #{placeholder}", "bob").or("age = #{placeholder}", 23)
+      expected = [{join: :and, stmt: "name = #{placeholder}", value: "bob"}, {join: :or, stmt: "age = #{placeholder}", value: 23}]
+
+      query.where_fields.should eq expected
+    end
+  end
 end

src/granite/query/assemblers/base.cr

@@ -1,5 +1,6 @@
 module Granite::Query::Assembler
   abstract class Base(Model)
+    @placeholder : String = ""
     @where : String?
     @order : String?
     @limit : String?
@@ -41,26 +42,40 @@ module Granite::Query::Assembler
       clauses = ["WHERE"]
 
       @query.where_fields.each do |expression|
-        add_aggregate_field expression[:field]
-
         clauses << expression[:join].to_s.upcase unless clauses.size == 1
 
-        if expression[:value].nil?
-          clauses << "#{expression[:field]} IS NULL"
-        elsif expression[:value].is_a?(Array)
-          in_stmt = String.build do |str|
-            str << '('
-            expression[:value].as(Array).each_with_index do |val, idx|
-              str << '\'' if expression[:value].is_a?(Array(String))
-              str << val
-              str << '\'' if expression[:value].is_a?(Array(String))
-              str << ',' if expression[:value].as(Array).size - 1 != idx
+        if expression[:field]?.nil? # custom SQL
+          expression = expression.as(NamedTuple(join: Symbol, stmt: String, value: Granite::Columns::Type))
+
+          if !expression[:value].nil?
+            param_token = add_parameter expression[:value]
+            clause = expression[:stmt].gsub(@placeholder, param_token)
+          else
+            clause = expression[:stmt]
+          end
+
+          clauses << clause
+        else # standard where query
+          expression = expression.as(NamedTuple(join: Symbol, field: String, operator: Symbol, value: Granite::Columns::Type))
+          add_aggregate_field expression[:field]
+
+          if expression[:value].nil?
+            clauses << "#{expression[:field]} IS NULL"
+          elsif expression[:value].is_a?(Array)
+            in_stmt = String.build do |str|
+              str << '('
+              expression[:value].as(Array).each_with_index do |val, idx|
+                str << '\'' if expression[:value].is_a?(Array(String))
+                str << val
+                str << '\'' if expression[:value].is_a?(Array(String))
+                str << ',' if expression[:value].as(Array).size - 1 != idx
+              end
+              str << ')'
             end
-            str << ')'
+            clauses << "#{expression[:field]} #{sql_operator(expression[:operator])} #{in_stmt}"
+          else
+            clauses << "#{expression[:field]} #{sql_operator(expression[:operator])} #{add_parameter expression[:value]}"
           end
-          clauses << "#{expression[:field]} #{sql_operator(expression[:operator])} #{in_stmt}"
-        else
-          clauses << "#{expression[:field]} #{sql_operator(expression[:operator])} #{add_parameter expression[:value]}"
         end
       end
 

src/granite/query/assemblers/mysql.cr

@@ -2,6 +2,8 @@
 # This will likely require adapter specific subclassing :[.
 module Granite::Query::Assembler
   class Mysql(Model) < Base(Model)
+    @placeholder = "?"
+
     def add_parameter(value : Granite::Columns::Type) : String
       @numbered_parameters << value
       "?"

src/granite/query/assemblers/pg.cr

@@ -2,6 +2,8 @@
 # This will likely require adapter specific subclassing :[.
 module Granite::Query::Assembler
   class Pg(Model) < Base(Model)
+    @placeholder = "$"
+
     def add_parameter(value : Granite::Columns::Type) : String
       @numbered_parameters << value
       "$#{@numbered_parameters.size}"

src/granite/query/assemblers/sqlite.cr

@@ -1,5 +1,7 @@
 module Granite::Query::Assembler
   class Sqlite(Model) < Base(Model)
+    @placeholder = "?"
+
     def add_parameter(value : Granite::Columns::Type) : String
       @numbered_parameters << value
       "?"

src/granite/query/builder.cr

@@ -28,7 +28,8 @@ class Granite::Query::Builder(Model)
   end
 
   getter db_type : DbType
-  getter where_fields = [] of NamedTuple(join: Symbol, field: String, operator: Symbol, value: Granite::Columns::Type)
+  getter where_fields = [] of (NamedTuple(join: Symbol, field: String, operator: Symbol, value: Granite::Columns::Type) |
+                               NamedTuple(join: Symbol, stmt: String, value: Granite::Columns::Type))
   getter order_fields = [] of NamedTuple(field: String, direction: Sort)
   getter group_fields = [] of NamedTuple(field: String)
   getter offset : Int64?
@@ -70,6 +71,10 @@ class Granite::Query::Builder(Model)
     and(field: field.to_s, operator: operator, value: value)
   end
 
+  def where(stmt : String, value : Granite::Columns::Type = nil)
+    and(stmt: stmt, value: value)
+  end
+
   def and(**matches)
     and(matches)
   end
@@ -88,6 +93,12 @@ class Granite::Query::Builder(Model)
     self
   end
 
+  def and(stmt : String, value : Granite::Columns::Type = nil)
+    @where_fields << {join: :and, stmt: stmt, value: value}
+
+    self
+  end
+
   def or(**matches)
     or(matches)
   end
@@ -106,6 +117,12 @@ class Granite::Query::Builder(Model)
     self
   end
 
+  def or(stmt : String, value : Granite::Columns::Type = nil)
+    @where_fields << {join: :or, stmt: stmt, value: value}
+
+    self
+  end
+
   def order(field : Symbol)
     @order_fields << {field: field.to_s, direction: Sort::Ascending}