db_mod 0.0.1

data/lib/db_mod/statements/prepared.rb

@@ -0,0 +1,235 @@
+require_relative 'params'
+
+module DbMod
+  module Statements
+    # Provides the +def_prepared+ function which allows
+    # {DbMod} modules to declare prepared SQL statements
+    # that will be added to the database connection when
+    # {DbMod#db_connect} is called.
+    #
+    # For statements that are not prepared ahead of execution,
+    # see +def_statement+ in {DbMod::Statements::Statement}.
+    #
+    # def_prepared
+    # ------------
+    #
+    # +def_prepared+ accepts two parameters:
+    # * `name` [Symbol]: The name that will be given to
+    #   the prepared statement. A method will also be defined
+    #   on the module with the same name which will call the
+    #   statement and return the result.
+    # * `sql` [String]: The SQL statement to be prepared.
+    #   Parameters may be declared using the $ symbol followed
+    #   by a number ($1, $2, $3) or a name ($one, $two, $under_scores).
+    #   The two styles may not be mixed in the same statement.
+    #   The defined function can then be passed parameters
+    #   that will be used when the statement is executed.
+    #
+    # ### example
+    #
+    #  module MyModule
+    #    include DbMod
+    #
+    #    def_prepared :my_prepared, <<-SQL
+    #      SELECT *
+    #        FROM stuff
+    #       WHERE a = $1 AND b = $2
+    #    SQL
+    #
+    #    def_prepared :my_named_prepared, <<-SQL
+    #      SELECT *
+    #        FROM stuff
+    #       WHERE a = $a AND b = $b
+    #    SQL
+    #  end
+    #
+    #  include MyModule
+    #  db_connect db: 'mydb'
+    #  my_prepared(1,2)
+    #  my_named_prepared(a: 1, b: 2)
+    module Prepared
+      include Params
+
+      # Defines a module-specific +def_prepared+ function
+      # for a module that has just had {DbMod} included.
+      #
+      # @param mod [Module]
+      def self.setup(mod)
+        Prepared.define_def_prepared(mod)
+        Prepared.define_prepared_statements(mod)
+        Prepared.define_inherited_prepared_statements(mod)
+        Prepared.define_prepare_all_statements(mod)
+      end
+
+      private
+
+      # Merge the prepared statements from a module
+      # into a given hash. Fails if there are any
+      # duplicates.
+      #
+      # @param statements [Hash] named list of prepared statements
+      # @param klass [Class,Module] ancestor (hopefully a DbMod module)
+      #   to collect prepared statements from
+      def self.merge_statements(statements, klass)
+        return unless klass.respond_to? :prepared_statements
+        return if klass.prepared_statements.nil?
+
+        klass.prepared_statements.each do |name, sql|
+          fail DbMod::Exceptions::DuplicateStatementName if statements.key? name
+
+          statements[name] = sql
+        end
+      end
+
+      # Add a +def_prepared+ method definition to a module.
+      # This method allows modules to declare named SQL statements
+      # that will be prepared when the database connection is
+      # established, and that can be accessed via an instance
+      # method with the same name.
+      #
+      # @param mod [Module] a module with {DbMod} included
+      def self.define_def_prepared(mod)
+        mod.class.instance_eval do
+          define_method(:def_prepared) do |name, sql|
+            sql = sql.dup
+            name = name.to_sym
+
+            params = Params.parse_params! sql
+            prepared_statements[name] = sql
+            Prepared.define_prepared_method(mod, name, params)
+          end
+        end
+      end
+
+      # Defines +prepare_all_statements+, a module method which
+      # accepts a connection object and will prepare on it all of
+      # the prepared statements that have been declared on the
+      # module or any of its included modules.
+      #
+      # @param mod [Module] module that has {DbMod} included
+      def self.define_prepare_all_statements(mod)
+        mod.class.instance_eval do
+          define_method(:prepare_all_statements) do |conn|
+            inherited_prepared_statements.each do |name, sql|
+              conn.prepare(name.to_s, sql)
+            end
+          end
+        end
+      end
+
+      # Define a method in the module with the given name
+      # and parameters, that will call the prepared statement
+      # with the same name.
+      #
+      # @param mod [Module] module declaring the metho
+      # @param name [Symbol] method name
+      # @param params [Fixnum,Array<Symbol>]
+      #   expected parameter count, or a list of argument names.
+      #   An empty array produces a no-argument method.
+      def self.define_prepared_method(mod, name, params)
+        mod.expected_prepared_statement_parameters[name] = params
+
+        if params.is_a?(Array)
+          if params.empty?
+            define_no_args_prepared_method(mod, name)
+          else
+            define_named_args_prepared_method(mod, name, params)
+          end
+        else
+          define_fixed_args_prepared_method(mod, name, params)
+        end
+      end
+
+      # Define a no-argument method with the given name
+      # that will call the prepared statement with the
+      # same name.
+      #
+      # @param mod [Module] {DbMod} enabled module
+      #   where the method will be defined
+      # @param name [Symbol] name of the method to be defined
+      #   and the prepared query to be called.
+      def self.define_no_args_prepared_method(mod, name)
+        mod.instance_eval do
+          define_method name, ->() { conn.exec_prepared(name.to_s) }
+        end
+      end
+
+      # Define a method with the given name that accepts the
+      # given set of named parameters, that will call the prepared
+      # statement with the same name.
+      #
+      # @param mod [Module] {DbMod} enabled module
+      #   where the method will be defined
+      # @param name [Symbol] name of the method to be defined
+      #   and the prepared query to be called.
+      # @param params [Array<Symbol>] list of parameter names
+      def self.define_named_args_prepared_method(mod, name, params)
+        method = lambda do |*args|
+          unless args.size == 1
+            fail ArgumentError, "unexpected arguments: #{args.inspect}"
+          end
+          args = Params.valid_named_args! params, args.first
+          conn.exec_prepared(name.to_s, args)
+        end
+
+        mod.instance_eval { define_method(name, method) }
+      end
+
+      # Define a method with the given name that accepts a fixed
+      # number of arguments, that will call the prepared statement
+      # with the same name.
+      #
+      # @param mod [Module] {DbMod} enabled module
+      #   where the method will be defined
+      # @param name [Symbol] name of the method to be defined
+      #   and the prepared query to be called.
+      # @param count [Fixnum] arity of the defined method,
+      #   the number of parameters that the prepared statement
+      #   requires
+      def self.define_fixed_args_prepared_method(mod, name, count)
+        method = lambda do |*args|
+          unless args.size == count
+            fail ArgumentError, "#{args.size} args given, #{count} expected"
+          end
+
+          conn.exec_prepared(name.to_s, args)
+        end
+
+        mod.instance_eval { define_method(name, method) }
+      end
+
+      # Adds +prepared_statements+ to a module. This list of named
+      # prepared statements will be added to the connection when
+      # {DbMod#db_connect} is called.
+      #
+      # @param mod [Module]
+      def self.define_prepared_statements(mod)
+        mod.class.instance_eval do
+          define_method(:prepared_statements) do
+            @prepared_statements ||= {}
+          end
+
+          define_method(:expected_prepared_statement_parameters) do
+            @expected_prepared_statement_parameters ||= {}
+          end
+        end
+      end
+
+      # Adds +inherited_prepared_statements+ to a module. This list
+      # of named prepared statements declared on this module and all
+      # included modules will be added to the connection when
+      # {DbMod#db_connect} is called.
+      def self.define_inherited_prepared_statements(mod)
+        mod.class.instance_eval do
+          define_method(:inherited_prepared_statements) do
+            inherited = {}
+            ancestors.each do |klass|
+              Prepared.merge_statements(inherited, klass)
+            end
+            inherited
+          end
+        end
+      end
+    end
+  end
+end

data/lib/db_mod/statements/statement.rb

@@ -0,0 +1,29 @@
+module DbMod
+  module Statements
+    # Provides the +def_statement+ function which allows
+    # {DbMod} modules to declare SQL statements that can
+    # then be executed later using a specially defined
+    # instance method.
+    #
+    # To declare prepared statements, see +def_prepared+
+    # in {DbMod::Statements::Prepared}.
+    #
+    # def_statement
+    # -------------
+    #
+    # +def_statement+ accepts two parameters:
+    # * `name` [Symbol]: The name that will be given to the
+    #   method that can be used to execute the SQL statement
+    #   and return the result.
+    # * `sql` [String]: The SQL statement that shoul be executed
+    #   when the method is called. Parameters may be declared
+    #   using the $ symbol followed by a number ($1, $2, $3) or
+    #   a name ($one, $two, $under_scores). The two styles may
+    #   not be mixed in the same statement. The defined function
+    #   can then be passed parameters that will be used to fill
+    #   in the statement before execution.
+    module Statement
+      # Not yet implemented.
+    end
+  end
+end

data/lib/db_mod/statements.rb

@@ -0,0 +1,13 @@
+require_relative 'statements/statement'
+require_relative 'statements/prepared'
+
+module DbMod
+  # Functions allowing {DbMod} modules to declare
+  # SQL statements that can be called later via
+  # automatically declared instance methods.
+  #
+  # See {DbMod::Statements::Statement} for details on +def_statement+
+  # and {DbMod::Statements::Prepared} for details on +def_prepared+.
+  module Statements
+  end
+end

data/lib/db_mod/transaction.rb

@@ -0,0 +1,47 @@
+module DbMod
+  # Module which provides transaction blocks for db_mod
+  # enabled classes.
+  module Transaction
+    protected
+
+    # Create a transaction on the db_mod database connection.
+    # Calls +BEGIN+ then yields to the given block. Calls
+    # +COMMIT+ once the block yields, or +ROLLBACK+ if the
+    # block raises an exception.
+    #
+    # Not thread safe. May not be called from inside another
+    # transaction.
+    # @return [Object] the result of +yield+
+    def transaction
+      start_transaction!
+
+      result = yield
+
+      query 'COMMIT'
+
+      result
+    rescue
+      query 'ROLLBACK'
+      raise
+
+    ensure
+      end_transaction!
+    end
+
+    private
+
+    # Start the database transaction, or fail if
+    # one is already open.
+    def start_transaction!
+      fail DbMod::Exceptions::AlreadyInTransaction if @in_transaction
+      @in_transaction = true
+
+      query 'BEGIN'
+    end
+
+    # End the database transaction
+    def end_transaction!
+      @in_transaction = false
+    end
+  end
+end

data/lib/db_mod/version.rb

@@ -0,0 +1,5 @@
+# Version information
+module DbMod
+  # The current version of db_mod.
+  VERSION = '0.0.1'
+end

data/lib/db_mod.rb

@@ -0,0 +1,87 @@
+require 'pg'
+require_relative 'db_mod/exceptions'
+require_relative 'db_mod/transaction'
+require_relative 'db_mod/create'
+require_relative 'db_mod/statements'
+
+# This is the foundation module for enabling db_mod
+# support in an application. Including this module
+# will give your class or object the protected methods
+# {#db_connect} and {#conn=}, allowing the connection
+# to be set or created, as well as the methods {#conn},
+# {#query}, {#transaction}, and {#def_prepared}.
+module DbMod
+  include Transaction
+
+  # When a module includes {DbMod}, we define some
+  # class-level functions specific to the module.
+  def self.included(mod)
+    DbMod::Create.setup(mod)
+    DbMod::Statements::Prepared.setup(mod)
+  end
+
+  protected
+
+  # Database object to be used for all database
+  # interactions in this module.
+  # Use {#db_connect} to initialize the object.
+  attr_accessor :conn
+
+  # Shorthand for +conn.query+
+  def query(sql)
+    unless @conn
+      fail DbMod::Exceptions::ConnectionNotSet, 'db_connect not called'
+    end
+    conn.query(sql)
+  end
+
+  # Create a new database connection to be used
+  # for all database interactions in this module.
+  #
+  # @param options [Hash] database connection options
+  # @option options [String] :db
+  #   the name of the database to connect to
+  # @option options [String] :host
+  #   the host server for the database. If not supplied a local
+  #   posix socket connection will be attempted.
+  # @option options [Fixnum] :port
+  #   port number the database server is listening on. Default is 5432.
+  # @option options [String] :user
+  #   username for database authentication. If not supplied the
+  #   name of the user running the script will be used (i.e. ENV['USER'])
+  # @option options [String] :pass
+  #   password for database authentication. If not supplied then
+  #   trusted authentication will be attempted.
+  def db_connect(options = {})
+    db_defaults! options
+    @conn = db_connect! options
+    self.class.prepare_all_statements(@conn)
+  end
+
+  private
+
+  # Load any missing options from defaults
+  #
+  # @param options [Hash] see {#db_connect}
+  def db_defaults!(options)
+    fail ArgumentError, 'database name :db not supplied' unless options[:db]
+    options[:port] ||= 5432
+    options[:user] ||= ENV['USER']
+    options[:pass] ||= 'trusted?'
+  end
+
+  # Create the database object itself.
+  #
+  # @param options [Hash] see {#db_connect}
+  def db_connect!(options)
+    PGconn.connect(
+      options[:host],
+      options[:port],
+      '',
+      '',
+      options[:db],
+      options[:user],
+      options[:pass]
+    )
+  end
+end

data/spec/db_mod/create_spec.rb

@@ -0,0 +1,39 @@
+require 'spec_helper'
+
+module CreateTest
+  include DbMod
+
+  def do_thing
+    query 'SELECT 1'
+  end
+end
+
+describe DbMod::Create do
+  before do
+    @conn = instance_double 'PGconn'
+    allow(PGconn).to receive(:connect).and_return(@conn)
+  end
+
+  it 'creates module instances' do
+    expect(PGconn).to receive(:connect).with(
+      nil, 5432, '', '', 'testdb', ENV['USER'], 'trusted?'
+    )
+
+    test = CreateTest.create db: 'testdb'
+
+    expect(@conn).to receive(:query).with('SELECT 1')
+
+    test.do_thing
+  end
+
+  it 'can be supplied an existing connection' do
+    expect(PGconn).not_to receive(:connect)
+    expect(@conn).to receive(:is_a?).with(PGconn).and_return true
+
+    test = CreateTest.create @conn
+
+    expect(@conn).to receive(:query).with('SELECT 1')
+
+    test.do_thing
+  end
+end

data/spec/db_mod/statements/prepared_spec.rb

@@ -0,0 +1,155 @@
+require 'spec_helper'
+
+describe DbMod::Statements::Prepared do
+  subject do
+    Module.new do
+      include DbMod
+
+      def_prepared :one, <<-SQL
+        SELECT *
+          FROM foo
+         WHERE a = $1 AND b = $2 AND c = $1
+      SQL
+
+      def_prepared :two, <<-SQL
+        SELECT *
+          FROM foo
+         WHERE a = $a AND b = $b AND c = $a
+      SQL
+    end
+  end
+
+  before do
+    @conn = instance_double 'PGconn'
+    allow(PGconn).to receive(:connect).and_return(@conn)
+    allow(@conn).to receive(:prepare)
+  end
+
+  it 'adds statements when the connection is created' do
+    expect(@conn).to receive(:prepare) do |name, sql|
+      expect(%w(one two)).to include name
+      expect(sql.split(/\s+/m).join(' ').strip).to eq(
+        'SELECT * FROM foo WHERE a = $1 AND b = $2 AND c = $1'
+      )
+    end
+
+    subject.create db: 'testdb'
+  end
+
+  it 'executes statements with numbered params' do
+    db = subject.create db: 'testdb'
+
+    expect(@conn).to receive(:exec_prepared).with('one', [1, 'two'])
+    db.one(1, 'two')
+
+    expect { db.one 'too', 'many', 'args' }.to raise_exception ArgumentError
+  end
+
+  it 'executes statements with named params' do
+    db = subject.create db: 'testdb'
+
+    expect(@conn).to receive(:exec_prepared).with('two', [2, 'three'])
+    db.two(b: 'three', a: 2)
+
+    expect { db.two bad: 'arg', b: 1, a: 1 }.to raise_exception ArgumentError
+    expect { db.two b: 'a missing' }.to raise_exception ArgumentError
+    expect { db.two 1, 2 }.to raise_exception ArgumentError
+    expect { db.two 1 }.to raise_exception ArgumentError
+  end
+
+  it 'prepares and exposes inherited prepared statements' do
+    mod = subject
+    sub_module = Module.new do
+      include mod
+
+      def_prepared :three, <<-SQL
+        SELECT *
+          FROM foo
+         WHERE a = $1 OR b = $2 OR c = $1
+      SQL
+    end
+
+    expect(@conn).to receive(:prepare).exactly(3).times do |name, _|
+      expect(%w(one two three)).to include name
+    end
+
+    sub_module.create db: 'testdb'
+  end
+
+  it 'does not allow mixed parameter types' do
+    expect do
+      Module.new do
+        include DbMod
+
+        def_prepared :numbers_and_names, <<-SQL
+          SELECT *
+            FROM foo
+           WHERE this = $1 AND wont = $work
+        SQL
+      end
+    end.to raise_exception ArgumentError
+  end
+
+  it 'allows no parameters' do
+    expect do
+      mod = Module.new do
+        include DbMod
+
+        def_prepared :no_params, 'SELECT 1'
+      end
+
+      expect(@conn).to receive(:prepare).with('no_params', 'SELECT 1')
+      expect(@conn).to receive(:exec_prepared).with('no_params')
+
+      db = mod.create(db: 'testdb')
+      db.no_params
+
+      expect { db.no_params(1) }.to raise_exception ArgumentError
+    end.not_to raise_exception
+  end
+
+  it 'does not allow invalid parameters' do
+    %w(CAPITALS numb3rs_and_l3tt3rs).each do |param|
+      expect do
+        Module.new do
+          include DbMod
+
+          def_prepared :bad_params, %(
+            SELECT * FROM foo where bad = $#{param}
+          )
+        end
+      end.to raise_exception ArgumentError
+    end
+  end
+
+  it 'does not allow duplicate statement names' do
+    mod = subject
+    sub_module = Module.new do
+      include mod
+
+      def_prepared :one, <<-SQL
+        SELECT not FROM gonna WHERE work = $1
+      SQL
+    end
+
+    expect { sub_module.create db: 'testdb' }.to raise_exception(
+      DbMod::Exceptions::DuplicateStatementName
+    )
+  end
+
+  it 'validates numbered arguments' do
+    [
+      'a = $1 AND b = $2 AND c = $2 AND c = $4',
+      'a = $2 AND b = $2 AND c = $3',
+      'a = $1 AND b = $2 AND c = $4'
+    ].each do |params|
+      expect do
+        Module.new do
+          include DbMod
+
+          def_prepared :bad_params, "SELECT * FROM foo WHERE #{params}"
+        end
+      end.to raise_exception ArgumentError
+    end
+  end
+end

data/spec/db_mod/transaction_spec.rb

@@ -0,0 +1,69 @@
+require 'spec_helper'
+
+class TransactionTest
+  include DbMod
+
+  def connect
+    db_connect db: 'testdb'
+  end
+
+  def transaction!
+    transaction do
+      query 'SELECT 1'
+    end
+  end
+
+  def nested
+    transaction do
+      transaction do
+        # Not reached
+      end
+    end
+  end
+end
+
+describe DbMod::Transaction do
+  subject { TransactionTest.new }
+
+  before do
+    @conn = instance_double 'PGconn'
+    allow(@conn).to receive(:query)
+    allow(subject).to receive(:db_connect!).and_return @conn
+  end
+
+  describe '#transaction' do
+    it 'expects the connection to be set' do
+      expect { subject.transaction! }.to raise_exception(
+        DbMod::Exceptions::ConnectionNotSet
+      )
+    end
+
+    it 'calls BEGIN and COMMIT' do
+      subject.connect
+
+      expect(@conn).to receive(:query).with 'BEGIN'
+      expect(@conn).to receive(:query).with 'SELECT 1'
+      expect(@conn).to receive(:query).with 'COMMIT'
+
+      subject.transaction!
+    end
+
+    it 'calls ROLLBACK if there is a failure' do
+      subject.connect
+
+      expect(@conn).to receive(:query).with 'BEGIN'
+      expect(@conn).to receive(:query).with('SELECT 1').and_raise 'error'
+      expect(@conn).to receive(:query).with 'ROLLBACK'
+
+      expect { subject.transaction! }.to raise_exception 'error'
+    end
+
+    it 'guards against concurrent transactions' do
+      subject.connect
+
+      expect { subject.nested }.to raise_exception(
+        DbMod::Exceptions::AlreadyInTransaction
+      )
+    end
+  end
+end