query_set 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7c4ccc0d00a6a52280fe9dec2cb138ad071a4811
+  data.tar.gz: acfb0146a4b850ced79ed9f782799307a1fe3025
+SHA512:
+  metadata.gz: 24b0b9beb0cf0c05816345cfbbf733b87442e2c36740ac7d2a871d9dd935242cb495b22cc8b7b8200751f36896641da6dc8d8f213ad26ca4dde07efea9d18201
+  data.tar.gz: 5e6ecc3af71bd77d44b8774d0b057122a992c1f0d69586b05c3af5c5ad0b3770455323e84502537ee7519b72e883392ae98db501d238aefc894ac2bfcb73bbea

data/.gems

@@ -0,0 +1,2 @@
+cutest -v 1.2.3
+pg -v 0.21.0

data/.gitignore

@@ -0,0 +1,4 @@
+.gs/
+.DS_Store
+.env
+.gem

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2017 Steven Weiss
+
+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,111 @@
+# QuerySet
+
+QuerySet is a small wrapper around the Ruby pg gem for safely executing
+sql that is saved in files.
+
+## Installation
+
+`$ gem install query-set`
+
+## API
+
+### QuerySet
+
+`initialize` Requires a connection and a formattable directory path.
+Optional arguments include `query:` for setting the query class, and `store:`
+for setting the caching object.
+
+`[]` Fetches a query object from the cache (store). If it does not exist, loads
+the corresponding template from disk and compiles it.
+
+`[]=` Manually sets an object in the cache.
+
+`execute` Delegates execution to the appropriate query object, passing it the configured
+connection and any provided arguments.
+
+### Query
+
+`initialize` Requires a string to be compiled into a sql string with ordered
+placeholders.
+
+`execute` Sends sql to the connection for the given arguments.
+
+## Usage
+
+To get an understanding of QuerySet (qs), we're going to start from the bottom
+and build our way up. The foundation of qs is the class QuerySet::Query.
+
+QuerySet::Query is responsible for parsing a template string,
+and converting it into a sql string with position based placeholders that
+Postgres understands. This buys us two things. First, we "upgrade" our coupling
+from one that is based on position to one that is based on name
+(which is generally a good thing, see [connascence][Connascence]). The second
+thing we get is security, since we no longer have to be escaping sql strings
+manually we get to avoid all sorts of vulnerabilities. If you ever find yourself
+using QuerySet::Query manually, remember to always escape any untrusted values
+via `PG::Connection.escape_string`.
+
+```ruby
+  ## Initial a new query object.
+  query = QuerySet::Query.new("SELECT * FROM users WHERE id = {{ id }} LIMIT 1;")
+
+  ## During initialization, the query object
+  ## 'compiled' the template string into a sql string.
+  query.sql ## SELECT * FROM users WHERE id = $1 LIMIT 1;
+
+  ## It also remembered the params (as symbols).
+  query.params ## [:id]
+```
+
+Now that we have converted the template string into sql that our database
+understands, we can execute it. To do so we send our query object
+`##execute(conn, args)`.
+
+The first argument, `conn`, is expected to be a `PG::Connection`.
+The second argument is typically a `Hash`,
+though you can pass it custom objects that implement `##values_at` (quick quick).
+
+This means that `##execute` knows how to put our args in order
+and then delegate the execution to the connection. The return values are the
+same as using the `pg` gem directly: `PG::Result` on success, and
+on a failure it raises `PG::Error`.
+
+You're probably thinking this is a little inconvenient, having to pass the conn
+in each time. But don't worry, this is handled for you by the `QuerySet` class.
+
+The QuerySet class is the top level of the library, and is basically a
+factory for your query objects your query objects. It is responsible for:
+
+* Holding a reference to your database connection.
+* Dealing with the file system.
+* Caching query objects (not the results, just the compiled templates).
+* Delegating execute to the the appropriate query object.
+
+```ruby
+  conn = PG.connection.open(ENV['pg'])
+
+  ## Construct a QuerySet by giving it a reference to your connection
+  ## and also a path where it can find your query templates.
+  ## Notice the `%s` in the path, it's super important.
+  ## When we call methods on our query set, we will send it the file name
+  ## of our query. This file name serves as both the cache key for a query
+  ## an it's location on disk.
+  query_set = QuerySet.new(conn, './path/to/queries/%s.sql')
+
+  ## To execute a query located in the directory we configured, we send it
+  ## '##execute'.
+  query_set.execute('users/by_id', id: id)
+
+  ## This is the meat of the entire library. The first thing the execute method
+  ## does is check the cache to see if a query object exists for the file
+  ## name we gave it. If it does not exist, it creates one by giving QuerySet::Query
+  ## the template string it finds on disc. Once the template is compiled, we
+  ## get to hop back on the branch as if it was a cache hit. On a cache hit,
+  ## we send our query object the `##execute` method, passing it the conn we have
+  ## a reference to and also the supplied arguments.
+```
+
+Check out the examples directory and tests to get an even better understand
+on how to use QuerySet.
+
+[connascence][https://www.youtube.com/watch?v=HQXVKHoUQxY]

data/Rakefile

@@ -0,0 +1,16 @@
+desc 'open irb in gs context'
+task :console do
+  sh 'gs irb'
+end
+
+desc 'installs gems'
+task :install do
+  sh 'mkdir -p .gs & gs dep install'
+end
+
+desc 'tests the given [test].rb'
+task :test, :name do |t, args|
+  name = args[:name] || '*'
+
+  sh "gs cutest -r ./lib/query_set ./test/#{name}_test.rb"
+end

data/bin/rk

@@ -0,0 +1,8 @@
+#!/bin/sh
+
+if [ -f .env ]; then
+  env `cat .env` \
+  rake $*
+else
+  rake $*
+fi

data/examples/active_record_pattern.rb

@@ -0,0 +1,34 @@
+# Below is an example on how to implement a poor man's ORM with the
+# active record pattern using QuerySet. If something like this interests you,
+# check out the 'MiniModel' gem at https://github.com/sirscriptalot/mini_model.
+
+require 'pg'
+require 'query_set'
+
+class Model
+  class << self
+    attr_accessor :query_set
+
+    def [](id)
+      result = query_set.execute('by_id', id: id)
+
+      build(result)
+    rescue PG::Error => e
+      puts e
+
+      nil
+    end
+
+    alias_method :by_id, :[]
+
+    def build(result)
+      # ...
+    end
+  end
+end
+
+conn = PG::Connection.open(ENV['db1'])
+
+User.query_set = QuerySet.new(conn, './sql/users/%s.sql')
+
+User[0]

data/examples/custom_query_delimiters.rb

@@ -0,0 +1,20 @@
+# Custom delimiters can be set for compiling templates by subclassing
+# QuerySet::Query.
+
+require 'pg'
+require 'query_set'
+
+class Query < QuerySet::Query
+  # Override the left and right delimiter methods
+  # to build a custom regexp for compiling templates.
+  def left
+    '<%='
+  end)
+
+  def right
+    '%>'
+  end
+end
+
+# Inject your subclass when you initializing the QuerySet.
+QuerySet.new(conn, '', query: Query)

data/examples/interpolated_queries.rb

@@ -0,0 +1,15 @@
+# You can "preprocess" your sql templates via string interpolation
+# when working directly with QuerySet::Query.
+
+# Unnecessary for trusted data, but always remember to escape user input.
+# Be careful though, escaping user input is never guarenteed to be 100% safe.
+column = conn.escape_string('column')
+
+# Initialize a query with an interpolated string with escaped values.
+by_column = QuerySet::Query.new("SELECT * FROM users WHERE #{column} = {{ column }};")
+
+# Executing a query directly requires passing it your db connection.
+by_column.execute(conn, column: 'value')
+
+# You can also assign a query to an existing query set.
+query_set['by_column'] = by_column

data/examples/multiple_databases.rb

@@ -0,0 +1,10 @@
+require 'pg'
+require 'query_set'
+
+# Connect to multiple databases.
+db1 = PG::Connection.open(ENV['db1'])
+db2 = PG::Connection.open(ENV['db2'])
+
+# Initialize QuerySet with the appropriate connection.
+users = QuerySet.new(db1, './sql/users/%s.sql')
+posts = QuerySet.new(db2, './sql/posts/%s.sql')

data/examples/sql/posts/by_title.sql

@@ -0,0 +1,3 @@
+SELECT *
+  FROM posts
+ WHERE title = {{ title }};

data/examples/sql/users/by_id.sql

@@ -0,0 +1,3 @@
+SELECT id, email
+  FROM users
+ WHERE id = {{ id }};

data/lib/query_set.rb

@@ -0,0 +1,84 @@
+class QuerySet
+  VERSION = '0.0.0'
+
+  attr_accessor :conn, :path, :query, :store
+
+  def initialize(conn, path, query: Query, store: {})
+    @conn = conn
+    @path = path
+    @query = query
+    @store = store
+  end
+
+  def [](file_name)
+    store.fetch(file_name) do
+      store[file_name] = query.new(File.read(path % file_name))
+    end
+  end
+
+  def []=(key, value)
+    store[key] = value
+  end
+
+  def execute(file_name, *args)
+    self.[](file_name).execute(conn, *args)
+  end
+
+  class Query
+    LEFT = '{{'
+
+    RIGHT = '}}'
+
+    attr_reader :sql, :params
+
+    def initialize(str)
+      @sql = ''
+      @params = []
+
+      compile(str)
+
+      @sql.freeze
+      @params.freeze
+    end
+
+    def execute(conn, args = {})
+      conn.exec_params(sql, args.values_at(*params))
+    end
+
+    private
+
+    def compile(str)
+      terms = str.split(regexp)
+
+      while (term = terms.shift)
+        case term
+        when left
+          param = terms.shift.to_sym
+
+          # Capture the param for execute position.
+          params << param
+
+          # Append a 1-based placeholder for the param to the sql string.
+          sql << "$#{params.index(param).succ}"
+        else
+          sql << term
+        end
+      end
+
+      # Only remember the unique parameters.
+      params.uniq!
+    end
+
+    def left
+      LEFT
+    end
+
+    def right
+      RIGHT
+    end
+
+    def regexp
+      /(#{left})\s*(.*?)\s*#{right}/
+    end
+  end
+end

data/query_set.gemspec

@@ -0,0 +1,14 @@
+require_relative "./lib/query_set"
+
+Gem::Specification.new do |s|
+  s.name     = "query_set"
+  s.summary  = "QuerySet"
+  s.version  = QuerySet::VERSION
+  s.authors  = ["Steve Weiss"]
+  s.email    = ["weissst@mail.gvsu.edu"]
+  s.homepage = "https://github.com/sirscriptalot/query_set"
+  s.license  = "MIT"
+  s.files    = `git ls-files`.split("\n")
+
+  s.add_development_dependency "cutest", "~> 1.2"
+end

data/test/query_set_test.rb

@@ -0,0 +1,47 @@
+setup do
+  query_set = QuerySet.new(nil, __dir__ + "/sql/%s.sql")
+end
+
+test '#[] initializes query objects for path/file_name' do |query_set|
+  query = query_set['example']
+
+  assert query.is_a?(query_set.query)
+end
+
+test '#[] memoizes query objects' do |query_set|
+  a = query_set['example']
+  b = query_set['example']
+
+  assert_equal a.object_id, b.object_id
+end
+
+test '#[]= sets query objects' do |query_set|
+  query_set['foo'] = 'bar'
+
+  assert_equal query_set['foo'], 'bar'
+end
+
+class FakeQuery
+  attr_reader :conn, :args
+
+  def initialize(*args); end
+
+  def execute(conn, args)
+    @conn, @args = conn, args
+  end
+end
+
+test '#execute sends conn and args to query object for file name' do
+  conn = :conn
+
+  args = { foo: :bar }
+
+  query_set = QuerySet.new(conn, __dir__ + "/sql/%s.sql", query: FakeQuery)
+
+  query_set.execute('example', args)
+
+  query = query_set['example']
+
+  assert_equal query.conn, conn
+  assert_equal query.args, args
+end

data/test/query_test.rb

@@ -0,0 +1,39 @@
+test '#compile replaces identifiers with ordered placeholders' do
+  query = QuerySet::Query.new('{{ first }} {{ second }} {{ first }}')
+
+  assert_equal query.sql, '$1 $2 $1'
+end
+
+test '#compile captures unique params' do
+  query = QuerySet::Query.new('{{ first }} {{ second }} {{ first }}')
+
+  assert_equal query.params, [:first, :second]
+end
+
+test '#compile ignores whitespace in identifiers' do
+  a = QuerySet::Query.new('{{first}} {{second}} {{first}}')
+  b = QuerySet::Query.new('{{ first }} {{ second }} {{ first }}')
+
+  assert_equal a.sql, b.sql
+end
+
+class FakeConn
+  attr_reader :sql, :ary
+
+  def exec_params(sql, ary)
+    @sql, @ary = sql, ary
+  end
+end
+
+test '#execute delegates to conn with correct parameters order' do
+  conn = FakeConn.new
+
+  query = QuerySet::Query.new('{{ first }} {{ second }} {{ first }}')
+
+  args = { second: 2, first: 1}
+
+  query.execute(conn, args)
+
+  assert_equal conn.sql, query.sql
+  assert_equal conn.ary, [1, 2]
+end

data/test/sql/example.sql

@@ -0,0 +1 @@
+SELECT * FROM table WHERE id = {{ id }};

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: query_set
+version: !ruby/object:Gem::Version
+  version: 0.0.0
+platform: ruby
+authors:
+- Steve Weiss
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-10-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: cutest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+description: 
+email:
+- weissst@mail.gvsu.edu
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gems"
+- ".gitignore"
+- LICENSE
+- README.md
+- Rakefile
+- bin/rk
+- examples/active_record_pattern.rb
+- examples/custom_query_delimiters.rb
+- examples/interpolated_queries.rb
+- examples/multiple_databases.rb
+- examples/sql/posts/by_title.sql
+- examples/sql/users/by_id.sql
+- lib/query_set.rb
+- query_set.gemspec
+- test/query_set_test.rb
+- test/query_test.rb
+- test/sql/example.sql
+homepage: https://github.com/sirscriptalot/query_set
+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: []
+rubyforge_project: 
+rubygems_version: 2.6.11
+signing_key: 
+specification_version: 4
+summary: QuerySet
+test_files: []