module Sequel::Dataset::PreparedStatementMethods

Backbone of the prepared statement support. Grafts bind variable support into datasets by hijacking literal and using placeholders. By default, emulates prepared statements and bind variables by taking the hash of bind variables and directly substituting them into the query, which works on all databases, as it is no different from using the dataset without bind variables.

Public Instance Methods

call(bind_vars=OPTS, &block) click to toggle source

Sets the prepared_args to the given hash and runs the prepared statement.

    # File lib/sequel/dataset/prepared_statements.rb
124 def call(bind_vars=OPTS, &block)
125   bind(bind_vars).run(&block)
126 end
columns() click to toggle source

Send the columns to the original dataset, as calling it on the prepared statement can cause problems.

    # File lib/sequel/dataset/prepared_statements.rb
137 def columns
138   orig_dataset.columns
139 end
delayed_evaluation_sql_append(sql, delay) click to toggle source

Disallow use of delayed evaluations in prepared statements.

Calls superclass method
    # File lib/sequel/dataset/prepared_statements.rb
142 def delayed_evaluation_sql_append(sql, delay)
143   raise Error, "delayed evaluations cannot be used in prepared statements" if @opts[:no_delayed_evaluations]
144   super
145 end
inspect() click to toggle source

Programmer friendly string showing this is a prepared statement, with the prepared SQL it represents (which in general won’t have substituted variables).

    # File lib/sequel/dataset/prepared_statements.rb
183 def inspect
184   "<#{visible_class_name}/PreparedStatement #{prepared_sql.inspect}>"
185 end
literal_symbol_append(sql, v) click to toggle source

Changes the values of symbols if they start with $ and prepared_args is present. If so, they are considered placeholders, and they are substituted using prepared_arg.

Calls superclass method
    # File lib/sequel/dataset/prepared_statements.rb
172 def literal_symbol_append(sql, v)
173   if @opts[:bind_vars] && /\A\$(.*)\z/ =~ v
174     literal_append(sql, prepared_arg($1.to_sym))
175   else
176     super
177   end
178 end
log_sql() click to toggle source

Whether to log the full SQL query. By default, just the prepared statement name is generally logged on adapters that support native prepared statements.

   # File lib/sequel/dataset/prepared_statements.rb
90 def log_sql
91   @opts[:log_sql]
92 end
orig_dataset() click to toggle source

The dataset that created this prepared statement.

    # File lib/sequel/dataset/prepared_statements.rb
112 def orig_dataset
113   @opts[:orig_dataset]
114 end
prepare(*) click to toggle source

Raise an error if attempting to call prepare on an already prepared statement.

Calls superclass method
    # File lib/sequel/dataset/prepared_statements.rb
130 def prepare(*)
131   raise Error, "cannot prepare an already prepared statement" unless allow_preparing_prepared_statements?
132   super
133 end
prepared_args() click to toggle source

The array/hash of bound variable placeholder names.

    # File lib/sequel/dataset/prepared_statements.rb
107 def prepared_args
108   @opts[:prepared_args]
109 end
prepared_modify_values() click to toggle source

The argument to supply to insert and update, which may use placeholders specified by prepared_args

    # File lib/sequel/dataset/prepared_statements.rb
118 def prepared_modify_values
119   @opts[:prepared_modify_values]
120 end
prepared_sql() click to toggle source

Returns the SQL for the prepared statement, depending on the type of the statement and the prepared_modify_values.

    # File lib/sequel/dataset/prepared_statements.rb
149 def prepared_sql
150   case prepared_sql_type
151   when :select, :all, :each
152     # Most common scenario, so listed first.
153     select_sql
154   when :first, :single_value
155     clone(:limit=>1).select_sql
156   when :insert_select
157     insert_select_sql(*prepared_modify_values)
158   when :insert, :insert_pk
159     insert_sql(*prepared_modify_values)
160   when :update
161     update_sql(*prepared_modify_values)
162   when :delete
163     delete_sql
164   else
165     select_sql
166   end
167 end
prepared_sql_type() click to toggle source

The type of SQL to generate for the prepared statement. Generally the same as prepared_type, but can be different.

   # File lib/sequel/dataset/prepared_statements.rb
96 def prepared_sql_type
97   @opts[:prepared_sql_type] || prepared_type
98 end
prepared_type() click to toggle source

The type of prepared statement, which controls how the prepared statement handles results from the database.

    # File lib/sequel/dataset/prepared_statements.rb
102 def prepared_type
103   @opts[:prepared_type]
104 end

Protected Instance Methods

run(&block) click to toggle source

Run the method based on the type of prepared statement.

    # File lib/sequel/dataset/prepared_statements.rb
190 def run(&block)
191   case type = prepared_type
192   when :select, :all
193     with_sql_all(prepared_sql, &block)
194   when :each
195     with_sql_each(prepared_sql, &block)
196   when :insert_select, :first
197     with_sql_first(prepared_sql)
198   when :insert, :update, :delete
199     if opts[:returning] && supports_returning?(prepared_type)
200       returning_fetch_rows(prepared_sql)
201     elsif type == :delete
202       with_sql_delete(prepared_sql)
203     else
204       force_prepared_sql.public_send(type, *prepared_modify_values)
205     end
206   when :insert_pk, :single_value
207     with_sql_single_value(prepared_sql)
208   when Array
209     # :nocov:
210     case type[0]
211     # :nocov:
212     when :map, :as_hash, :to_hash, :to_hash_groups
213       force_prepared_sql.public_send(*type, &block) 
214     end
215   else
216     raise Error, "unsupported prepared statement type used: #{prepared_type.inspect}"
217   end
218 end

Private Instance Methods

force_prepared_sql() click to toggle source

If the prepared_sql_type does not match the prepared statement, return a clone that with the prepared SQL, to ensure the prepared_sql_type is respected.

    # File lib/sequel/dataset/prepared_statements.rb
224 def force_prepared_sql
225   if prepared_sql_type != prepared_type
226     with_sql(prepared_sql)
227   else
228     self
229   end
230 end
prepared_arg(k) click to toggle source

Returns the value of the prepared_args hash for the given key.

    # File lib/sequel/dataset/prepared_statements.rb
233 def prepared_arg(k)
234   @opts[:bind_vars][k]
235 end
skip_symbol_cache?() click to toggle source

The symbol cache should always be skipped, since placeholders are symbols.

    # File lib/sequel/dataset/prepared_statements.rb
238 def skip_symbol_cache?
239   true
240 end
subselect_sql_append(sql, ds) click to toggle source

Use a clone of the dataset extended with prepared statement support and using the same argument hash so that you can use bind variables/prepared arguments in subselects.

    # File lib/sequel/dataset/prepared_statements.rb
245 def subselect_sql_append(sql, ds)
246   subselect_sql_dataset(sql, ds).prepared_sql
247 end
subselect_sql_dataset(sql, ds) click to toggle source
Calls superclass method
    # File lib/sequel/dataset/prepared_statements.rb
249 def subselect_sql_dataset(sql, ds)
250   super.clone(:prepared_args=>prepared_args, :bind_vars=>@opts[:bind_vars]).
251     send(:to_prepared_statement, :select, nil, :extend=>prepared_statement_modules)
252 end