kweerie 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 28a36928eab4b34cff2a0fbdcf7e4614264f501d7e75f0b08ae6c28f151cd641
+  data.tar.gz: 8f0332f34bf28dc46c33cb671bb03e95330d08a9e15eed735be6ca64964d10db
+SHA512:
+  metadata.gz: 026f1786bbb42976b0461951005f448e7b2169b6962a5f06737a9cc2fbdd99af93c84ea5d5ee277067788e349c6e73df98096154bebea79f6a2b9b5f450f0234
+  data.tar.gz: d3e8e06dcaa23ea12f205e623861ba08cd16b2be877e9008571efbe38a6f6a536efb717ed45ca977102c9b2fa2cf5ebec737a31faf6e8e4accf4e93f51412395

data/.rubocop.yml

@@ -0,0 +1,13 @@
+AllCops:
+  TargetRubyVersion: 2.6
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2024-11-06
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 TODO: Write your name
+
+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,163 @@
+# Kweerie
+
+Kweerie is a Ruby gem that helps you manage SQL queries in standalone files with parameter binding for PostgreSQL. It's designed to be a lightweight alternative to database views when you need to keep SQL logic separate from your Ruby code.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'kweerie'
+```
+
+Then execute:
+
+```bash
+bundle install
+```
+
+## Usage
+
+### Basic Usage
+
+Create a new query class and its corresponding SQL file:
+
+```ruby
+# app/queries/user_search.rb
+class UserSearch < Kweerie::Base
+  bind :name, as: '$1'
+  bind :email, as: '$2'
+end
+```
+
+```sql
+-- app/queries/user_search.sql
+SELECT 
+  users.id,
+  users.name,
+  users.email
+FROM 
+  users
+WHERE 
+  name ILIKE $1
+  AND email ILIKE $2;
+```
+
+Execute your query:
+
+```ruby
+results = UserSearch.with(
+  name: 'John%',
+  email: '%@example.com'
+)
+# => [{"id"=>9981, "name"=>"John Doe", "email"=>"johndoe@example.com"}]
+```
+
+### Rails Generator
+
+If you're using Rails, you can use the generator to create new query files:
+
+```bash
+# Using underscored name
+rails generate kweerie user_search email name
+
+# Using CamelCase name
+rails generate kweerie UserSearch email name
+```
+
+This will create both the Ruby class and SQL file with the appropriate structure.
+
+### Configuration
+
+By default, Kweerie uses ActiveRecord's connection if available. You can configure this and other options:
+
+```ruby
+# config/initializers/kweerie.rb
+Kweerie.configure do |config|
+  # Use a custom connection provider
+  config.connection_provider = -> { MyCustomConnectionPool.connection }
+  
+  # Configure where to look for SQL files
+  config.sql_paths = -> { ['db/queries', 'app/sql'] }
+end
+```
+
+## Requirements
+
+- Ruby 2.7 or higher
+- PostgreSQL (this gem is PostgreSQL-specific and uses the `pg` gem)
+- Rails 6+ (optional, needed for the generator and default ActiveRecord integration)
+
+## Features
+
+- ✅ Separate SQL files from Ruby code
+- ✅ Strong parameter binding for SQL injection protection
+- ✅ Rails generator for quick file creation
+- ✅ Configurable connection handling
+- ✅ Parameter validation
+
+## Why Kweerie?
+
+- **SQL Views Overkill**: When a database view is too heavy-handed but you still want to keep SQL separate from Ruby
+- **Version Control**: Keep your SQL under version control alongside your Ruby code
+- **Parameter Safety**: Built-in parameter binding prevents SQL injection
+- **Simple Interface**: Clean, simple API for executing parameterized queries
+- **Rails Integration**: Works seamlessly with Rails and ActiveRecord
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## FAQ
+
+**Q: Why PostgreSQL only?**  
+A: Kweerie uses PostgreSQL-specific features for parameter binding and result handling. Supporting other databases would require different parameter binding syntax and result handling.
+
+**Q: Do I need Rails?**  
+A: No, Kweerie works with any Ruby application. Rails is only required if you want to use the generator or the automatic ActiveRecord integration.
+
+**Q: Can I use this with views?**  
+A: Yes! You can write any valid PostgreSQL query, including queries that use views.
+
+**Q: How do I handle optional parameters?**  
+A: Currently, all bound parameters are required. For optional parameters, you'll need to handle the conditionals in your SQL using COALESCE or similar PostgreSQL functions.
+
+**Q: How do I convert types in parameters?**  
+A: PostgreSQL has robust type handling built-in, so you can handle type conversion directly in your SQL. Here are some examples:
+
+```sql
+-- Convert string to integer
+WHERE id = $1::integer
+
+-- Convert string to date
+WHERE created_at > $1::date
+
+-- Convert string to array
+WHERE tags && $1::text[]
+
+-- Convert to timestamp with timezone
+WHERE created_at > $1::timestamptz
+
+-- Multiple conversions in one query
+SELECT *
+FROM users
+WHERE 
+  created_at > $1::timestamptz
+  AND age > $2::integer
+  AND tags && $3::text[]
+  AND metadata @> $4::jsonb
+```
+
+This approach leverages PostgreSQL's native type casting system, which is both more efficient and more reliable than converting types in Ruby.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/generators/kweerie/kweerie_generator.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+class KweerieGenerator < Rails::Generators::NamedBase
+  source_root File.expand_path("templates", __dir__)
+  argument :parameters, type: :array, default: []
+
+  def create_query_file
+    # Convert parameters into bind statements
+    bind_statements = parameters.map.with_index(1) do |param, index|
+      "  bind :#{param.underscore}, as: '$#{index}'"
+    end.join("\n")
+
+    # Create the query class
+    template_content = <<~RUBY
+      # frozen_string_literal: true
+
+      class #{class_name} < Kweerie::Base
+        #{bind_statements}
+      end
+    RUBY
+
+    # Ensure the queries directory exists
+    FileUtils.mkdir_p("app/queries")
+
+    # Create the Ruby file
+    create_file "app/queries/#{file_name}.rb", template_content
+
+    # Create the SQL file
+    create_file "app/queries/#{file_name}.sql", <<~SQL
+      -- Write your SQL query here
+      -- Available parameters: #{parameters.map { |p| "$#{parameters.index(p) + 1} (#{p})" }.join(", ")}
+
+      SELECT
+        -- your columns here
+      FROM
+        -- your tables here
+      WHERE
+        -- your conditions here
+    SQL
+  end
+
+  private
+
+  def file_name
+    name.underscore
+  end
+
+  def class_name
+    name.classify
+  end
+end

data/lib/kweerie/base.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Kweerie
+  class Base
+    class << self
+      def inherited(subclass)
+        subclass.instance_variable_set(:@bindings, {})
+        super
+      end
+
+      def bind(param_name, as:)
+        @bindings[param_name] = as
+      end
+
+      attr_reader :bindings
+
+      def sql_path
+        @sql_path ||= begin
+          subclass_file = "#{name.underscore}.sql"
+          possible_paths = Kweerie.configuration.sql_paths.call
+
+          sql_file = possible_paths.map do |path|
+            File.join(root_path, path, subclass_file)
+          end.find { |f| File.exist?(f) }
+
+          unless sql_file
+            raise SQLFileNotFound,
+                  "Could not find SQL file for #{name} in paths: #{possible_paths.join(", ")}"
+          end
+
+          sql_file
+        end
+      end
+
+      def sql_content
+        @sql_content ||= File.read(sql_path)
+      end
+
+      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
+
+      private
+
+      def validate_params!(params)
+        missing_params = bindings.keys - params.keys
+        raise ArgumentError, "Missing required parameters: #{missing_params.join(", ")}" if missing_params.any?
+
+        extra_params = params.keys - bindings.keys
+        return unless extra_params.any?
+
+        raise ArgumentError, "Unknown parameters provided: #{extra_params.join(", ")}"
+      end
+
+      def order_params(params)
+        ordered_params = bindings.transform_values { |position| params[bindings.key(position)] }
+        ordered_params.values
+      end
+
+      def root_path
+        defined?(Rails) ? Rails.root : Dir.pwd
+      end
+
+      def using_activerecord?
+        defined?(ActiveRecord::Base) &&
+          Kweerie.configuration.connection_provider == Kweerie::Configuration.new.connection_provider
+      end
+    end
+  end
+end

data/lib/kweerie/configuration.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Kweerie
+  class Configuration
+    attr_accessor :connection_provider, :sql_paths
+
+    def initialize
+      # Default to using ActiveRecord's connection if available
+      @connection_provider = lambda {
+        unless defined?(ActiveRecord::Base)
+          raise ConfigurationError, "No connection provider configured and ActiveRecord is not available"
+        end
+
+        ActiveRecord::Base.connection.raw_connection
+      }
+
+      # Default SQL paths
+      @sql_paths = lambda {
+        paths = ["app/queries"]
+        paths.unshift("lib/queries") unless defined?(Rails)
+        paths
+      }
+    end
+  end
+end

data/lib/kweerie/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Kweerie
+  VERSION = "0.1.0"
+end

data/lib/kweerie.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "kweerie/version"
+
+module Kweerie
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class SQLFileNotFound < Error; end
+
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end
+
+require_relative "kweerie/configuration"
+require_relative "kweerie/base"

data/sig/kweerie.rbs

@@ -0,0 +1,4 @@
+module Kweerie
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: kweerie
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Toby
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-11-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+description: A simple way to manage SQL files with parameter binding in Ruby applications
+email:
+- toby@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/generators/kweerie/kweerie_generator.rb
+- lib/kweerie.rb
+- lib/kweerie/base.rb
+- lib/kweerie/configuration.rb
+- lib/kweerie/version.rb
+- sig/kweerie.rbs
+homepage: https://github.com/tobyond/kweerie
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/tobyond/kweerie
+  source_code_uri: https://github.com/tobyond/kweerie
+  allowed_push_host: https://rubygems.org
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: SQL file handler with parameter binding
+test_files: []