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
117 def call(bind_vars=OPTS, &block)
118   bind(bind_vars).run(&block)
119 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
130 def columns
131   orig_dataset.columns
132 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
135 def delayed_evaluation_sql_append(sql, delay)
136   raise Error, "delayed evaluations cannot be used in prepared statements" if @opts[:no_delayed_evaluations]
137   super
138 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
176 def inspect
177   "<#{visible_class_name}/PreparedStatement #{prepared_sql.inspect}>"
178 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
165 def literal_symbol_append(sql, v)
166   if @opts[:bind_vars] && /\A\$(.*)\z/ =~ v
167     literal_append(sql, prepared_arg($1.to_sym))
168   else
169     super
170   end
171 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
89 def log_sql
90   @opts[:log_sql]
91 end
orig_dataset() click to toggle source

The dataset that created this prepared statement.

    # File lib/sequel/dataset/prepared_statements.rb
105 def orig_dataset
106   @opts[:orig_dataset]
107 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
123 def prepare(*)
124   raise Error, "cannot prepare an already prepared statement" unless allow_preparing_prepared_statements?
125   super
126 end
prepared_args() click to toggle source

The array/hash of bound variable placeholder names.

    # File lib/sequel/dataset/prepared_statements.rb
100 def prepared_args
101   @opts[:prepared_args]
102 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
111 def prepared_modify_values
112   @opts[:prepared_modify_values]
113 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
142 def prepared_sql
143   case prepared_type
144   when :select, :all, :each
145     # Most common scenario, so listed first.
146     select_sql
147   when :first, :single_value
148     clone(:limit=>1).select_sql
149   when :insert_select
150     insert_select_sql(*prepared_modify_values)
151   when :insert, :insert_pk
152     insert_sql(*prepared_modify_values)
153   when :update
154     update_sql(*prepared_modify_values)
155   when :delete
156     delete_sql
157   else
158     select_sql
159   end
160 end
prepared_type() click to toggle source

The type of prepared statement, should be one of :select, :first, :insert, :update, :delete, or :single_value

   # File lib/sequel/dataset/prepared_statements.rb
95 def prepared_type
96   @opts[:prepared_type]
97 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
183 def run(&block)
184   case prepared_type
185   when :select, :all
186     all(&block)
187   when :each
188     each(&block)
189   when :insert_select
190     with_sql(prepared_sql).first
191   when :first
192     first
193   when :insert, :update, :delete
194     if opts[:returning] && supports_returning?(prepared_type)
195       returning_fetch_rows(prepared_sql)
196     elsif prepared_type == :delete
197       delete
198     else
199       public_send(prepared_type, *prepared_modify_values)
200     end
201   when :insert_pk
202     fetch_rows(prepared_sql){|r| return r.values.first}
203   when Array
204     # :nocov:
205     case prepared_type[0]
206     # :nocov:
207     when :map, :as_hash, :to_hash, :to_hash_groups
208       public_send(*prepared_type, &block) 
209     end
210   when :single_value
211     single_value
212   else
213     raise Error, "unsupported prepared statement type used: #{prepared_type.inspect}"
214   end
215 end

Private Instance Methods

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
220 def prepared_arg(k)
221   @opts[:bind_vars][k]
222 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
225 def skip_symbol_cache?
226   true
227 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
232 def subselect_sql_append(sql, ds)
233   subselect_sql_dataset(sql, ds).prepared_sql
234 end
subselect_sql_dataset(sql, ds) click to toggle source
Calls superclass method
    # File lib/sequel/dataset/prepared_statements.rb
236 def subselect_sql_dataset(sql, ds)
237   super.clone(:prepared_args=>prepared_args, :bind_vars=>@opts[:bind_vars]).
238     send(:to_prepared_statement, :select, nil, :extend=>prepared_statement_modules)
239 end