find_by_sql_file 0.9.9

data/MIT-LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2008 Jordi Bunster <jordi@bunster.org>
+
+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.rdoc

@@ -0,0 +1,95 @@
+= Find by SQL file
+
+This plugin extends the API of ActiveRecord::Base#find_by_sql
+
+== A Warning
+
+Besides the warnings on the +ERB+ section below (don't ignore those), this
+code has very little production track record. So there, beware.
+
+== Example Usage
+
+Instead of passing the SQL statement as a string...
+
+  Elephant.find_by_sql "SELECT * FROM elephants WHERE weight='massive'"
+
+You can pass a symbol that refers to a query file:
+
+  Elephant.find_by_sql :massive_weight
+
+Query files are assumed to be save as:
+
+  Rails.root/app/queries/TABLE_NAME/SYMBOL.sql
+
+== Installation instructions
+
+Via rubygems:
+
+  gem install find_by_sql_file
+
+  # Rails 2.x (config/environment.rb)
+  config.gem 'find_by_sql_file'
+
+  # Rails 3.x (Gemfile)
+  gem 'find_by_sql_file'
+
+  # Or, to use outside of Rails, for now (better API coming soon):
+  require 'active_record'
+  RAILS_ROOT = '/some/folder/'
+  require 'find_by_sql_file'
+
+== Motivation
+
+The advantage of the external file approach is that the SQL file can be
+properly indented and commented (the indentation and comments are stripped
+from the logs.)
+
+== Features & Problems
+
+=== Comment removal
+
+As far as comment removal, only double-dash-space single-line comments are
+stripped, like so:
+
+  SELECT foo, -- We need this for X reason
+         bar, -- and this for some Y reason
+         bez,  # This comment will NOT be removed, and will be a problem
+         duh  /* And neither will this one. Use -- style only */
+
+         FROM table;
+
+So, to clarify, the start-comment marker is '-- ' (two dashes and a space).
+That I know of, this marker works in MySQL, PostgreSQL, SQLite, Oracle, DB2,
+and SQL Server. While not all of these require the space after the dashes,
+it never hurts.
+
+=== Bind variables
+
+It's possible to pass named bind variables, much like in the conditions
+parameter of ActiveRecord::Base.find, by passing a hash as the second
+parameter, like so:
+
+  Elephant.find_by_sql :specifics, :color => 'grey', :weight => 6800
+
+=== ERB (be careful)
+
+It is also possible to use +ERB+ inside the query file, but *beware!*
+Unlike the named bind variables, any data passed in via the ERB method is not
+properly quoted by the database adapter, leaving open the possibility of
+*SQL injection*. 99.9% of the time, *you will _NOT_ need this*.
+
+Here's an artificial (but easy to explain) example of how the
+(very dangerous!) +ERB+ _feature_ works:
+
+  Elephant.find_by_sql :single_value, :value   => 'grey',
+                                      :inject! => { :field => 'color' }
+
+The call above replaces the bind variable +value+ inside the SQL file,
+but it also populates the instance variable +field+ with "+color+", which
+can then be used with the usual ERB syntax, like so:
+
+  SELECT <%= @field -%> FROM elephants WHERE <%= @field -%> = :value
+
+== Legal
+
+Copyright (c) 2008..2010 Jordi Bunster, released under the MIT license

data/Rakefile

@@ -0,0 +1,42 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the find_by_sql_file plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the find_by_sql_file plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'FindBySqlFile'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include 'README.rdoc'
+  rdoc.rdoc_files.include 'lib/**/*.rb'
+end
+
+namespace :rcov do
+  begin
+    require 'rcov/rcovtask'
+  rescue LoadError
+    desc '(Not installed!)'
+    task :build do
+      puts "Install 'rcov' to get test coverage reports."
+    end
+  else
+    Rcov::RcovTask.new(:build) do |t|
+      t.test_files = %w[ test/*_test.rb ]
+      t.output_dir = 'coverage'
+      t.verbose    = true
+      t.rcov_opts  << '-x /Library -x ~/.gem -x /usr --html'
+    end
+  end
+end
+
+task :rcov => :'rcov:build'

data/WHATSNEW

@@ -0,0 +1,12 @@
+* 0.9.9 (2010-02-21):
+
+  - Changed the comment marker to be '-- ' (two dashes and a space)
+  - Tested under Ruby 1.8.7 and 1.9.1
+  - Tested under ActiveRecord 2.3 and 3.0beta
+
+* 0.9.5 (2008-10-06):
+
+  - Added a WHATSNEW file :)
+  - Added a few behaviour tests
+  - Added ActiveRecord::Base#find_one_by_sql(*args) as sugar for
+    ActiveRecord::Base#find_by_sql(*args).first

data/find_by_sql_file.gemspec

@@ -0,0 +1,45 @@
+Gem::Specification.new do |s|
+  s.name        = 'find_by_sql_file'
+  s.version     = '0.9.9'
+  s.date        = '2010-2-21'
+
+  s.author      = 'Jordi Bunster'
+  s.email       = 'jordi@bunster.org'
+  s.homepage    = 'http://github.com/jordi/find_by_sql_file'
+
+  s.summary     = "Extension to ActiveRecord's find_by_sql to use SQL files"
+  s.description = %{ This ActiveRecord extension lets you pass a symbol to
+                     ActiveRecord::Base#find_by_sql, which refers to a query
+                     file saved under app/queries/. Variable replacement
+                     and ERB are available, and comments and indentation are
+                     stripped. }.strip!.gsub! /\s+/, ' '
+
+  s.test_files  = %w[
+    test
+    test/find_by_sql_file_test.rb
+    test/rails_root_fixture
+    test/rails_root_fixture/app
+    test/rails_root_fixture/app/queries
+    test/rails_root_fixture/app/queries/articles
+    test/rails_root_fixture/app/queries/articles/all.sql
+    test/rails_root_fixture/app/queries/articles/count_all.sql
+    test/rails_root_fixture/app/queries/articles/last_updated.sql
+    test/rails_root_fixture/app/queries/articles/with_erb_fields.sql
+    test/rails_root_fixture/app/queries/articles/with_variables.sql
+    test/test_helper.rb
+  ]
+
+  s.files = %w[ MIT-LICENSE
+                README.rdoc
+                Rakefile
+                WHATSNEW
+                find_by_sql_file.gemspec
+                lib
+                lib/find_by_sql_file.rb
+                rails
+                rails/init.rb ]
+
+  s.has_rdoc         = true
+  s.extra_rdoc_files = %w[ README.rdoc        ]
+  s.rdoc_options     = %w[ --main README.rdoc ]
+end

data/lib/find_by_sql_file.rb

@@ -0,0 +1,64 @@
+require 'erb'
+require 'active_record'
+
+module FindBySqlFile
+  # This makes it a tad simpler to create a clean ERB binding context. It
+  # works like so:
+  #
+  # ERBJacket.wrap "A Foo is: <%= @foo -%>", :foo => 'not a bar'
+  #
+  class ERBJacket
+    def initialize(hash) # :nodoc:
+      hash.each { |k, v| instance_variable_set('@' + k.to_s, v) }
+    end
+
+    def wrap(erb_template) # :nodoc:
+      ::ERB.new(erb_template, nil, '-').result binding
+    end
+
+    def self.wrap(erb_template = '', instance_variables = {}) # :nodoc:
+      new(instance_variables).wrap erb_template
+    end
+  end
+
+  def find_by_sql_with_sql_file(query_or_symbol, opts = {}) # :nodoc:
+    find_by_sql_without_sql_file sql_file(query_or_symbol, opts)
+  end
+
+  def count_by_sql_with_sql_file(query_or_symbol, opts = {}) # :nodoc:
+    count_by_sql_without_sql_file sql_file(query_or_symbol, opts)
+  end
+
+  def sql_file(query_or_symbol, opts = {}) # :nodoc:
+    if query_or_symbol.is_a? Symbol
+
+      file_name = Rails.root.join 'app', 'queries',
+        (table_name rescue 'application'), (query_or_symbol.to_s + '.sql')
+
+      bound_variables = HashWithIndifferentAccess.new(opts).symbolize_keys!
+      injected_locals = bound_variables.delete(:inject!) || []
+
+      query = ERBJacket.wrap File.read(file_name), injected_locals
+      query = replace_named_bind_variables(query, bound_variables)
+
+      query.gsub(/-- .*/, '').strip.gsub(/\s+/, ' ')
+    else
+      raise 'Additional parameters only supported when using a query' \
+            ' file (pass a symbol, not a string)' unless opts.blank?
+
+      query_or_symbol
+    end
+  end
+
+  # The equivalent of ActiveRecord::Base#find_by_sql(*args).first
+  def find_one_by_sql(*args)
+    find_by_sql(*args).first
+  end
+end
+
+class << ActiveRecord::Base
+  include FindBySqlFile
+
+  alias_method_chain :find_by_sql,  :sql_file
+  alias_method_chain :count_by_sql, :sql_file
+end

data/rails/init.rb

@@ -0,0 +1 @@
+require File.join(File.dirname(__FILE__), '..', 'lib', 'find_by_sql_file')

data/test/find_by_sql_file_test.rb

@@ -0,0 +1,73 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+class Article < ActiveRecord::Base
+end
+
+class FindBySqlFileTest < Test::Unit::TestCase
+
+  def test_counting_by_sql_file
+    assert_equal Article.count_by_sql(:count_all), Article.count
+  end
+
+  def test_find_all
+    assert_equal Article.find_by_sql(:all), Article.find(:all)
+  end
+
+  def test_find_last_updated
+    assert_equal Article.find_one_by_sql(:last_updated),
+                 Article.find(:first, :order => 'updated_at DESC')
+  end
+
+  def test_named_bind_variables
+    assert_equal Article.find_by_sql(:with_variables,
+                   :published  => @articles.last.published,
+                   :created_on => @articles.last.created_on),
+                 Article.find(:all, :conditions => {
+                   :published  => @articles.last.published,
+                   :created_on => @articles.last.created_on })
+  end
+
+  def test_erb_injection
+    fields = 'id, title, published'
+
+    assert_equal(
+      Article.find_by_sql(:with_erb_fields,
+        :inject! => { :select => fields }).map  { |a| a.attributes },
+      Article.find(:all, :select => fields).map { |a| a.attributes } )
+  end
+
+  def test_query_reformatting
+    assert_equal 'SELECT * FROM articles ORDER BY updated_at DESC LIMIT 1',
+                 Article.sql_file(:last_updated)
+  end
+
+  def setup
+    @articles = []
+
+    @articles << Article.new(:title      => 'Lorem ipsum dolor sit amet',
+                             :published  => true,
+                             :created_on => '1969-01-27',
+                             :updated_at => '2008-10-06 12:02:32')
+
+    @articles << Article.new(:title      => 'Consectetur adipisicing elit',
+                             :published  => false,
+                             :created_on => '1969-12-30',
+                             :updated_at => '2008-10-06 12:02:32')
+
+    @articles << Article.new(:title      => 'Sed do eiusmod tempor incididunt',
+                             :published  => false,
+                             :created_on => '1969-01-15',
+                             :updated_at => '2008-10-06 12:02:32')
+
+    @articles << Article.new(:title      => 'Ut enim ad minim veniam',
+                             :published  => false,
+                             :created_on => '1999-12-13',
+                             :updated_at => '2012-10-06 12:02:32')
+
+    @articles.each { |a| a.save }
+  end
+
+  def teardown
+    Article.delete_all
+  end
+end

data/test/rails_root_fixture/app/queries/articles/all.sql

@@ -0,0 +1,3 @@
+-- This query gets all of the articles
+SELECT * FROM articles
+

data/test/rails_root_fixture/app/queries/articles/count_all.sql

@@ -0,0 +1,2 @@
+-- Count all of the articles using SQL
+SELECT COUNT(*) FROM articles

data/test/rails_root_fixture/app/queries/articles/last_updated.sql

@@ -0,0 +1,3 @@
+SELECT * FROM articles
+  ORDER BY updated_at DESC -- Gets the last one updated
+  LIMIT 1

data/test/rails_root_fixture/app/queries/articles/with_erb_fields.sql

@@ -0,0 +1,3 @@
+-- Gets certain fields from articles using ERB to pass the SELECT fragment
+
+SELECT <%= @select -%> FROM articles

data/test/rails_root_fixture/app/queries/articles/with_variables.sql

@@ -0,0 +1,4 @@
+-- Gets articles with given values for 'created_on' and 'published'
+
+SELECT * FROM articles WHERE created_on = :created_on
+                         AND published  = :published

data/test/test_helper.rb

@@ -0,0 +1,30 @@
+require 'test/unit'
+require 'yaml'
+require 'pathname'
+require 'rubygems'
+
+begin
+  require 'leftright'
+rescue LoadError
+  puts "Install the 'leftright' gem (optional) to get awesome test output"
+end
+
+module Rails
+  def self.root
+    Pathname.new File.join(File.dirname(__FILE__), 'rails_root_fixture')
+  end
+end
+
+require 'find_by_sql_file'
+
+ActiveRecord::Base.establish_connection :adapter  => 'sqlite3',
+                                        :database => ':memory:'
+
+ActiveRecord::Schema.define :version => 1 do
+  create_table :articles, :force => true do |article|
+    article.string    :title
+    article.boolean   :published
+    article.date      :created_on
+    article.timestamp :updated_at
+  end
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification 
+name: find_by_sql_file
+version: !ruby/object:Gem::Version 
+  version: 0.9.9
+platform: ruby
+authors: 
+- Jordi Bunster
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-02-21 00:00:00 -05:00
+default_executable: 
+dependencies: []
+
+description: This ActiveRecord extension lets you pass a symbol to ActiveRecord::Base#find_by_sql, which refers to a query file saved under app/queries/. Variable replacement and ERB are available, and comments and indentation are stripped.
+email: jordi@bunster.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- MIT-LICENSE
+- README.rdoc
+- Rakefile
+- WHATSNEW
+- find_by_sql_file.gemspec
+- lib/find_by_sql_file.rb
+- rails/init.rb
+has_rdoc: true
+homepage: http://github.com/jordi/find_by_sql_file
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Extension to ActiveRecord's find_by_sql to use SQL files
+test_files: 
+- test/find_by_sql_file_test.rb
+- test/rails_root_fixture/app/queries/articles/all.sql
+- test/rails_root_fixture/app/queries/articles/count_all.sql
+- test/rails_root_fixture/app/queries/articles/last_updated.sql
+- test/rails_root_fixture/app/queries/articles/with_erb_fields.sql
+- test/rails_root_fixture/app/queries/articles/with_variables.sql
+- test/test_helper.rb