querier 0.4.4 → 0.4.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17df356b959c87427cc72225d58d40a38a0e7ad8ba7c0f4f15ceab9c603176eb
-  data.tar.gz: 0a6286066f90301cd9cf433ad118afe10ab49015fb839a5a7a38233f3821f48d
+  metadata.gz: 9288e68d9c81a85ddd04dbac7bda54ed629dc5bcbf3862828234b416646b31e1
+  data.tar.gz: 9776a4f2a9d025f4b30c1c41c91e04213d767f696879b1507d27b34210e87617
 SHA512:
-  metadata.gz: 92d410ee75923192069927f59609ba491424f672475eda7cc96d333e6ef0ef7f2f1fcab485c4c7463d2e216ce95b660f6a598abdc4591c5a84980395e02a5cef
-  data.tar.gz: 5e1a04e6e19141b75cae7c9c1ac547b0e0b0bc07d61c0f19800619480743be123d60f218621bf9d6b833f54cb0d1b9d5ee50bc1168370ddc27532a9748eb6588
+  metadata.gz: 105265c744ee14f48a2f410839f4c6d075ec1a38a739c83275a86caf34ff24a17cb1270f1e0f01c6cf601cab741a75abfdb64976179ac2e8fb379f5b85703a28
+  data.tar.gz: 9d33bef69465070fc629b524004664fca7e256cc7dcc1a6c975a2349aaf8e9d192748fd596015e08714957feda9f8dbc61225186f8d3b35cab513d405d7f7689

data/README.md

@@ -1,15 +1,85 @@
-# Querier
+# Querier Class for ActiveRecord Custom SQL Queries
 
-Active Record query executer utility.
+This README explains the functionality and use of the `Querier` class, designed to facilitate the construction and execution of custom SQL queries in a Ruby on Rails environment using ActiveRecord.
+
+## Module: `QuerierDatasetExtensions`
+
+The `QuerierDatasetExtensions` module extends the results returned by SQL queries with utility methods for easy data transformation:
+
+- `as_hash`: Converts each record into a hash with symbolized keys, making it easier to work with the data.
+- `as_struct`: Converts each record into an `OpenStruct` instance, allowing attribute access using dot notation.
+
+## Class: `Querier`
+
+The `Querier` class is designed to simplify the execution of custom SQL queries on a specific ActiveRecord model. Below are the detailed explanations of its components:
+
+### 1. Class Variable and Singleton Attribute
+
+The class uses a singleton attribute (`@active_record_class`) to maintain a reference to the ActiveRecord class that will be used to execute queries.
+
+Instead of using class variables (`@@`), which are generally discouraged due to inheritance and concurrency issues, the implementation uses the recommended approach of using singleton class attributes with `attr_accessor` defined within the `class << self` context.
+
+### 2. Attributes and Initialization
+
+- **`@query_params`**: Stores the parameters that will be used to fill in the query template.
+- **`@active_record_class`**: Initialized with the ActiveRecord class defined by the class or superclass. This allows the `Querier` class to be reused for different ActiveRecord models.
+
+### 3. Public Execution Methods
+
+The `Querier` class provides several methods to execute SQL queries, wrapping the ActiveRecord connection methods:
+
+- `execute`: Executes the query without returning structured records.
+- `exec_query`: Executes the query and returns results as an `ActiveRecord::Result`, extended with the `QuerierDatasetExtensions` module.
+- `select_all`, `select_one`, `select_rows`, `select_values`, `select_value`: These methods provide different formats for returning the query results, such as all records, a single record, rows, values, or a specific value.
+
+### 4. Filling Query Parameters (`fill_query_params`)
+
+The private `fill_query_params` method is responsible for parameter interpolation within the `@query_template`.
+
+- There are two types of placeholders for parameters in the query:
+  - `${param_name}`: This placeholder is replaced by the parameter value, escaped using the ActiveRecord connection's `quote` method to prevent SQL injection.
+  - `${param_name/no_quote}`: This placeholder substitutes the value directly without escaping, which is useful when the value is not susceptible to SQL injection (e.g., column names).
+
+### Security Considerations
+
+- The use of `${param_name/no_quote}` should be done cautiously, as it may introduce vulnerabilities if used with unvalidated inputs. It is recommended to restrict its use to validated column names only.
+
+### Error Handling
+
+Currently, there is no error handling. Adding a `begin-rescue` block in the execution methods could improve robustness, handling issues such as connection failures or SQL syntax errors gracefully.
+
+### Query Template Separation
+
+The `@query_template` is not explicitly defined in the provided code. It is recommended to use subclasses or clearly pass a query template, following good design practices to reuse query templates effectively.
+
+### Interface Improvement
+
+Adding methods that accept queries directly as arguments could make the class more flexible and easier to use in scenarios where a dynamic query is needed.
+
+## Example Usage
+
+Below is an example of how to use the `Querier` class:
 
 ```ruby
-class UserQuerier < Querier
-  @active_record_class = ApplicationRecord  
-  def initialize user_name:, active:  
-    @query_template = "SELECT * FROM users WHERE name = ${user_name} AND active = ${active/no_quote}"
+class MyCustomQuery < Querier
+  QUERY_TEMPLATE = <<-END_TEMPLATE
+  SELECT * FROM users WHERE id = ${user_id}
+  END_TEMPLATE
+
+  def initialize(user_id)
+    @query_template = QUERY_TEMPLATE
     super
   end
 end
 
-UserQuerier.new(user_name: 'foo', active: true)select_all.to_struct
-```
+query = MyCustomQuery.new(1)
+result = query.select_one
+puts result # => Returns the user record with id 1
+```
+
+This example demonstrates how the `Querier` class can be used to create specific queries for different purposes, making it easier to organize and reuse SQL queries.
+
+## Summary
+
+The `Querier` class provides a convenient way to build and execute custom SQL queries while keeping the process organized. It also enables centralized control for constructing and executing SQL within the context of ActiveRecord. The addition of the `QuerierDatasetExtensions` module further enhances the ease of transforming and using query results.
+

data/lib/querier.rb

@@ -1,5 +1,10 @@
 require 'active_record'
 
+module QuerierDatasetExtensions
+  def as_hash = map(&:symbolize_keys)
+  def as_struct = map { |record| OpenStruct.new(record) }
+end
+
 class Querier
   @active_record_class = ActiveRecord::Base
   # based on rubocop's tips at: https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Style/ClassVars
@@ -17,21 +22,15 @@ class Querier
   end
 
   def execute = @active_record_class.connection.execute(@query)
-  def exec_query = decorate_dataset_format(@active_record_class.connection.exec_query(@query))
-  def select_all = decorate_dataset_format(@active_record_class.connection.select_all(@query))
+  def exec_query = @active_record_class.connection.exec_query(@query).extend(QuerierDatasetExtensions)
+  def select_all = @active_record_class.connection.select_all(@query).extend(QuerierDatasetExtensions)
   def select_one = @active_record_class.connection.select_one(@query)
-  def select_values = @active_record_class.connection.select_values(@query)
   def select_rows = @active_record_class.connection.select_rows(@query)
+  def select_values = @active_record_class.connection.select_values(@query)
   def select_value = @active_record_class.connection.select_value(@query)
 
   private
 
-  def decorate_dataset_format(dataset)
-    def dataset.as_hash = map(&:symbolize_keys)
-    def dataset.as_struct = map { |record| OpenStruct.new(record) }
-    dataset
-  end
-
   def fill_query_params
     query = @query_template.dup
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: querier
 version: !ruby/object:Gem::Version
-  version: 0.4.4
+  version: 0.4.5
 platform: ruby
 authors:
 - Gedean Dias
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-10-03 00:00:00.000000000 Z
+date: 2024-10-04 00:00:00.000000000 Z
 dependencies: []
 description: Active Record queries with variable number of params
 email: gedean.dias@gmail.com