olaf 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 707d135df5db1d5105754573d6fa021c43da6b87ff9d83cd9baafc879ae3401e
+  data.tar.gz: d8fbaa062cd9eb2c4e3438d4b40f8c8352b95e1234f2f5d59c040870013ad263
+SHA512:
+  metadata.gz: 969ee6bec25a2f5c17dbc03fb1e5aab61ed9b6801c764c2797ac36c0a8a0482351888a9f87cdec3d78453aca5bbd82ec635d3a5d3dfca0cc03eac0df3eee193c
+  data.tar.gz: 7a1fe66488aa789b7f005102b668767682ae6e5bb59fa20168641897a993ebb48a9c5b359ac69795e2bafe67df78b5565be1a4b19cf11c1e68119c114cb6623b

data/README.md

@@ -0,0 +1,45 @@
+# Olaf
+[![Gem Version](https://badge.fury.io/rb/ork.svg)](http://badge.fury.io/rb/ork)
+[![Build Status](https://travis-ci.org/emancu/ork.svg)](https://travis-ci.org/emancu/ork)
+
+Olaf is a small Ruby wrapper for Snowflake queries.
+
+![Olaf](https://i.pinimg.com/474x/6a/76/67/6a76672b65bf989b25b1ec0fc8cda3c8.jpg)
+
+## Dependencies
+
+`olaf` requires Ruby 2.2 or later, `sequel` and `odbc` driver to connect with DBs.
+
+Install dependencies using `bundler` is easy as run:
+
+    bundle install
+
+## Installation
+
+If you don't have Olaf, try this:
+
+    $ gem install olaf
+
+## Getting started
+
+Olaf helps developers to represent Snowflake queries as objects, to have more
+control in the code and in tests.
+
+### Example
+
+```ruby
+class FetchUsers
+  include Olaf::QueryDefinition
+
+  template './snowflake/users_in_department.sql'
+
+  attribute :department_id
+
+  row_object User
+end
+
+query = FetchUsers.prepare(department_id: 1337)
+
+Olaf.execute(query)
+=> [#<User id: 41, department_id: 1337, name: 'Ian'>]
+```

data/lib/olaf.rb

@@ -0,0 +1,46 @@
+require 'sequel'
+require 'odbc_utf8'
+
+require_relative 'olaf/errors'
+require_relative 'olaf/query_definition'
+require_relative 'olaf/drivers/fake'
+require_relative 'olaf/drivers/snowflake'
+
+module Olaf
+  # Configures Olaf module to execute queries in Snowflake or in a local object
+  # to prevent external calls. Arguments passed will be forwarded directly
+  # to the `olaf_driver` class specified.
+  #
+  # By default, it will set a connection with Snowflake
+  def self.configure(olaf_driver: Olaf::Snowflake, **args)
+    @instance = olaf_driver.new(**args)
+  end
+
+  # Executes a query defined by Olaf::QueryDefinition with the driver
+  # configured previously.
+  #
+  #   @return Enumerable of results.
+  #     (i.e. Array of Hashes or `row_objects` when specified)
+  #
+  #   @raises Olaf::QueryExecutionError
+  def self.execute(olaf_query)
+    row_object = olaf_query.class.row_object
+    row_transformer = row_object ? ->(r) { row_object.new(**r) } : Proc.new(&:itself)
+
+    instance
+      .fetch(olaf_query)
+      .map!(&row_transformer)
+  rescue Sequel::DatabaseError => error
+    raise QueryExecutionError.new(error.message, olaf_query)
+  end
+
+  # Returns an instance to execute queries when its configured.
+  #
+  #   @return Olaf driver instance
+  #     * Olaf::Fake      - Ideal for testing
+  #     * Olaf::Snowflake - Sequel.odbc driver to run queries in Snowflake
+  #
+  def self.instance
+    @instance || raise('You need to configure Olaf before using it!')
+  end
+end

data/lib/olaf/drivers/fake.rb

@@ -0,0 +1,60 @@
+module Olaf
+  class Fake
+    attr_reader :config, :execution_log, :recorded_responses
+
+    def initialize(**config)
+      @config = config
+      @execution_log = []
+      @recorded_responses = {}
+    end
+
+    def fetch(olaf_query)
+      @execution_log << olaf_query
+
+      generic_response = @recorded_responses.dig(olaf_query.class, :generic)
+      specific_response = @recorded_responses.dig(olaf_query.class, olaf_query.variables)
+
+      specific_response || generic_response || raise_developer_error!(olaf_query)
+    end
+
+    def register_result(olaf_query_class, result, with: :generic)
+      @recorded_responses[olaf_query_class] ||= {}
+      @recorded_responses[olaf_query_class].merge!(with => result)
+    end
+
+    private
+
+    def raise_developer_error!(query)
+      error_msg = "No Query result registered for '#{query.class}' with: #{query.variables} found!"
+
+      available_responses =
+        @recorded_responses
+          .map { |k, v| [k, ['', *v.keys].join("\n\t\t=> ")] }
+          .map { |klass, args| "\t #{klass}#{args}" }
+          .join("\n\n")
+          .then { |str| "Queries responses registered: \n\n #{str}" unless str.empty?}
+
+      puts %{
+        #{error_msg}
+
+        This is a testing environment and the query has no result registered.
+        To register a query result call `Olaf.instance.register_result`
+        during the test setup or before executing the query.
+
+
+            Olaf.instance.register_result(#{query.class}, [])
+
+
+        To register a result for specific arguments you can specify the variables:
+
+
+            Olaf.instance.register_result(#{query.class}, [], with: #{query.variables})
+
+
+        #{available_responses}
+      }
+
+      raise error_msg
+    end
+  end
+end

data/lib/olaf/drivers/snowflake.rb

@@ -0,0 +1,17 @@
+module Olaf
+  class Snowflake
+    def initialize(**config)
+      @config = config
+    end
+
+    def fetch(olaf_query)
+      conn.fetch(olaf_query.sql_template, **olaf_query.variables).all
+    end
+
+    private
+
+    def conn
+      @conn ||= Sequel.odbc('snowflake', **@config)
+    end
+  end
+end

data/lib/olaf/errors.rb

@@ -0,0 +1,35 @@
+module Olaf
+  class MissingArgumentsError < ArgumentError
+    def initialize(olaf_query)
+      @olaf_query = olaf_query
+      msg = "Missing arguments: #{olaf_query.missing_arguments}"
+
+      super(msg)
+    end
+
+    def metadata
+      {
+        query: @olaf_query.class.name,
+        defined_arguments: @olaf_query.defined_arguments,
+        missing_arguments: @olaf_query.missing_arguments,
+        arguments: @olaf_query.variables
+      }
+    end
+  end
+
+  class UndefinedArgumentsError < StandardError
+    def initialize(olaf_query)
+      super("Undefined arguments: #{olaf_query.undefined_arguments}")
+    end
+  end
+
+  class QueryExecutionError < StandardError
+    attr_reader :metadata
+
+    def initialize(message, olaf_query)
+      @query = olaf_query
+      @metadata = olaf_query.metadata
+      super(message)
+    end
+  end
+end

data/lib/olaf/query_definition.rb

@@ -0,0 +1,67 @@
+require_relative 'errors'
+require_relative 'query_definition/class_methods'
+
+module Olaf
+  module QueryDefinition
+    attr_reader :variables, :sql_template
+
+    def self.included(base)
+      base.extend(Olaf::QueryDefinition::ClassMethods)
+    end
+
+    def initialize(**variables)
+      @variables = variables
+      @sql_template = nil
+    end
+
+    # Loads the SQL template and validate all the arguments are
+    # defined AND present.
+    # The instance will be ready to be executed.
+    #
+    #   @return QueryDefinition instance
+    #
+    #   @raises Snowflake::UndefinedArgumentsError
+    #   @raises Snowflake::MissingArgumentsError
+    def prepare
+      @sql_template ||= File.read(self.class.template)
+
+      raise UndefinedArgumentsError, self if undefined_arguments.any?
+      raise MissingArgumentsError, self if missing_arguments.any?
+
+      literal_arguments = self.class.arguments.select { |_k, v| v[:literal] }.keys
+
+      variables.slice(*literal_arguments).each do |placeholder, literal_value|
+        @sql_template.gsub!(":#{placeholder}", literal_value)
+      end
+
+      self
+    end
+
+    def metadata
+      {
+        query_class: self.class.name,
+        arguments: variables,
+        sql_template: sql_template,
+      }
+    end
+
+    def defined_arguments
+      self.class.arguments.keys
+    end
+
+    def missing_arguments
+      defined_arguments - @variables.keys
+    end
+
+    # Find placeholders in the SQL file.
+    # Every placeholder MUST be declared as an `argument` of the query.
+    def undefined_arguments
+      @sql_template
+        .scan(/[^:]:(\w+)/)
+        .flatten
+        .map(&:to_sym)
+        .then { |required_arguments| required_arguments - defined_arguments }
+        .uniq
+    end
+  end
+end

data/lib/olaf/query_definition/class_methods.rb

@@ -0,0 +1,79 @@
+module Olaf
+  module QueryDefinition
+    module ClassMethods
+      # Creates a new instance of the Query defined and validates
+      # the parameters passed, leaving the instance in a ready-to-execute state.
+      #   @return Snowflake::QueryDefinition instance
+      def prepare(**vars)
+        new(vars).prepare
+      end
+
+      # Returns ALL the arguments defined for the query, including options.
+      #   @return Hash
+      def arguments
+        @arguments ||= {}
+      end
+
+      # Define an argument for the query matching a placeholder in the template.
+      # The Sequel gem, will fill the placeholders in the SQL query escaping the
+      # value passed as an argument. Sometimes, we need to pass an argument as
+      # literal to avoid the single quotes added by Sequel (i.e. sending a table_name)
+      #
+      # options - Hash config for each argument
+      #   :as - Argument Type
+      #     * :literal - Forces a string substitution with the literal value
+      #
+      # Example:
+      #
+      #     class OneQuery
+      #       include Snowflake::QueryDefinition
+      #
+      #       template 'reports/one.sql'
+      #
+      #       argument :dealersip_id
+      #       argument :table_name, as: :literal
+      #     end
+      #
+      #
+      def argument(name, options = {})
+        return if arguments.key?(name)
+
+        arguments[name] = { literal: options[:as] == :literal }
+
+        name
+      end
+
+      # Define the file path to the SQL template for this query.
+      #
+      # Example:
+      #
+      #     class OneQuery
+      #       include Snowflake::QueryDefinition
+      #
+      #       template 'reports/one.sql'
+      #     end
+      #
+      #
+      def template(file_name = nil)
+        @template ||= file_name
+      end
+
+      # Define the object representing each row of the result.
+      # When not specified, each row will be a hash by default.
+      #
+      # Example:
+      #
+      #     class OneQuery
+      #       include Snowflake::QueryDefinition
+      #
+      #       row_object MyOwnObject
+      #     end
+      #
+      #
+      def row_object(object_class = nil)
+        @row_object ||= object_class
+      end
+    end
+  end
+end
+

data/olaf.gemspec

@@ -0,0 +1,21 @@
+Gem::Specification.new do |s|
+  s.name        = 'olaf'
+  s.version     = '0.1.0'
+  s.date        = Time.now.strftime('%Y-%m-%d')
+  s.summary     = 'Ruby wrapper for Snowflake queries.'
+  s.authors     = ['Emiliano Mancuso']
+  s.email       = ['emiliano.mancuso@gmail.com', 'developers@carwow.co.uk']
+  s.homepage    = 'http://github.com/carwow/olaf'
+  s.license     = 'MIT'
+
+  s.files = Dir[
+    'README.md',
+    'rakefile',
+    'lib/**/*.rb',
+    '*.gemspec'
+  ]
+  s.test_files = Dir['test/*.*']
+
+  s.add_runtime_dependency 'sequel', '~> 5.37'
+  s.add_runtime_dependency 'ruby-odbc', '~> 0.99'
+end

data/rakefile

@@ -0,0 +1,8 @@
+task :default => :test
+
+desc 'Run tests'
+task :test do
+  require File.expand_path('./test/helper', File.dirname(__FILE__))
+
+  Dir['test/**/*_test.rb'].each { |file| load file }
+end

data/test/helper.rb

@@ -0,0 +1,8 @@
+$LOAD_PATH.unshift(File.expand_path(File.dirname(__FILE__) + "/../lib"))
+
+require 'olaf'
+require 'test/unit'
+
+def reject(condition, message="Expected condition to be unsatisfied")
+  assert !condition, message
+end

data/test/olaf_configure_test.rb

@@ -0,0 +1,28 @@
+require_relative 'helper'
+
+class OlafConfigureTest < Test::Unit::TestCase
+  class MockDriver
+    attr_reader :config
+
+    def initialize(**config)
+      @config = config
+    end
+
+    def instance
+      self
+    end
+  end
+
+  def test_configure_initializes_driver_instance
+    Olaf.configure(olaf_driver: MockDriver, other: 'configs', like: 'user and passwd')
+
+    assert Olaf.instance.is_a?(MockDriver)
+    assert_equal Olaf.instance.config, { other: 'configs', like: 'user and passwd' }
+  end
+
+  def test_configure_defaults_to_snowflake
+    Olaf.configure(random: 'stuff')
+
+    assert Olaf.instance.is_a?(Olaf::Snowflake)
+  end
+end

data/test/olaf_execute_test.rb

@@ -0,0 +1,48 @@
+require_relative 'helper'
+
+class OlafExecuteTest < Test::Unit::TestCase
+  def setup
+    Olaf.configure(olaf_driver: Olaf::Fake)
+
+    @query = Class.new.include(Olaf::QueryDefinition)
+    @query.template File.join(File.dirname(__FILE__), './fixtures/query_with_arguments.sql')
+    @query.argument :id
+
+    Olaf.instance.register_result(@query, [{ company: 'carwow' }])
+    @query_instance = @query.new(id: 1).prepare
+  end
+
+  def test_execute_returns_an_enumerable
+    assert Olaf.execute(@query_instance).is_a?(Enumerable)
+  end
+
+  def test_execute_returns_a_list_of_row_objects_when_defined
+    @query.row_object OpenStruct
+
+    all_row_objects = Olaf.execute(@query_instance).all? { |e| e.is_a? OpenStruct }
+
+    assert all_row_objects
+  end
+
+  def test_execute_returns_hashes_when_no_row_object_defined
+    all_hashes = Olaf.execute(@query_instance).all? { |e| e.is_a? Hash }
+
+    assert all_hashes
+  end
+
+  def test_execute_raises_error
+    faulty_driver = Class.new do
+      def initialize(**args); end
+
+      def fetch(*args)
+        raise Sequel::DatabaseError
+      end
+    end
+
+    Olaf.configure(olaf_driver: faulty_driver)
+
+    assert_raise Olaf::QueryExecutionError do
+      Olaf.execute(@query_instance)
+    end
+  end
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: olaf
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Emiliano Mancuso
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2020-10-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sequel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.37'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.37'
+- !ruby/object:Gem::Dependency
+  name: ruby-odbc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.99'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.99'
+description:
+email:
+- emiliano.mancuso@gmail.com
+- developers@carwow.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/olaf.rb
+- lib/olaf/drivers/fake.rb
+- lib/olaf/drivers/snowflake.rb
+- lib/olaf/errors.rb
+- lib/olaf/query_definition.rb
+- lib/olaf/query_definition/class_methods.rb
+- olaf.gemspec
+- rakefile
+- test/helper.rb
+- test/olaf_configure_test.rb
+- test/olaf_execute_test.rb
+homepage: http://github.com/carwow/olaf
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.4
+signing_key:
+specification_version: 4
+summary: Ruby wrapper for Snowflake queries.
+test_files:
+- test/helper.rb
+- test/olaf_execute_test.rb
+- test/olaf_configure_test.rb