db_mod 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f148df036e59a1e23b2faa43b407b9493d54671a
+  data.tar.gz: c0ab239586891d8b91a5a82d79a17f4e19777f48
+SHA512:
+  metadata.gz: 199028216fcaf755e20a67d607ad5f7ac3399c0c26ea3cee37f151dc5786c3e87b57245a9c4d42bbe5807bb6e3a1e6814e2ae9495ed15030e6d94c85f9071ea1
+  data.tar.gz: 7930c834d9705cfdb2e57556e9a478db09c0967ac16339d5728893561178431d09520fb98f7dc688ee7d331b683ffe8014ccfe9e25c7efaa7348427afe5d0158

data/.gitignore

@@ -0,0 +1,46 @@
+## MAC OS
+.DS_Store
+.com.apple.timemachine.supported
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## REDCAR
+.redcar
+
+## VIM
+*.swp
+*.swo
+
+## RUBYMINE
+.idea
+
+## PROJECT::GENERAL
+coverage
+doc
+pkg
+.rvmrc
+.bundle
+.yardoc/*
+dist
+Gemfile.lock
+gemfiles/*.lock
+tmp
+
+## Rubinius
+.rbx
+
+## Bundler binstubs
+bin
+
+## ripper-tags and gem-ctags
+tags
+
+## PROJECT::SPECIFIC
+.project

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format=documentation

data/.rubocop.yml

@@ -0,0 +1,5 @@
+AllCops:
+  Exclude:
+    - vendor/**/*
+    - bin/**/*
+    - gemfiles/**/*

data/.travis.yml

@@ -0,0 +1,14 @@
+language: ruby
+rvm:
+  - 2.2
+  - 2.1
+  - 2.0.0
+  - ruby-head
+  - 1.9.3
+
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+
+gemfile:
+  - Gemfile

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,22 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic addresses, without explicit permission
+* Other unethical or unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. By adopting this Code of Conduct, project maintainers commit themselves to fairly and consistently applying these principles to every aspect of managing this project. Project maintainers who do not follow or enforce the Code of Conduct may be permanently removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.2.0, available at [http://contributor-covenant.org/version/1/2/0/](http://contributor-covenant.org/version/1/2/0/)

data/Gemfile

@@ -0,0 +1,15 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :development, :test do
+  gem 'byebug' unless RUBY_VERSION < '2.0.0'
+  gem 'rake'
+  gem 'redcarpet'
+  gem 'rubocop'
+  gem 'guard'
+  gem 'guard-bundler'
+  gem 'guard-rspec'
+  gem 'guard-rubocop'
+  gem 'guard-yard'
+end

data/Guardfile

@@ -0,0 +1,94 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+## Uncomment and set this to only include directories you want to watch
+# directories %w(app lib config test spec features) \
+#  .select{|d| Dir.exists?(d) ? d : UI.warning("Directory #{d} does not exist")}
+
+## Note: if you are using the `directories` clause above and you are not
+## watching the project directory ('.'), then you will want to move
+## the Guardfile to a watched dir and symlink it back, e.g.
+#
+#  $ mkdir config
+#  $ mv Guardfile config/
+#  $ ln -s config/Guardfile .
+#
+# and, you'll have to watch "config/Guardfile" instead of "Guardfile"
+
+# Note: The cmd option is now required due to the increasing number of ways
+#       rspec may be run, below are examples of the most common uses.
+#  * bundler: 'bundle exec rspec'
+#  * bundler binstubs: 'bin/rspec'
+#  * spring: 'bin/rspec' (This will use spring if running and you have
+#                          installed the spring binstubs per the docs)
+#  * zeus: 'zeus rspec' (requires the server to be started separately)
+#  * 'just' rspec: 'rspec'
+
+guard :rspec, cmd: 'bundle exec rspec' do
+  require 'guard/rspec/dsl'
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # Feel free to open issues for suggestions and improvements
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+
+  # Rails files
+  rails = dsl.rails(view_extensions: %w(erb haml slim))
+  dsl.watch_spec_files_for(rails.app_files)
+  dsl.watch_spec_files_for(rails.views)
+
+  watch(rails.controllers) do |m|
+    [
+      rspec.spec.call("routing/#{m[1]}_routing"),
+      rspec.spec.call("controllers/#{m[1]}_controller"),
+      rspec.spec.call("acceptance/#{m[1]}")
+    ]
+  end
+
+  # Rails config changes
+  watch(rails.spec_helper)     { rspec.spec_dir }
+  watch(rails.routes)          { "#{rspec.spec_dir}/routing" }
+  watch(rails.app_controller)  { "#{rspec.spec_dir}/controllers" }
+
+  # Capybara features specs
+  watch(rails.view_dirs)     { |m| rspec.spec.call("features/#{m[1]}") }
+  watch(rails.layouts)       { |m| rspec.spec.call("features/#{m[1]}") }
+
+  # Turnip features and steps
+  watch(%r{^spec/acceptance/(.+)\.feature$})
+  watch(%r{^spec/acceptance/steps/(.+)_steps\.rb$}) do |m|
+    Dir[File.join("**/#{m[1]}.feature")][0] || 'spec/acceptance'
+  end
+end
+
+guard :rubocop do
+  watch(/.+\.rb$/)
+  watch(%r{(?:.+/)?\.rubocop\.yml$}) { |m| File.dirname(m[0]) }
+end
+
+guard 'yard' do
+  watch(%r{app/.+\.rb})
+  watch(%r{lib/.+\.rb})
+  watch(%r{ext/.+\.c})
+  watch(/.+\.md$/)
+end
+
+guard :bundler do
+  require 'guard/bundler'
+  require 'guard/bundler/verify'
+  helper = Guard::Bundler::Verify.new
+
+  files = ['Gemfile']
+  files += Dir['*.gemspec'] if files.any? { |f| helper.uses_gemspec?(f) }
+
+  # Assume files are symlinked from somewhere
+  files.each { |file| watch(helper.real_path(file)) }
+end

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010-2015 Douglas Stephen Lake-Hammond
+
+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,170 @@
+## `db_mod`
+
+Database enabled modules for ruby.
+
+## Description
+
+The `db_mod` gem is a simple framework that helps you organise your
+database access functions into modular libraries that can be included
+in your projects to give them selective access to facets of your data.
+
+## Usage
+
+### The database connection
+
+At its most basic, `db_mod` provides `db_connect`, `query`, and
+`transaction`:
+
+```ruby
+require 'db_mod'
+
+module MyFunctions
+  include DbMod
+
+  def get_stuff
+    query 'SELECT * FROM stuff'
+  end
+
+  def do_complicated_thing(input)
+    transaction do # calls BEGIN
+      query 'INSERT ...'
+      query 'UPDATE ...'
+      query 'DELETE ...'
+
+      output = query 'SELECT ...'
+      fail if output.empty? # calls ROLLBACK
+    end # calls COMMIT
+  end
+end
+
+include MyFunctions
+
+db_connect(
+  db: 'mydb',
+  host: 'localhost', # defaults to local socket
+  port: 5432,        # this is the default
+  user: 'myuser',    # default is ENV['USER']
+  pass: 'password'   # attempts trusted connection by default
+)
+
+get_stuff.each do |thing|
+  thing['id'] # => '1'
+  # ...
+end
+```
+
+#### `create`: Module instances
+
+Each module also comes with its own `create` function,
+which instantiates an object exposing all of the module's functions.
+
+```ruby
+# Standard connection options can be used.
+# db_connect will be called.
+db = MyFunctions.create db: 'mydb'
+
+# Or an existing connection object can be passed
+db = MyFunctions.create PGconn.connect # ...
+
+db.get_stuff
+```
+
+#### `@conn`: The connection object
+
+The connection created by `db_connect` or `create` will be stored
+in the instance variable `@conn`. This instance variable may be
+set explicitly instead of calling `db_connect`, allowing arbitrary
+sharing of database connections between modules and objects.
+See notes below on using this technique with `def_prepared`.
+
+### Module heirarchies
+
+By including multiple modules into the same class or object, they
+will all use the same connection object supplied by `db_connect`.
+This connection object is stored in the instance variable `@conn`
+and can be supplied manually:
+
+```ruby
+module DbAccess
+  # includes DbMod and defines do_things
+  include Db::Things
+
+  # includes DbMod and defines do_stuff
+  include Db::Stuff
+
+  def things_n_stuff
+    transaction do
+      do_things
+      do_stuff
+    end
+  end
+end
+
+db = DbAccess.create db: 'mydb'
+db.things_n_stuff
+```
+
+### `def_prepared`: Declaring SQL statements
+
+Modules which include `DbMod` can declare prepared statements
+using the module function `def_prepared`. These statements will
+be prepared on the connection when `db_connect` is called.
+A method will be defined in the module with the same name as
+the prepared statement, provided as a convenience for executing
+the statement:
+
+```ruby
+module Db
+  module Things
+    # Statements can use named parameters:
+    def_prepared :foo, <<-SQL
+      SELECT *
+        FROM foo
+       WHERE id = $id
+         AND b > $minimum_value
+         AND c > $minimum_value
+    SQL
+  end
+
+  module Stuff
+    # Indexed parameters also work:
+    def_prepared :bar, <<-SQL
+      INSERT INTO bar
+        (a, b, c)
+      VALUES
+        ($1, $2, $1)
+    SQL
+  end
+
+  module ComplicatedStuff
+    # Statements on included modules will also
+    # be executed when db_connect is called.
+    include Things
+    include Stuff
+
+    def complicated_thing!(id, min)
+      transaction do
+        foo(id: id, minimum_value: min).each do |thing|
+          bar(thing['a'], thing['b'])
+        end
+      end
+    end
+  end
+end
+
+include Db::ComplicatedStuff
+db_connect db: 'mydb'
+
+complicated_thing!(1, 2)
+```
+
+Note that if an existing connection is supplied to `create` or `@conn`
+then declared statements will not be automatically prepared. In this
+case the module function `prepare_all_statements(conn)` can be used
+to prepare all statements declared in the module or any included
+modules on the given connection.
+
+```ruby
+db = Db::ComplicatedStuff.create my_conn
+Db::ComplicatedStuff.prepare_all_statements my_conn
+```

data/Rakefile

@@ -0,0 +1,25 @@
+require 'rubygems'
+require 'bundler'
+Bundler.setup :default, :test, :development
+
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+end
+
+task :spec
+
+require 'rainbow/ext/string' unless String.respond_to?(:color)
+require 'rubocop/rake_task'
+RuboCop::RakeTask.new
+
+task default: [:rubocop, :spec]
+
+require 'yard'
+DOC_FILES = ['lib/**/*.rb', 'README.md']
+
+YARD::Rake::YardocTask.new(:doc) do |t|
+  t.files = DOC_FILES
+end

data/db_mod.gemspec

@@ -0,0 +1,26 @@
+$LOAD_PATH.push File.expand_path('../lib', __FILE__)
+require 'db_mod/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'db_mod'
+  s.version     = DbMod::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ['Doug Hammond']
+  s.email       = ['d.lakehammond@gmail.com']
+  s.summary     = 'Ruby framework for building modular db-access libs.'
+  s.description = 'Organize your database-intensive batch scripts with db_mod.'
+  s.license     = 'MIT'
+
+  s.add_runtime_dependency 'pg'
+  s.add_runtime_dependency 'docile'
+
+  s.add_development_dependency 'simplecov'
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'rspec-mocks'
+  s.add_development_dependency 'yard'
+  s.add_development_dependency 'bundler'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- spec/*`.split("\n")
+  s.require_paths = %w(lib)
+end

data/lib/db_mod/create.rb

@@ -0,0 +1,51 @@
+module DbMod
+  # Provides the +create+ function which
+  # is added to all modules which include {DbMod}.
+  # This function creates an object which exposes
+  # the functions defined in the module, allowing
+  # them to be used without namespace pollution.
+  #
+  # The function may be used in two forms. It may
+  # be called with an options hash, in which case
+  # {DbMod#db_connect} will be used to create a
+  # new connection object. Alternatively an
+  # existing connection object may be passed,
+  # which will be used for all database queries.
+  module Create
+    # Defines a module-specific +create+ function
+    # for a module that has just had {DbMod}
+    # included.
+    #
+    # @param mod [Module]
+    def self.setup(mod)
+      mod.class.instance_eval do
+        define_method(:create) do |options = {}|
+          @instantiable_class ||= Create.instantiable_class(self)
+
+          @instantiable_class.new(options)
+        end
+      end
+    end
+
+    private
+
+    # Creates a class which inherits from the given module
+    # and can be instantiated with either a connection object
+    # or some connection options.
+    #
+    # @param mod [Module]
+    def self.instantiable_class(mod)
+      Class.new do
+        include mod
+
+        define_method(:initialize) do |options|
+          if options.is_a? PGconn
+            self.conn = options
+          else
+            db_connect options
+          end
+        end
+      end
+    end
+  end
+end

data/lib/db_mod/exceptions/already_in_transaction.rb

@@ -0,0 +1,11 @@
+require_relative 'base'
+
+module DbMod
+  module Exceptions
+    # Raised when an attempt has been made to
+    # start a transaction on a connection that
+    # already has one open.
+    class AlreadyInTransaction < Base
+    end
+  end
+end

data/lib/db_mod/exceptions/base.rb

@@ -0,0 +1,7 @@
+module DbMod
+  module Exceptions
+    # Base class for db_mod exceptions
+    class Base < StandardError
+    end
+  end
+end

data/lib/db_mod/exceptions/connection_not_set.rb

@@ -0,0 +1,11 @@
+require_relative 'base'
+
+module DbMod
+  module Exceptions
+    # Raised when an attempt has been made to
+    # access db_mod functionality without first
+    # creating or supplying a connection object.
+    class ConnectionNotSet < Base
+    end
+  end
+end

data/lib/db_mod/exceptions/duplicate_statement_name.rb

@@ -0,0 +1,11 @@
+require_relative 'base'
+
+module DbMod
+  module Exceptions
+    # Raised when an attempt has been made to
+    # define or prepare statements for a module that includes
+    # more than one statement with the same name.
+    class DuplicateStatementName < Base
+    end
+  end
+end

data/lib/db_mod/exceptions.rb

@@ -0,0 +1,9 @@
+require_relative 'exceptions/connection_not_set'
+require_relative 'exceptions/already_in_transaction'
+require_relative 'exceptions/duplicate_statement_name'
+
+module DbMod
+  # Non-standard errors raised by db_mod
+  module Exceptions
+  end
+end

data/lib/db_mod/statements/params.rb

@@ -0,0 +1,108 @@
+module DbMod
+  module Statements
+    # Parsing and validation of query parameters
+    # for prepared SQL statements
+    module Params
+      # Assert that the named arguments given for the prepared statement
+      # with the given name satisfy expectations.
+      #
+      # @param expected [Array<Symbol>] the parameters expected to be present
+      # @param args [Hash] given parameters
+      # @return [Array] values to be passed to the prepared statement
+      def self.valid_named_args!(expected, args)
+        unless args.is_a? Hash
+          fail ArgumentError, "invalid argument: #{args.inspect}"
+        end
+
+        if args.size != expected.size
+          fail ArgumentError, "#{args.size} args given, #{expected.size} needed"
+        end
+
+        expected.map do |arg|
+          args[arg] || fail(ArgumentError, "missing arg #{arg}")
+        end
+      end
+
+      # Regex matching a numbered parameter
+      NUMBERED_PARAM = /\$\d+/
+
+      # Regex matching a named parameter
+      NAMED_PARAM = /\$[a-z]+(?:_[a-z]+)*/
+
+      # For validation, named or numbered parameter
+      NAMED_OR_NUMBERED = /^\$(?:\d+|[a-z]+(?:_[a-z]+)*)$/
+
+      # Parses parameters, named or numbered, from an SQL
+      # statement. See the {Prepared} module documentation
+      # for more. This method may modify the sql statement
+      # to change named parameters to numbered parameters.
+      # If the query uses numbered parameters, an integer
+      # will be returned that is the arity of the statement.
+      # If the query uses named parameters, an array of
+      # symbols will be returned, giving the order in which
+      # the named parameters should be fed into the
+      # statement.
+      #
+      # @param sql [String] statement to prepare
+      # @return [Fixnum,Array<Symbol>] description of
+      #   prepared statement's parameters
+      def self.parse_params!(sql)
+        Params.valid_sql_params! sql
+        numbered = sql.scan NUMBERED_PARAM
+        named = sql.scan NAMED_PARAM
+
+        if numbered.any?
+          fail ArgumentError, 'mixed named and numbered params' if named.any?
+          Params.parse_numbered_params! numbered
+        else
+          Params.parse_named_params! sql, named
+        end
+      end
+
+      # Fails if any parameters in an sql query aren't
+      # in the expected format. They must either be
+      # lower_case_a_to_z or digits only.
+      def self.valid_sql_params!(sql)
+        sql.scan(/\$\S+/) do |param|
+          unless param =~ NAMED_OR_NUMBERED
+            fail ArgumentError, "Invalid parameter #{param}"
+          end
+        end
+      end
+
+      # Validates the numbered parameters given (i.e. no gaps),
+      # and returns the parameter count.
+      #
+      # @param params [Array<String>] '$1','$2', etc...
+      # @return [Fixnum] parameter count
+      def self.parse_numbered_params!(params)
+        params.sort!
+        params.uniq!
+        if params.last[1..-1].to_i != params.length ||
+           params.first[1..-1].to_i != 1
+          fail ArgumentError, 'Invalid parameter list'
+        end
+
+        params.length
+      end
+
+      # Replaces the given list of named parameters in the
+      # query string with numbered parameters, and returns
+      # an array of symbols giving the order the parameters
+      # should be fed into the prepared statement for execution.
+      #
+      # @param sql [String] the SQL statement. Will be modified.
+      # @param params [Array<String>] '$one', '$two', etc...
+      # @return [Array<Symbol>] unique list of named parameters
+      def self.parse_named_params!(sql, params)
+        unique_params = params.uniq
+        params.each do |param|
+          index = unique_params.index(param)
+          sql[param] = "$#{index + 1}"
+        end
+
+        unique_params.map { |p| p[1..-1].to_sym }
+      end
+    end
+  end
+end