README.md in search_cop-1.0.9 vs README.md in search_cop-1.1.0
- old
+ new
@@ -1,10 +1,9 @@
# SearchCop
[](http://travis-ci.org/mrkamel/search_cop)
[](https://codeclimate.com/github/mrkamel/search_cop)
-[](https://gemnasium.com/mrkamel/search_cop)
[](http://badge.fury.io/rb/search_cop)
SearchCop extends your ActiveRecord models to support fulltext search
@@ -116,10 +115,28 @@
```ruby
Book.where(available: true).search("Harry Potter").order("books.id desc").paginate(page: params[:page])
```
+## Security
+
+When you pass a query string to SearchCop, it gets parsed, analyzed and mapped
+to finally build up an SQL query. To be more precise, when SearchCop parses the
+query, it creates objects (nodes), which represent the query expressions (And-,
+Or-, Not-, String-, Date-, etc Nodes). To build the SQL query, SearchCop uses
+the concept of visitors like e.g. used in
+[Arel](https://github.com/rails/arel), such that, for every node there must be
+a [visitor](https://github.com/mrkamel/search_cop/blob/master/lib/search_cop/visitors/visitor.rb),
+which transforms the node to SQL. When there is no visitor, an exception is
+raised when the query builder tries to "visit" the node. The visitors are
+responsible for sanitizing the user supplied input. This is primilarly done via
+quoting (string-, table-name-, column-quoting, etc). SearchCop is using the
+methods provided by the ActiveRecord connection adapter for sanitizing/quoting
+to prevent SQL injection. While we can never be 100% safe from security issues,
+SearchCop takes security issues seriously. Please report responsibly via
+security at flakks dot com in case you find any security related issues.
+
## Fulltext index capabilities
By default, i.e. if you don't tell SearchCop about your fulltext indices,
SearchCop will use `LIKE '%...%'` queries. Unfortunately, unless you
create a [trigram index](http://www.postgresql.org/docs/9.1/static/pgtrgm.html)
@@ -281,11 +298,11 @@
## Other indices
In case you expose non-fulltext attributes to search queries (price, stock,
etc.), the respective queries, like `Book.search("stock > 0")`, will profit
-from from the usual non-fulltext indices. Thus, you should add a usual index on
+from the usual non-fulltext indices. Thus, you should add a usual index on
every column you expose to search queries plus a fulltext index for every
fulltext attribute.
In case you can't use fulltext indices, because you're e.g. still on MySQL 5.5
while using InnoDB or another RDBMS without fulltext support, you can make your
@@ -310,10 +327,45 @@
```ruby
User.search("admin")
# ... WHERE users.username LIKE 'admin%'
```
+## Default operator
+
+When you define multiple fields on a search scope, SearcCop will use
+by default the AND operator to concatenate the conditions, e.g:
+
+```ruby
+class User < ActiveRecord::Base
+ include SearchCop
+
+ search_scope :search do
+ attributes :username, :fullname
+ end
+
+ # ...
+end
+```
+
+So a search like `User.search("something")` will generate a query
+with the following conditions:
+
+```sql
+... WHERE username LIKE '%something%' AND fullname LIKE '%something%'
+```
+
+However, there are cases where using AND as the default operator is not desired,
+so SearchCop allows you to override it and use OR as the default operator instead.
+A query like `User.search("something", default_operator: :or)` will
+generate the query using OR to concatenate the conditions
+
+```sql
+... WHERE username LIKE '%something%' OR fullname LIKE '%something%'
+```
+
+Finally, please note that you can apply it to fulltext indices/queries as well.
+
## Associations
If you specify searchable attributes from another model, like
```ruby
@@ -451,9 +503,13 @@
SearchCop also provides the ability to define custom operators by defining a
`generator` in `search_scope`. They can then be used with the hash based query
search. This is useful when you want to use database operators that are not
supported by SearchCop.
+
+Please note, when using generators, you are responsible for sanitizing/quoting
+the values (see example below). Otherwise your generator will allow SQL
+injection. Thus, please only use generators if you know what you're doing.
For example, if you wanted to perform a `LIKE` query where a book title starts
with a string, you can define the search scope like so:
```ruby