wise_gopher 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7568e5308f8025d5b1f9d9cf2a869a6560b6a0377aed7ca3a79c063c5abe76ec
+  data.tar.gz: cd076d93f65ff85e50c4279e67604b7ba4caa6811390bdc1bbdba48197d8e50c
+SHA512:
+  metadata.gz: 7a0d433f7e6c9dbabde1505caaa3b9a0c9318462969458d873280e0bd567c28724172fa1779f1b3163ca7334c8be2b189af9691c27654f1a26f9fc9f77e5ad57
+  data.tar.gz: 1517fed4b04a5c50640d8824fb9e97827905163c26155e5841dc733ef3349d3f5d27de31f8168f05bb2c9442782075cd71968edb8a42783fed61787dc6154625

data/.github/workflows/main.yml

@@ -0,0 +1,16 @@
+name: Ruby
+
+on: [push,pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: 2.6.6
+        bundler-cache: true
+    - name: Run the default task
+      run: bundle exec rake

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,37 @@
+require:
+  - rubocop-rake
+  - rubocop-rspec
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 2.5
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120
+Layout/DotPosition:
+  EnforcedStyle: trailing
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+Layout/HashAlignment:
+  EnforcedHashRocketStyle: table
+  EnforcedColonStyle: table
+
+RSpec/MultipleExpectations:
+  Enabled: false
+RSpec/NestedGroups:
+  Max: 4
+
+Lint/MissingSuper:
+  Enabled: false
+
+Naming/MethodParameterName:
+  AllowedNames:
+    - as

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2021-06-22
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,84 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at pierregabriel@me.com. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior,  harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0,
+available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,101 @@
+PATH
+  remote: .
+  specs:
+    wise_gopher (0.1.0)
+      activerecord (>= 5, < 7)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (6.1.4)
+      activesupport (= 6.1.4)
+    activerecord (6.1.4)
+      activemodel (= 6.1.4)
+      activesupport (= 6.1.4)
+    activesupport (6.1.4)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+      zeitwerk (~> 2.3)
+    ast (2.4.2)
+    byebug (11.1.3)
+    coderay (1.1.3)
+    concurrent-ruby (1.1.9)
+    database_cleaner (1.99.0)
+    diff-lcs (1.4.4)
+    i18n (1.8.10)
+      concurrent-ruby (~> 1.0)
+    method_source (1.0.0)
+    minitest (5.14.4)
+    parallel (1.20.1)
+    parser (3.0.1.1)
+      ast (~> 2.4.1)
+    pry (0.14.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    pry-byebug (3.8.0)
+      byebug (~> 11.0)
+      pry (~> 0.10)
+    pry-doc (1.1.0)
+      pry (~> 0.11)
+      yard (~> 0.9.11)
+    rainbow (3.0.0)
+    rake (13.0.3)
+    regexp_parser (2.1.1)
+    rexml (3.2.5)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.1)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.2)
+    rubocop (1.17.0)
+      parallel (~> 1.10)
+      parser (>= 3.0.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.7.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.7.0)
+      parser (>= 3.0.1.1)
+    rubocop-rake (0.5.1)
+      rubocop
+    rubocop-rspec (2.4.0)
+      rubocop (~> 1.0)
+      rubocop-ast (>= 1.1.0)
+    ruby-progressbar (1.11.0)
+    sqlite3 (1.4.2)
+    tzinfo (2.0.4)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (2.0.0)
+    yard (0.9.26)
+    zeitwerk (2.4.2)
+
+PLATFORMS
+  x86_64-linux
+
+DEPENDENCIES
+  database_cleaner (~> 1.5)
+  pry
+  pry-byebug
+  pry-doc
+  rake (~> 13.0)
+  rspec (~> 3.10)
+  rubocop (~> 1.7)
+  rubocop-rake
+  rubocop-rspec
+  sqlite3
+  wise_gopher!
+
+BUNDLED WITH
+   2.2.20

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Pierre Gabriel
+
+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,232 @@
+# WiseGopher
+
+Why is the gopher wise ? Because it knows one should not use raw SQL with ActiveRecord without being mindful about security and performance !
+
+This gem tries to solve some problems found when you need to execute custom and/or complex SQL queries for which returned data doesn't match your ActiveRecord models:
+
+1. ActiveRecord doesn't make it easy to use bind parameters with [`exec_query`](https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/DatabaseStatements.html#method-i-exec_query). It needs a lot of build up to pass arguments for your query.
+2. The result of query is return as an array of hashes wich deprive us of good old OOP.
+3. The column types are not always correctly retrieved by ActiveRecord, or sometimes you need a little more ruby treatment on the value before using it.
+
+[This article](https://blog.saeloun.com/2019/10/28/bind-parameters-in-activerecord-sql-queries.html) describe the benefits of using bind parameters with ActiveRecord.
+[This one](https://use-the-index-luke.com/sql/where-clause/bind-parameters) goes further one the subject.
+
+The basic idea of this gem is to provide you a way to declare what your query needs as input, what columns it returns and their type. In returns it will allow you to retrieve the rows from result as an array of plain Ruby objects. It will also dynamically creates a class for the row objects that you can customize or can provide it yourself.
+
+
+NB : This is my very first gem, any suggestions, feedbacks or bug reports are very welcome ! 😃
+
+------
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'wise_gopher'
+```
+
+And then execute:
+
+    bundle install
+
+Or install it yourself as:
+
+    gem install wise_gopher
+
+------
+
+## Usage
+> DISCLAIMER: for the sake of example, the queries presented here can be very simple and would obviously match an ActiveRecord model. For such queries I would of course highly recommend to use basic ActiveRecord.
+---
+
+To use WiseGopher you have to create a class to declare your query and its specifications. It could look like this:
+
+```ruby
+class PopularArticle < WiseGopher::Base
+  query <<-SQL
+    SELECT title, AVG(ratings.stars) AS average_rating, published_at, author_username
+    FROM articles
+    INNER JOIN ratings ON ratings.article_id = articles.id
+    WHERE author_username = {{ username }}
+    GROUP BY articles.id
+    HAVING average_rating > {{ mininum_rating }}
+    ORDER BY averating_rating
+  SQL
+  
+  param :minimum_rating, :integer
+  param :username, :string, transform: :strip
+  
+  row do
+    column :title, :string, transform: :capitalize
+    column :average_rating, :float, -> { round(2) }
+    column :published_at, :datetime
+    column :author_username, as: :author
+    
+    def to_s
+        "Article '#{title}' by #{author} is rated #{"%.2f" % average_rating}/5."
+    end
+  end
+end
+```
+
+Which you would use this way:
+```ruby
+result = PopularArticle.execute_with(minimum_rating: 3, username: "PageHey ")
+# => [#<PopularArticle::Row:0x0000560c37e9de48 @title="My first gem is out!", @average_rating=3.5 ...>, ...]
+puts result.first
+# => Article 'My first gem is out!' by PageHey is rated 3.5/5.
+result.first.class
+# => PopularArticle::Row
+```
+
+------
+
+So, basically what you need to do is make your class inherits from `WiseGopher::Base` and provide your SQL with `.query`. You can then declare what columns will be present in result with `.column` in a block given to `row`.
+
+
+If your query doesn't need any parameter like this one:
+```ruby
+class PopularArticle < WiseGopher::Base
+    query "SELECT title FROM articles"
+    
+    row do
+        column :title, :string
+    end
+end
+```
+You can simply get result with `.execute`:
+```ruby
+PopularArticle.execute
+```
+
+If your query **does need** parameter like this one:
+```ruby
+class PopularArticle < WiseGopher::Base
+    query <<-SQL
+        SELECT title FROM articles
+        WHERE author = {{ author_name }} AND published_at > {{ published_after }}
+    SQL
+    
+    param :author_name, :string
+    param :published_after, :date
+    
+    row do
+        column :title, :string
+    end
+end
+```
+You should declare the params with `.param` so you can pass the parameters as a hash to `.execute_with`:
+```ruby
+PopularArticle.execute_with(author_name: "PageHey", published_after: Date.today - 1.month)
+```
+
+If any parameter is missing or if you call `.execute` for a class that needs some, it will raise `WiseGopher::ArgumentError`.
+
+Before query execution, the placeholders will be replaced with the standard `?` placeholder or with the `$1`, `$2` ... numbered placeholders for PostgreSQL database.
+
+To declare the column in result, you should use `.row` and pass it a block. Calling this method will create a `Row` class nested into your query class. The block will be then executed in `Row` class context. In this context you can use `.column` but also define method, include module, basicaly write any code you would find in a class delacration.
+
+The goal of this syntax is to gather in the same file the input and output logic of the query while keeping dedicated classes for each logic.
+You can provide a custom class to `.row` if you prefer. If you still pass the block to the method, the `WiseGopher::Row` module will be included in the class before evaluating it, so you can have this syntax:
+```ruby
+_/my_custom_row.rb_
+class MyCustomRow
+    def some_custom_method
+        # [...]
+    end
+end
+
+_/my_query_class.rb
+class MyQueryClass < WiseGopher::Base
+    query "SELECT title FROM articles"
+    
+    row MyCustomRow do
+        column :title, :string
+    end
+end
+```
+
+**If you don't give any block to `.row`, make sure you include `WiseGopher::Row` in your class.**
+
+
+------
+## Methods documentation
+### WiseGopher::Base (class)
+#### .param
+```ruby
+param(name, type, transform: nil)
+```
+
+Argument | Required | Descrition
+------------ | ------------- | ------------- 
+name | true | The name of the parameter as written in the `{{ placeholder }}`
+type | true | The type of the column. It can be any type registred as ActiveRecord::Type. Including yours
+transform: | false | `Proc` or `Symbol`. An operation that will be call before creating the bind parameter when you call `.execute_with`.
+
+###  WiseGopher::Row (module)
+#### .column
+```ruby
+column(name, type, transform: nil, as: nil)
+```
+
+Argument | Required | Descrition
+------------ | ------------- | ------------- 
+name | true | The name (or alias) of the SQL column as written in the SELECT statement
+type | true | The type of the column. It can be any type registred as ActiveRecord::Type. Including yours
+transform: | false | `Proc` or `Symbol`. An operation that will be call on value while initializing the row object (See tips below).
+as: | false | The name of the getter you want on the row instance for this column (getter with original name won't be created!)
+
+------
+## Tips
+#### transform: argument as proc
+If you provide a proc to the `transform:` argument (either on `.column` or `.param`), you can expect one argument or none. If one argument is expected the value of the param or column will be passed.
+
+#### Prepare query for later execution
+You can prepare the query with param without executing it by simply calling `.new` on your class and providing the params an later call `.execute`.
+```ruby
+class PopularArticle < WiseGopher::Base
+    query <<-SQL
+        SELECT title FROM articles
+        WHERE published_at > {{ published_after }}
+    SQL
+    
+    param :published_after, :date
+    
+    row do
+        column :title, :string
+    end
+end
+last_month_articles = PopularArticle.new(published_after: Date.today - 1.month)
+# [...]
+last_month_articles.execute # => [#<PopularArticle::Row:0x0000560c37e9de48 ...>]
+```
+
+#### Ignore column in result
+If for some reason, you have a column in your result that you don't want to retrieve on the row instances, you can use `.ignore`.
+```ruby
+class MyQuery < WiseGopher::Base
+    query "SELECT title, rating FROM articles"
+    
+    row do
+        column :title, :string
+        ignore :rating
+    end
+end
+
+MyQuery.execute # => no error raised
+```
+
+------
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/pagehey/wise_gopher. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/pagehey/wise_gopher/blob/master/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the WiseGopher project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/pagehey/wise_gopher/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/bin/console

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "wise_gopher"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+require "pry-doc"
+
+require_relative "../spec/database_helper"
+
+class Object
+  # includes database helpers as top level methods
+  include DatabaseHelper
+end
+
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/wise_gopher.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "wise_gopher/version"
+require_relative "wise_gopher/base"
+require_relative "wise_gopher/column"
+require_relative "wise_gopher/param"
+require_relative "wise_gopher/row"
+require_relative "wise_gopher/errors"
+
+require "active_record"
+
+# base module
+module WiseGopher
+  def self.postgresql?
+    ActiveRecord::Base.connection.adapter_name.casecmp? "PostgreSQL"
+  end
+end

data/lib/wise_gopher/base.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module WiseGopher
+  # Main inteface of the gem. Class to be inherited by the query class
+  class Base
+    def self.inherited(base)
+      base.class_eval do
+        @params = {}
+      end
+      base.include Methods
+      base.extend  ClassMethods
+    end
+
+    # class methods for WiseGopher::Base
+    module ClassMethods
+      attr_reader :row_class, :params
+
+      def query(query)
+        const_set "QUERY", query.freeze
+      end
+
+      def param(name, type, transform = nil)
+        param = WiseGopher::Param.new(name, type, transform)
+
+        params[param.name] = param
+      end
+
+      def row(base = nil, &block)
+        @row_class ||= base || define_generic_row_class
+
+        @row_class.include WiseGopher::Row
+
+        @row_class.class_eval(&block) if block_given?
+      end
+
+      def execute
+        ensure_all_params_are_given
+
+        new.execute
+      end
+
+      def execute_with(inputs)
+        ensure_all_params_are_given(inputs)
+
+        new(inputs).execute
+      end
+
+      private
+
+      def define_generic_row_class
+        @row_class = const_set "Row", Class.new
+      end
+
+      def ensure_all_params_are_given(inputs = {})
+        missing_params = params.keys - inputs.keys.map(&:to_s)
+
+        raise WiseGopher::ArgumentError, params.slice(*missing_params) if missing_params.any?
+      end
+    end
+
+    # instance methods for WiseGopher::Base
+    module Methods
+      extend ::Forwardable
+
+      def_delegator :query_class, :row_class
+
+      def initialize(inputs = {})
+        @inputs         = inputs
+        @binds          = []
+        @bind_symbol    = WiseGopher.postgresql? ? +"$1" : "?"
+        @query_prepared = false
+
+        prepare_query
+      end
+
+      def execute
+        ensure_row_class_is_declared
+
+        result = connection.exec_query(@query.squish, query_class.to_s, @binds, prepare: true)
+
+        ensure_all_columns_are_declared(result)
+
+        result.entries.map { |entry| row_class.new(entry) }
+      end
+
+      def prepare_query
+        return if @query_prepared
+
+        @query = query_class::QUERY.dup
+
+        query_class.params.each do |name, param|
+          name  = name.to_sym
+          value = @inputs[name]
+
+          bind_params(value, param)
+        end
+
+        @query_prepared = true
+      end
+
+      private
+
+      def query_class
+        self.class
+      end
+
+      def bind_params(value, param)
+        if value.is_a? Array
+          bind_collection_param(value, param)
+        else
+          bind_single_param(value, param)
+        end
+      end
+
+      def bind_collection_param(values, param)
+        bindings = values.map { use_bind_symbol }
+
+        replace_binding_placeholder(param.name, bindings.join(", "))
+
+        values.each { |value| register_binding(value, param) }
+      end
+
+      def bind_single_param(value, param)
+        replace_binding_placeholder(param.name, use_bind_symbol)
+
+        register_binding(value, param)
+      end
+
+      def replace_binding_placeholder(name, binding_symbol)
+        @query.gsub!(/{{ ?#{name} ?}}/, binding_symbol)
+      end
+
+      def register_binding(value, param)
+        @binds << param.build_bind(value)
+      end
+
+      def use_bind_symbol
+        if WiseGopher.postgresql?
+          symbol = @bind_symbol.dup
+
+          @bind_symbol.next!
+
+          symbol
+        else
+          @bind_symbol
+        end
+      end
+
+      def ensure_row_class_is_declared
+        raise RowClassIsMissing unless row_class
+      end
+
+      def ensure_all_columns_are_declared(result)
+        undeclared_columns = result.columns - row_class.columns.keys - row_class.ignored_columns
+
+        raise UndeclaredColumns, undeclared_columns if undeclared_columns.any?
+      end
+
+      def connection
+        ActiveRecord::Base.connection
+      end
+    end
+  end
+end

data/lib/wise_gopher/column.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module WiseGopher
+  # Cast query columns and transform value
+  class Column
+    attr_reader :name, :type, :alias
+
+    def initialize(name, type_symbol, transform: nil, as: nil)
+      @alias     = as&.to_s.freeze || name.to_s.freeze
+      @name      = name.to_s.freeze
+      @type      = ActiveRecord::Type.lookup type_symbol
+      @transform = transform&.to_proc
+    end
+
+    def cast(value)
+      casted_value = @type.deserialize(value)
+
+      @transform ? transform_value(casted_value) : casted_value
+    end
+
+    def define_getter(row_class)
+      column = self
+
+      row_class.define_method(@alias) do
+        instance_variable_get(column.instance_variable_name)
+      end
+    end
+
+    def instance_variable_name
+      @instance_variable_name ||= "@#{@alias.tr("?!", "")}"
+    end
+
+    private
+
+    def transform_value(value)
+      case @transform.arity
+      when 0 then value.instance_exec(&@transform)
+      else
+        value.instance_eval(&@transform)
+      end
+    end
+  end
+end

data/lib/wise_gopher/errors.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module WiseGopher
+  # Base exception class
+  class Error < StandardError; end
+
+  # raised when `execute` is called whereas query needs params
+  # or `execute_with` did not provide all params
+  class ArgumentError < Error
+    attr_reader :params
+
+    def initialize(params)
+      @params = params.map do |name, param|
+        "- \"#{name}\" (#{param.type.type})"
+      end.join("\n")
+    end
+
+    def message
+      <<~STR
+        \n
+        The following params are required but were not provided:
+        #{params}
+      STR
+    end
+  end
+
+  # raised when result contains more columns than declared
+  class UndeclaredColumns < Error
+    attr_reader :column_names
+
+    def initialize(column_names)
+      @column_names = column_names.map do |name|
+        "- \"#{name}\""
+      end.join("\n")
+    end
+
+    def message
+      <<~STR
+        \n
+        The following columns where found in result but were not declared:
+        #{column_names}
+
+        If you need them during query execution but not in result,
+        you should ignore them, like this:
+
+        class Query < WiseGopher::Base
+          query "SELECT title, rating FROM articles"
+
+          row do
+            column :title, :string
+            ignore :rating
+          end
+        end
+      STR
+    end
+  end
+
+  # raised when row is not declared or not given
+  class RowClassIsMissing < Error
+  end
+
+  # raised when custom row class is given but doesn't include WiseGopher::Row
+  class RowClassNeedsRowModule < Error
+  end
+end
+
+# connection;
+# class Query < WiseGopher::Base
+#   query "SELECT title, rating FROM articles"
+
+#   row do
+#     column :title, :string
+#   end
+# end; Query.execute

data/lib/wise_gopher/param.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module WiseGopher
+  # Register query's params and build query's bind variables
+  class Param
+    attr_reader :name, :type
+
+    def initialize(name, type_symbol, transform = nil)
+      @name      = name.to_s.freeze
+      @type      = ActiveRecord::Type.lookup type_symbol
+      @transform = transform&.to_proc
+    end
+
+    def build_bind(value)
+      prepared_value = @transform ? transform_value(value) : value
+
+      ActiveRecord::Relation::QueryAttribute.new(name, prepared_value, type)
+    end
+
+    private
+
+    def transform_value(value)
+      case @transform.arity
+      when 0 then value.instance_exec(&@transform)
+      else
+        value.instance_eval(&@transform)
+      end
+    end
+  end
+end

data/lib/wise_gopher/row.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module WiseGopher
+  # This Module handles the declartion of row's columns of query result
+  # and defines the getters for row objects
+  module Row
+    def self.included(base)
+      base.class_eval do
+        @columns         = {}
+        @ignored_columns = []
+      end
+
+      base.extend(ClassMethods)
+    end
+
+    # Row class methods
+    module ClassMethods
+      attr_reader :columns, :ignored_columns
+
+      def column(name, type, **kwargs)
+        column = WiseGopher::Column.new(name, type, **kwargs)
+
+        column.define_getter(self)
+
+        columns[column.name] = column
+      end
+
+      def ignore(column_name)
+        @ignored_columns << column_name.to_s.freeze
+      end
+    end
+
+    def initialize(entry)
+      self.class.columns.each do |name, column|
+        variable_name = column.instance_variable_name.freeze
+
+        instance_variable_set(variable_name, column.cast(entry[name]))
+      end
+    end
+  end
+end

data/lib/wise_gopher/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module WiseGopher
+  module VERSION
+    MAJOR = 0
+    MINOR = 1
+    PATCH = 0
+
+    STRING = [MAJOR, MINOR, PATCH].join(".")
+  end
+end

data/wise_gopher.gemspec

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "lib/wise_gopher/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "wise_gopher"
+  spec.version       = WiseGopher::VERSION::STRING
+  spec.authors       = ["PageHey"]
+  spec.email         = ["pagehey@pm.me"]
+
+  spec.summary       = "Encapsulate raw SQL queries and return result as plain Ruby objects, using ActiveRecord."
+  spec.description   = <<~STR
+    Instead of using `ActiveRecord::Base.connection.execute("some raw sql ...")`,
+    use WiseGopher to delcare your queries as classes,
+    ensure sql injection protection
+    and retrieve results as plain Ruby object with dedicated class instead of raw values in hashes or arrays.
+  STR
+  spec.homepage              = "https://github.com/Pagehey/wise_gopher"
+  spec.license               = "MIT"
+  spec.required_ruby_version = ">= 2.5.0"
+
+  spec.metadata["homepage_uri"]    = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/Pagehey/wise_gopher"
+  spec.metadata["changelog_uri"]   = "https://github.com/Pagehey/wise_gopher/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activerecord", ">= 5", "< 7"
+
+  spec.add_development_dependency "database_cleaner", "~> 1.5"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "pry-byebug"
+  spec.add_development_dependency "pry-doc"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.10"
+  spec.add_development_dependency "rubocop", "~> 1.7"
+  spec.add_development_dependency "rubocop-rake"
+  spec.add_development_dependency "rubocop-rspec"
+  spec.add_development_dependency "sqlite3"
+end

metadata

@@ -0,0 +1,232 @@
+--- !ruby/object:Gem::Specification
+name: wise_gopher
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- PageHey
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2021-06-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
+- !ruby/object:Gem::Dependency
+  name: database_cleaner
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry-doc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.10'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  Instead of using `ActiveRecord::Base.connection.execute("some raw sql ...")`,
+  use WiseGopher to delcare your queries as classes,
+  ensure sql injection protection
+  and retrieve results as plain Ruby object with dedicated class instead of raw values in hashes or arrays.
+email:
+- pagehey@pm.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/main.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/wise_gopher.rb
+- lib/wise_gopher/base.rb
+- lib/wise_gopher/column.rb
+- lib/wise_gopher/errors.rb
+- lib/wise_gopher/param.rb
+- lib/wise_gopher/row.rb
+- lib/wise_gopher/version.rb
+- wise_gopher.gemspec
+homepage: https://github.com/Pagehey/wise_gopher
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Pagehey/wise_gopher
+  source_code_uri: https://github.com/Pagehey/wise_gopher
+  changelog_uri: https://github.com/Pagehey/wise_gopher/blob/main/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Encapsulate raw SQL queries and return result as plain Ruby objects, using
+  ActiveRecord.
+test_files: []