[flavorjones]

Motivation

Fixes #751.

As reported in #751, parameters passed to Statement#execute stay bound after the call, so a later #execute that omits a parameter reuses the earlier value:

stmt = db.prepare("select :a, :b")
stmt.execute(a: 1, b: 2).to_a  # => [[1, 2]]
stmt.execute(a: 3).to_a        # => [[3, 2]]

#execute binds through #bind_params (statement.rb), and SQLite keeps bindings until they are cleared. Changing this would break code that relies on it (see #757, now closed), so I am documenting it instead.

Details

The docs for Statement#execute, #execute!, #bind_param, #bind_params, #reset! and ResultSet#reset now say that bound values persist across executions. #execute and the FAQ show the example above, and point to Statement#clear_bindings! to set every parameter back to NULL. The FAQ also notes that the Database#execute family prepares a new statement for each call, so it is unaffected.

The #clear_bindings! description was a copy of the one for #reset!; it now says what the method does.