Module: DbMod::Statements::Prepared

Defined in:
lib/db_mod/statements/prepared.rb

Overview

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 Statement.

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, $a_b). 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.

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)

Class Method Summary collapse

Class Method Details

.define_def_prepared(mod) ⇒ Object (private)

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.

Parameters:

  • mod (Module) —

    a module with DbMod included

Raises:

  • ArgumentError if there is a problem parsing method parameters from the SQL statement



69
70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/db_mod/statements/prepared.rb', line 69

def self.define_def_prepared(mod)
  class << mod
    define_method(:def_prepared) do |name, sql, &block|
      sql = sql.dup
      name = name.to_sym

      params = Parameters.parse_params! sql
      prepared_statements[name] = sql
      Prepared.define_prepared_method(self, name, params, &block)
    end
  end
end

.define_inherited_prepared_statements(mod) ⇒ Object (private)

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.

Parameters:

  • mod (Module) —

    where inherited_prepared_statements should be defined

See Also:



194
195
196
197
198
199
200
201
202
203
204
 
# File 'lib/db_mod/statements/prepared.rb', line 194

def self.define_inherited_prepared_statements(mod)
  class << mod
    define_method(:inherited_prepared_statements) do
      inherited = {}
      ancestors.each do |klass|
        Prepared.merge_statements(inherited, klass)
      end
      inherited
    end
  end
end

.define_no_args_prepared_method(mod, name, &block) { ... } ⇒ Object (private)

Define a no-argument method with the given name that will call the prepared statement with the same name.

Parameters:

  • mod (Module) —

    DbMod enabled module where the method will be defined

  • name (Symbol) —

    name of the method to be defined and the prepared query to be called.

  • block (Proc) —

    see Configuration::MethodConfiguration

Yields:

  • dsl method configuration object may be passed



148
149
150
151
 
# File 'lib/db_mod/statements/prepared.rb', line 148

def self.define_no_args_prepared_method(mod, name, &block)
  method = ->(*) { conn.exec_prepared(name.to_s) }
  Configuration.def_configurable mod, name, method, &block
end

.define_prepare_all_statements(mod) ⇒ Object (private)

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.

Parameters:

  • mod (Module) —

    module that has DbMod included

See Also:



89
90
91
92
93
94
95
96
97
 
# File 'lib/db_mod/statements/prepared.rb', line 89

def self.define_prepare_all_statements(mod)
  class << mod
    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_prepared_method(mod, name, params, &block) ⇒ Object (private)

Define a method in the given module with the given name and parameters, that will call the prepared statement with the same name.

Parameters:

  • mod (Module) —

    module declaring the method

  • name (Symbol) —

    method name

  • params (Fixnum, Array<Symbol>) —

    expected parameter count, or a list of argument names. An empty array produces a no-argument method.

  • block (Proc) —

    A dsl block may be passed, which will be evaluated using a Configuration::MethodConfiguration object as scope

See Also:

  • Configurable.def_configurable


130
131
132
133
134
135
136
 
# File 'lib/db_mod/statements/prepared.rb', line 130

def self.define_prepared_method(mod, name, params, &block)
  if params == []
    define_no_args_prepared_method(mod, name, &block)
  else
    define_prepared_method_with_args(mod, name, params, &block)
  end
end

.define_prepared_method_with_args(mod, name, params, &block) { ... } ⇒ Object (private)

Define a method on the given module with the given name and parameters that will call the prepared statement with the same name. Additional method configuration settings may be passed via a block.

Parameters:

  • mod (Module) —

    DbMod enabled module where the method will be defined

  • name (Symbol) —

    name of the method to be defined and the prepared query to be called.

  • params (Fixnum, Array<Symbol>) —

    expected parameter count, or a list of argument names. An empty array produces a no-argument method.

  • block (Proc) —

    see Configuration::MethodConfiguration

Yields:

  • dsl method configuration object may be passed



167
168
169
170
 
# File 'lib/db_mod/statements/prepared.rb', line 167

def self.define_prepared_method_with_args(mod, name, params, &block)
  method = ->(*args) { conn.exec_prepared(name.to_s, args) }
  Configuration.def_configurable(mod, name, method, params, &block)
end

.define_prepared_statements(mod) ⇒ Object (private)

Adds prepared_statements to a module. This list of named prepared statements will be added to the connection when DbMod#db_connect is called.

Parameters:

  • mod (Module)

See Also:



178
179
180
181
182
183
184
 
# File 'lib/db_mod/statements/prepared.rb', line 178

def self.define_prepared_statements(mod)
  class << mod
    define_method(:prepared_statements) do
      @prepared_statements ||= {}
    end
  end
end

.merge_statements(statements, klass) ⇒ Object (private)

Merge the prepared statements from a module into a given hash. Fails if there are any duplicates.

Parameters:

  • statements (Hash) —

    named list of prepared statements

  • klass (Class, Module) —

    ancestor (hopefully a DbMod module) to collect prepared statements from

See Also:



107
108
109
110
111
112
113
114
115
116
 
# File 'lib/db_mod/statements/prepared.rb', line 107

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

.setup(mod) ⇒ Object

Defines a module-specific def_prepared function for a module that has just had DbMod included.

Parameters:

  • mod (Module) —

    module including DbMod

See Also:



51
52
53
54
55
56
 
# File 'lib/db_mod/statements/prepared.rb', line 51

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