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
118 def call(bind_vars=OPTS, &block)
119   bind(bind_vars).run(&block)
120 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
131 def columns
132   orig_dataset.columns
133 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
136 def delayed_evaluation_sql_append(sql, delay)
137   raise Error, "delayed evaluations cannot be used in prepared statements" if @opts[:no_delayed_evaluations]
138   super
139 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
177 def inspect
178   "<#{visible_class_name}/PreparedStatement #{prepared_sql.inspect}>"
179 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
166 def literal_symbol_append(sql, v)
167   if @opts[:bind_vars] && /\A\$(.*)\z/ =~ v
168     literal_append(sql, prepared_arg($1.to_sym))
169   else
170     super
171   end
172 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
106 def orig_dataset
107   @opts[:orig_dataset]
108 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
124 def prepare(*)
125   raise Error, "cannot prepare an already prepared statement" unless allow_preparing_prepared_statements?
126   super
127 end
prepared_args() click to toggle source

The array/hash of bound variable placeholder names.

    # File lib/sequel/dataset/prepared_statements.rb
101 def prepared_args
102   @opts[:prepared_args]
103 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
112 def prepared_modify_values
113   @opts[:prepared_modify_values]
114 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
143 def prepared_sql
144   case prepared_type
145   when :select, :all, :each
146     # Most common scenario, so listed first.
147     select_sql
148   when :first, :single_value
149     clone(:limit=>1).select_sql
150   when :insert_select
151     insert_select_sql(*prepared_modify_values)
152   when :insert, :insert_pk
153     insert_sql(*prepared_modify_values)
154   when :update
155     update_sql(*prepared_modify_values)
156   when :delete
157     delete_sql
158   else
159     select_sql
160   end
161 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
96 def prepared_type
97   @opts[:prepared_type]
98 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
184 def run(&block)
185   case prepared_type
186   when :select, :all
187     all(&block)
188   when :each
189     each(&block)
190   when :insert_select
191     with_sql(prepared_sql).first
192   when :first
193     first
194   when :insert, :update, :delete
195     if opts[:returning] && supports_returning?(prepared_type)
196       returning_fetch_rows(prepared_sql)
197     elsif prepared_type == :delete
198       delete
199     else
200       public_send(prepared_type, *prepared_modify_values)
201     end
202   when :insert_pk
203     fetch_rows(prepared_sql){|r| return r.values.first}
204   when Array
205     # :nocov:
206     case prepared_type[0]
207     # :nocov:
208     when :map, :as_hash, :to_hash, :to_hash_groups
209       public_send(*prepared_type, &block) 
210     end
211   when :single_value
212     single_value
213   else
214     raise Error, "unsupported prepared statement type used: #{prepared_type.inspect}"
215   end
216 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
221 def prepared_arg(k)
222   @opts[:bind_vars][k]
223 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
226 def skip_symbol_cache?
227   true
228 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
233 def subselect_sql_append(sql, ds)
234   subselect_sql_dataset(sql, ds).prepared_sql
235 end
subselect_sql_dataset(sql, ds) click to toggle source
Calls superclass method
    # File lib/sequel/dataset/prepared_statements.rb
237 def subselect_sql_dataset(sql, ds)
238   super.clone(:prepared_args=>prepared_args, :bind_vars=>@opts[:bind_vars]).
239     send(:to_prepared_statement, :select, nil, :extend=>prepared_statement_modules)
240 end