Class: Kweerie::Base

Inherits:
Object
  • Object
show all
Defined in:
lib/kweerie/base.rb

Direct Known Subclasses

BaseObject

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.bindings ⇒ Object (readonly)

Returns the value of attribute bindings.



49
50
51
 
# File 'lib/kweerie/base.rb', line 49

def bindings
  @bindings
end

Class Method Details

.all ⇒ Object

Raises:

  • (ArgumentError) 


153
154
155
156
157
 
# File 'lib/kweerie/base.rb', line 153

def all
  raise ArgumentError, "Cannot use .all on queries with bindings. Use .with instead." if bindings.any?

  with
end

.bind(param_name, as:) ⇒ Object

Parameter Binding

Binds a parameter to a SQL placeholder. Parameters are required by default and must be provided when executing the query.

Options

  • :as - The SQL placeholder (e.g., ‘$1’, ‘$2’) that this parameter maps to

Examples

class UserSearch < Kweerie::Base
  # Single parameter
  bind :name, as: '$1'

  # Multiple parameters
  bind :email, as: '$2'
  bind :status, as: '$3'
end

# Using the query
UserSearch.with(
  name: 'Eclipsoid',
  email: '%@example.com',
  status: 'active'
)

Notes

  • Parameters must be provided in the order they appear in the SQL

  • All bound parameters are required

  • Use PostgreSQL’s COALESCE for optional parameters



45
46
47
 
# File 'lib/kweerie/base.rb', line 45

def bind(param_name, as:)
  @bindings[param_name] = as
end

.inherited(subclass) ⇒ Object 



6
7
8
9
10
 
# File 'lib/kweerie/base.rb', line 6

def inherited(subclass)
  subclass.instance_variable_set(:@bindings, {})
  subclass.instance_variable_set(:@class_location, caller_locations(1, 1)[0].path)
  super
end

.sql_content ⇒ Object 



106
107
108
 
# File 'lib/kweerie/base.rb', line 106

def sql_content
  @sql_content ||= File.read(sql_path)
end

.sql_file_location(location = :default) ⇒ Object

SQL File Location

Specifies the location of the SQL file for this query. By default, Kweerie looks for an SQL file with the same name as the query class in the same directory.

Options

  • :default - Use default file naming (class_name.sql in same directory)

  • root: 'path' - Path relative to Rails.root

  • relative: 'path' - Path relative to the query class file

Examples

class UserSearch < Kweerie::Base
  # Default behavior - looks for user_search.sql in same directory
  sql_file_location :default

  # Use a specific file from Rails root
  sql_file_location root: 'db/queries/complex_user_search.sql'

  # Use a file relative to this class
  sql_file_location relative: '../sql/user_search.sql'
end

Notes

  • Root paths require Rails to be defined

  • Paths should use forward slashes even on Windows

  • File extensions should be included in the path

  • Relative paths are relative to the query class file location



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/kweerie/base.rb', line 82

def sql_file_location(location = :default)
  @sql_file_location =
    case location
    when :default
      nil
    when Hash
      if location.key?(:root)
        { root: location[:root].to_s }
      elsif location.key?(:relative)
        { relative: location[:relative].to_s }
      else
        raise ArgumentError,
              "Invalid sql_file_location option. Use :default, root: 'path', or relative: 'path'"
      end
    else
      raise ArgumentError,
            "Invalid sql_file_location option. Use :default, root: 'path', or relative: 'path'"
    end
end

.sql_path ⇒ Object 



102
103
104
 
# File 'lib/kweerie/base.rb', line 102

def sql_path
  @sql_path ||= SQLPathResolver.new(@sql_file_location, name).resolve
end

.with(params = {}) ⇒ Object

Execute Query with Parameters

Executes the SQL query with the provided parameters. All bound parameters must be provided unless using .all for parameter-free queries.

Parameters

  • params - Hash of parameter names and values that match the bound parameters

Returns

Array of hashes representing the query results. When using Kweerie::BaseObject, returns array of typed objects instead.

Examples

# With parameters
UserSearch.with(
  name: 'Eclipsoid',
  email: '%@example.com'
)
# => [{"id"=>1, "name"=>"Eclipsoid", "email"=>"[email protected]"}]

# With type casting (BaseObject)
UserSearch.with(created_after: '2024-01-01')
# => [#<UserSearch id=1 created_at=2024-01-01 00:00:00 +0000>]

Notes

  • Raises ArgumentError if required parameters are missing

  • Raises ArgumentError if extra parameters are provided

  • Returns empty array if no results found

  • Parameters are bound safely using pg-ruby’s parameter binding



144
145
146
147
148
149
150
151
 
# File 'lib/kweerie/base.rb', line 144

def with(params = {})
  validate_params!(params)
  param_values = order_params(params)

  connection = Kweerie.configuration.connection_provider.call
  result = connection.exec_params(sql_content, param_values)
  result.to_a
end