[flavorjones]

Motivation

A parameter passed to Statement#execute stays bound after that execution, as @jeremyevans reported in #740:

stmt = db.prepare "SELECT :a + :b"
stmt.execute(a: 1, b: 2).to_a # => [[3]]
stmt.execute(a: 2).to_a       # => [[4]], b is still 2
stmt.execute.to_a             # => [[4]]

Statement#execute binds its arguments with #bind_params and never undoes them. Values bound with #bind_params before #execute must still persist, so #execute cannot simply clear every binding:

stmt.bind_params(a: 1)
stmt.execute(b: 2).to_a # => [[3]]
stmt.execute(b: 3).to_a # => [[4]]

Details

SQLite has no API to read a bound value, so Statement#bind_param and #bind_params now record each value in a Hash on the statement, keyed by the parameter index SQLite resolved. An unfrozen String is recorded as a frozen copy made with String.new (or SQLite3::Blob.new), because SQLite copies its bytes at bind time and the caller may mutate it afterwards. String.new runs no subclass hooks, and the copy is made before binding.

#execute still binds its arguments through #bind_params and #bind_param, so subclasses that override them keep working, but those values are not recorded. After such an #execute, the next #execute or the next value bound by #bind_param or #bind_params calls sqlite3_clear_bindings() and rebinds the recorded values, so placeholders set only by the earlier #execute become NULL. #bind_param binds the new value before restoring, so a bind that raises on a running statement leaves that statement's bindings alone.

With this change, the first example returns [[3]], [[nil]], [[nil]]. A value passed to #execute also overrides a #bind_param value only for that execution.

Calling #bind_params with no values binds nothing and restores nothing. ResultSet#reset with no arguments therefore still rewinds with the values passed to #execute, as it did before.

#clear_bindings! also forgets the recorded values. Its documentation said it reset the statement; it now says it sets every placeholder to NULL.

#bind_param and #clear_bindings! are now Ruby methods wrapping the C implementations, which are private.

Additional information

Code that passes a value to #execute and expects a later #execute to reuse it must now bind that value with #bind_params.

The recorded Hash keeps the last value bound to each parameter alive until that parameter is rebound or #clear_bindings! is called. A cached statement therefore holds the last values bound with #bind_param or #bind_params. Except while an #execute overrides them, SQLite holds its own copy of the same values. On the path Rails uses (reset!, bind_params, to_a on a cached statement), recording costs one allocation per unfrozen String bound. On a one-row in-memory query binding an Integer and a String, that path takes 1.52 µs per call, against 1.23 µs with the recording removed (best of 4 runs of 500,000 calls).

Resolves #751.