sqlite3 2.9.6 → 2.10.2

data/ext/sqlite3/exception.c

@@ -120,3 +120,98 @@ rb_sqlite3_raise_with_sql(sqlite3 *db, int status, const char *sql)
 
     rb_exc_raise(exception);
 }
+
+/* Each call into sqlite that can run callbacks pushes a frame on the current
+ * fiber's chain. A callback that fails records its rb_protect state in the top
+ * frame, and the call resumes Ruby's pending jump once sqlite returns. Ruby
+ * code that runs in between, such as a finalizer during an allocation, pushes
+ * its own frame for any nested call, so it never takes the outer call's jump.
+ * The chain is fiber-local because Ruby code inside a callback can switch
+ * threads or fibers, and a Ruby thread can move between native threads inside
+ * rb_protect. */
+typedef struct {
+    rb_sqlite3_callback_frame_t *top;
+} callback_frames_t;
+
+static const rb_data_type_t callback_frames_type = {
+    .wrap_struct_name = "SQLite3::CallbackFrames",
+    .function = {
+        .dfree = RUBY_TYPED_DEFAULT_FREE,
+    },
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY | RUBY_TYPED_WB_PROTECTED,
+};
+
+static ID id_callback_frames;
+
+/* Ruby code can overwrite or delete the fiber-local, so check its type. */
+static VALUE
+current_callback_frames_holder(void)
+{
+    VALUE holder = rb_thread_local_aref(rb_thread_current(), id_callback_frames);
+    return rb_typeddata_is_kind_of(holder, &callback_frames_type) ? holder : Qnil;
+}
+
+static callback_frames_t *
+current_callback_frames(void)
+{
+    VALUE holder = current_callback_frames_holder();
+    return NIL_P(holder) ? NULL : (callback_frames_t *)RTYPEDDATA_DATA(holder);
+}
+
+void
+rb_sqlite3_push_callback_frame(rb_sqlite3_callback_frame_t *frame)
+{
+    VALUE holder = current_callback_frames_holder();
+    callback_frames_t *frames;
+
+    if (NIL_P(holder)) {
+        holder = TypedData_Make_Struct(rb_cObject, callback_frames_t, &callback_frames_type, frames);
+        rb_thread_local_aset(rb_thread_current(), id_callback_frames, holder);
+    }
+    frames = (callback_frames_t *)RTYPEDDATA_DATA(holder);
+
+    frame->state = 0;
+    frame->prev = frames->top;
+    frame->holder = holder;
+    frames->top = frame;
+}
+
+int
+rb_sqlite3_pop_callback_frame(rb_sqlite3_callback_frame_t *frame)
+{
+    ((callback_frames_t *)RTYPEDDATA_DATA(frame->holder))->top = frame->prev;
+    return frame->state;
+}
+
+VALUE
+rb_sqlite3_protect_callback(VALUE (*body)(VALUE), VALUE data, int *failed)
+{
+    callback_frames_t *frames = current_callback_frames();
+    rb_sqlite3_callback_frame_t *frame = frames ? frames->top : NULL;
+    VALUE result;
+    int state;
+
+    if (frame && frame->state) {
+        *failed = 1;
+        return Qnil;
+    }
+
+    result = rb_protect(body, data, &state);
+    *failed = state != 0;
+
+    if (frame) {
+        frame->state = state;
+    } else if (state) {
+        /* sqlite ran the callback from a call that cannot resume the jump, such
+         * as Statement#reset!, so the error is dropped */
+        rb_set_errinfo(Qnil);
+    }
+
+    return result;
+}
+
+void
+init_sqlite3_exception(void)
+{
+    id_callback_frames = rb_intern("__sqlite3_callback_frames__");
+}

data/ext/sqlite3/exception.h

@@ -9,4 +9,25 @@ void rb_sqlite3_raise(sqlite3 *db, int status);
 void rb_sqlite3_raise_msg(sqlite3 *db, int status, const char *msg);
 void rb_sqlite3_raise_with_sql(sqlite3 *db, int status, const char *sql);
 
+typedef struct rb_sqlite3_callback_frame {
+    int state;
+    struct rb_sqlite3_callback_frame *prev;
+    /* the frame lives on the C stack, so GC marks and pins this */
+    VALUE holder;
+} rb_sqlite3_callback_frame_t;
+
+/* A call into sqlite that can run callbacks is wrapped in a frame. sqlite
+ * cannot carry a raise or a throw, so a failed callback records its rb_protect
+ * state in the frame, and later callbacks skip their Ruby code. Pop the frame
+ * when sqlite returns, then resume the jump with rb_jump_tag if the returned
+ * state is nonzero. Run nothing but the sqlite call in between, because a
+ * raise there would skip the pop. */
+void rb_sqlite3_push_callback_frame(rb_sqlite3_callback_frame_t *frame);
+int rb_sqlite3_pop_callback_frame(rb_sqlite3_callback_frame_t *frame);
+
+/* Runs a callback's Ruby code for sqlite. Sets *failed if it did not complete. */
+VALUE rb_sqlite3_protect_callback(VALUE (*body)(VALUE), VALUE data, int *failed);
+
+void init_sqlite3_exception(void);
+
 #endif

data/ext/sqlite3/extconf.rb

@@ -65,7 +65,10 @@ module Sqlite3
               "-DSQLITE_ENABLE_DBPAGE_VTAB=1",
               "-DSQLITE_ENABLE_DBSTAT_VTAB=1"
             ]
-            env["CFLAGS"] = [user_cflags, env["CFLAGS"], more_cflags].flatten.join(" ")
+            # sqlite >= 3.54 requires Vista APIs, same as ruby's default target. Placed first so a
+            # user-defined _WIN32_WINNT takes precedence.
+            windows_cflags = windows? ? ["-D_WIN32_WINNT=0x0600"] : []
+            env["CFLAGS"] = [windows_cflags, user_cflags, env["CFLAGS"], more_cflags].flatten.join(" ")
             recipe.configure_options += env.slice(*ENV_ALLOWLIST)
               .map { |key, value| "#{key}=#{value.strip}" }
           end
@@ -115,9 +118,10 @@ module Sqlite3
 
         abort_could_not_find(libname) unless find_library(libname, "sqlite3_libversion_number", "sqlite3.h")
 
-        # Truffle Ruby doesn't support this yet:
+        # Ruby 3.0+, but not on every implementation:
         # https://github.com/oracle/truffleruby/issues/3408
         have_func("rb_enc_interned_str_cstr")
+        have_func("rb_enc_interned_str")
 
         # Functions defined in 1.9 but not 1.8
         have_func("rb_proc_arity")
@@ -139,6 +143,8 @@ module Sqlite3
         have_func("sqlite3_prepare_v2")
         have_func("sqlite3_db_name", "sqlite3.h") # v3.39.0
         have_func("sqlite3_error_offset", "sqlite3.h") # v3.38.0
+        have_func("sqlite3_serialize", "sqlite3.h") # v3.23.0
+        have_func("sqlite3_deserialize", "sqlite3.h") # v3.23.0
 
         have_type("sqlite3_int64", "sqlite3.h")
         have_type("sqlite3_uint64", "sqlite3.h")

data/ext/sqlite3/sqlite3.c

@@ -60,6 +60,19 @@ bignum_to_int64(VALUE value, sqlite3_int64 *result)
 #endif
 }
 
+void
+rb_sqlite3_pin_array_and_contents(VALUE ary)
+{
+    long i;
+
+    if (NIL_P(ary) || !ary) { return; }
+
+    rb_gc_mark(ary);
+    for (i = 0; i < RARRAY_LEN(ary); i++) {
+        rb_gc_mark(RARRAY_AREF(ary, i));
+    }
+}
+
 static VALUE
 libversion(VALUE UNUSED(klass))
 {
@@ -191,6 +204,7 @@ Init_sqlite3_native(void)
     sqlite3_initialize();
 #endif
 
+    init_sqlite3_exception();
     init_sqlite3_constants();
     init_sqlite3_database();
     init_sqlite3_statement();

data/ext/sqlite3/sqlite3_ruby.h

@@ -45,4 +45,7 @@ extern VALUE cSqlite3Blob;
 
 int bignum_to_int64(VALUE big, sqlite3_int64 *result);
 
+/* Pinning a collection doesn't pin what's in it, hence both. */
+void rb_sqlite3_pin_array_and_contents(VALUE ary);
+
 #endif

data/ext/sqlite3/statement.c

@@ -31,7 +31,7 @@ statement_memsize(const void *data)
 }
 
 static const rb_data_type_t statement_type = {
-    "SQLite3::Backup",
+    "SQLite3::Statement",
     {
         NULL,
         statement_deallocate,
@@ -54,8 +54,9 @@ prepare(VALUE self, VALUE db, VALUE sql)
 {
     sqlite3RubyPtr db_ctx = sqlite3_database_unwrap(db);
     sqlite3StmtRubyPtr ctx;
-    const char *tail = NULL;
-    int status;
+    const char *sql_cstr, *tail = NULL;
+    rb_sqlite3_callback_frame_t frame;
+    int sql_len, status, callback_state;
 
     StringValue(sql);
 
@@ -66,20 +67,26 @@ prepare(VALUE self, VALUE db, VALUE sql)
      * variable will keep it from being GCed. */
     ctx->db = db_ctx;
 
+    timespecclear(&db_ctx->stmt_deadline);
+
+    sql_cstr = StringValuePtr(sql);
+    sql_len = RSTRING_LENINT(sql);
+
+    rb_sqlite3_push_callback_frame(&frame);
 #ifdef HAVE_SQLITE3_PREPARE_V2
     status = sqlite3_prepare_v2(
 #else
     status = sqlite3_prepare(
 #endif
                  db_ctx->db,
-                 (const char *)StringValuePtr(sql),
-                 (int)RSTRING_LEN(sql),
+                 sql_cstr,
+                 sql_len,
                  &ctx->st,
                  &tail
              );
+    if ((callback_state = rb_sqlite3_pop_callback_frame(&frame))) { rb_jump_tag(callback_state); }
 
     CHECK_PREPARE(db_ctx->db, status, StringValuePtr(sql));
-    timespecclear(&db_ctx->stmt_deadline);
 
     return rb_utf8_str_new_cstr(tail);
 }
@@ -124,7 +131,8 @@ step(VALUE self)
 {
     sqlite3StmtRubyPtr ctx;
     sqlite3_stmt *stmt;
-    int value, length;
+    rb_sqlite3_callback_frame_t frame;
+    int value, length, callback_state;
     VALUE list;
     rb_encoding *internal_encoding;
 
@@ -139,14 +147,17 @@ step(VALUE self)
 
     stmt = ctx->st;
 
+    if (!sqlite3_stmt_busy(stmt)) {
+        timespecclear(&ctx->db->stmt_deadline);
+    }
+
+    rb_sqlite3_push_callback_frame(&frame);
     value = sqlite3_step(stmt);
-    if (rb_errinfo() != Qnil) {
-        /* some user defined function was invoked as a callback during step and
-         * it raised an exception that has been suppressed until step returns.
-         * Now re-raise it. */
-        VALUE exception = rb_errinfo();
-        rb_set_errinfo(Qnil);
-        rb_exc_raise(exception);
+    if ((callback_state = rb_sqlite3_pop_callback_frame(&frame))) { rb_jump_tag(callback_state); }
+
+    if (value == SQLITE_DONE) {
+        ctx->done_p = 1;
+        return Qnil;
     }
 
     length = sqlite3_column_count(stmt);
@@ -195,10 +206,6 @@ step(VALUE self)
             }
         }
         break;
-        case SQLITE_DONE:
-            ctx->done_p = 1;
-            return Qnil;
-            break;
         default:
             sqlite3_reset(stmt);
             ctx->done_p = 0;
@@ -216,6 +223,25 @@ step(VALUE self)
  * Fixnum, it is treated as an index for a positional placeholder.
  * Otherwise it is used as the name of the placeholder to bind to.
  *
+ * Type mapping from Ruby to SQLite3:
+ * - +nil+        → NULL
+ * - Integer      → INTEGER (or REAL when outside the signed int64 range)
+ * - Float        → REAL
+ * - SQLite3::Blob → BLOB
+ * - String with Encoding::ASCII_8BIT (a.k.a. BINARY) → BLOB
+ * - String with Encoding::UTF_16LE or Encoding::UTF_16BE → TEXT (bound as UTF-16)
+ * - String (all other encodings) → TEXT (re-encoded to UTF-8 if necessary)
+ * - Any other type → raises RuntimeError
+ *
+ * Note: if you have a string with only ASCII characters but ASCII-8BIT
+ * encoding and want it bound as TEXT rather than BLOB, re-encode it first:
+ *
+ *   stmt.bind_param(1, my_binary_str.encode(Encoding::UTF_8))
+ *
+ * The value that this method binds stays bound when you execute or reset the
+ * statement. To change the value, bind a new value to the same parameter. To
+ * clear all values, call #clear_bindings!.
+ *
  * See also #bind_params.
  */
 static VALUE
@@ -254,7 +280,7 @@ bind_param(VALUE self, VALUE key, VALUE value)
                              ctx->st,
                              index,
                              (const char *)StringValuePtr(value),
-                             (int)RSTRING_LEN(value),
+                             RSTRING_LENINT(value),
                              SQLITE_TRANSIENT
                          );
             } else {
@@ -265,7 +291,7 @@ bind_param(VALUE self, VALUE key, VALUE value)
                                  ctx->st,
                                  index,
                                  (const char *)StringValuePtr(value),
-                                 (int)RSTRING_LEN(value),
+                                 RSTRING_LENINT(value),
                                  SQLITE_TRANSIENT
                              );
                 } else {
@@ -276,7 +302,7 @@ bind_param(VALUE self, VALUE key, VALUE value)
                                  ctx->st,
                                  index,
                                  (const char *)StringValuePtr(value),
-                                 (int)RSTRING_LEN(value),
+                                 RSTRING_LENINT(value),
                                  SQLITE_TRANSIENT
                              );
                 }
@@ -311,8 +337,11 @@ bind_param(VALUE self, VALUE key, VALUE value)
 
 /* call-seq: stmt.reset!
  *
- * Resets the statement. This is typically done internally, though it might
- * occasionally be necessary to manually reset the statement.
+ * Resets the statement. The library usually calls this method for you, but
+ * you can also call it yourself.
+ *
+ * This method does not clear the values that you bound to the parameters. To
+ * clear them, call #clear_bindings!.
  */
 static VALUE
 reset_bang(VALUE self)
@@ -333,8 +362,11 @@ reset_bang(VALUE self)
 
 /* call-seq: stmt.clear_bindings!
  *
- * Resets the statement. This is typically done internally, though it might
- * occasionally be necessary to manually reset the statement.
+ * Sets the value of each parameter in the statement to NULL.
+ *
+ * The values that you bind with #bind_param, #bind_params, or #execute stay
+ * bound when you execute or reset the statement. Call this method to clear
+ * them.
  */
 static VALUE
 clear_bindings_bang(VALUE self)
@@ -398,6 +430,33 @@ interned_utf8_cstr(const char *str)
 }
 #endif
 
+/* Like interned_utf8_cstr, but ASCII-downcases as it copies. */
+static VALUE
+interned_downcased_utf8_cstr(const char *str)
+{
+#if HAVE_RB_ENC_INTERNED_STR
+    VALUE tmp, ret;
+    char *buf;
+    size_t i, len;
+
+    len = strlen(str);
+    buf = ALLOCV_N(char, tmp, len);
+
+    for (i = 0; i < len; i++) {
+        unsigned char c = (unsigned char)str[i];
+        buf[i] = (char)((c >= 'A' && c <= 'Z') ? c + ('a' - 'A') : c);
+    }
+
+    ret = rb_enc_interned_str(buf, (long)len, rb_utf8_encoding());
+    ALLOCV_END(tmp);
+    return ret;
+#else
+    VALUE rb_str = rb_funcall(rb_utf8_str_new_cstr(str), rb_intern("downcase"), 1,
+                              ID2SYM(rb_intern("ascii")));
+    return rb_funcall(rb_str, rb_intern("-@"), 0);
+#endif
+}
+
 /* call-seq: stmt.column_name(index)
  *
  * Get the column name at +index+.  0 based.
@@ -425,7 +484,8 @@ column_name(VALUE self, VALUE index)
 
 /* call-seq: stmt.column_decltype(index)
  *
- * Get the column type at +index+.  0 based.
+ * Get the declared type of the column at +index+, as a UTF-8 string.  0 based.
+ * Returns +nil+ if the column has no declared type, such as an expression.
  */
 static VALUE
 column_decltype(VALUE self, VALUE index)
@@ -440,7 +500,24 @@ column_decltype(VALUE self, VALUE index)
 
     name = sqlite3_column_decltype(ctx->st, (int)NUM2INT(index));
 
-    if (name) { return rb_str_new2(name); }
+    if (name) { return rb_utf8_str_new_cstr(name); }
+    return Qnil;
+}
+
+static VALUE
+column_decltype_downcased(VALUE self, VALUE index)
+{
+    sqlite3StmtRubyPtr ctx;
+    const char *name;
+
+    TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);
+
+    REQUIRE_LIVE_DB(ctx);
+    REQUIRE_OPEN_STMT(ctx);
+
+    name = sqlite3_column_decltype(ctx->st, (int)NUM2INT(index));
+
+    if (name) { return interned_downcased_utf8_cstr(name); }
     return Qnil;
 }
 
@@ -733,6 +810,7 @@ init_sqlite3_statement(void)
     rb_define_method(cSqlite3Statement, "memused", memused, 0);
 #endif
 
+    rb_define_private_method(cSqlite3Statement, "column_decltype_downcased", column_decltype_downcased, 1);
     rb_define_private_method(cSqlite3Statement, "prepare", prepare, 2);
     rb_define_private_method(cSqlite3Statement, "stats_as_hash", stats_as_hash, 0);
     rb_define_private_method(cSqlite3Statement, "stat_for", stat_for, 1);

data/ext/sqlite3/timespec.h

@@ -15,6 +15,15 @@
 			(vsp)->tv_nsec += 1000000000L;			\
 		}							\
 	} while (0)
+#define	timespecadd(tsp, usp, vsp)					\
+	do {								\
+		(vsp)->tv_sec = (tsp)->tv_sec + (usp)->tv_sec;		\
+		(vsp)->tv_nsec = (tsp)->tv_nsec + (usp)->tv_nsec;	\
+		if ((vsp)->tv_nsec >= 1000000000L) {			\
+			(vsp)->tv_sec++;				\
+			(vsp)->tv_nsec -= 1000000000L;			\
+		}							\
+	} while (0)
 #define timespecafter(tsp, usp)						\
 	(((tsp)->tv_sec > (usp)->tv_sec) ||				\
 	 ((tsp)->tv_sec == (usp)->tv_sec && (tsp)->tv_nsec > (usp)->tv_nsec))

data/lib/sqlite3/database.rb

@@ -579,6 +579,25 @@ module SQLite3
       self
     end
 
+    # The "handler" that #define_aggregator hands to define_aggregator2, which
+    # only needs something that responds to +new+ (a fresh aggregator for each
+    # aggregate invocation) and +arity+.
+    class AggregatorFactory # :nodoc:
+      def initialize(template)
+        @template = template
+      end
+
+      def new
+        @template.clone
+      end
+
+      # this is what sqlite3_obj_method_arity did before
+      def arity
+        @template.method(:step).arity
+      end
+    end
+    private_constant :AggregatorFactory
+
     # Define an aggregate function named +name+ using a object template
     # object +aggregator+. +aggregator+ must respond to +step+ and +finalize+.
     # +step+ will be called with row information and +finalize+ must return the
@@ -592,36 +611,7 @@ module SQLite3
     def define_aggregator(name, aggregator)
       # Previously, this has been implemented in C. Now this is just yet
       # another compatibility shim
-      proxy = Class.new do
-        @template = aggregator
-        @name = name
-
-        def self.template
-          @template
-        end
-
-        def self.name
-          @name
-        end
-
-        def self.arity
-          # this is what sqlite3_obj_method_arity did before
-          @template.method(:step).arity
-        end
-
-        def initialize
-          @klass = self.class.template.clone
-        end
-
-        def step(*args)
-          @klass.step(*args)
-        end
-
-        def finalize
-          @klass.finalize
-        end
-      end
-      define_aggregator2(proxy, name)
+      define_aggregator2(AggregatorFactory.new(aggregator), name)
       self
     end
 

data/lib/sqlite3/resultset.rb

@@ -16,8 +16,12 @@ module SQLite3
       @stmt = stmt
     end
 
-    # Reset the cursor, so that a result set which has reached end-of-file
-    # can be rewound and reiterated.
+    # Resets the cursor to the first row, so that you can iterate over the
+    # result set again after it reaches the end.
+    #
+    # This method binds each argument to the statement with
+    # Statement#bind_params. The values that you bound before stay bound
+    # unless you bind new values to the same parameters.
     def reset(*bind_params)
       @stmt.reset!
       @stmt.bind_params(*bind_params)
@@ -43,20 +47,26 @@ module SQLite3
       @stmt.step
     end
 
-    # Required by the Enumerable mixin. Provides an internal iterator over the
-    # rows of the result set.
+    # With a block given, iterates over the rows of the result set, passing each
+    # to the block. Returns self.
+    # With no block given, returns a new Enumerator.
     def each
+      return enum_for(__method__) unless block_given?
       while (node = self.next)
         yield node
       end
+      self
     end
 
-    # Provides an internal iterator over the rows of the result set where
-    # each row is yielded as a hash.
+    # With a block given, iterates over the rows of the result set, passing each
+    # to the block as a hash. Returns self.
+    # With no block given, returns a new Enumerator.
     def each_hash
+      return enum_for(__method__) unless block_given?
       while (node = next_hash)
         yield node
       end
+      self
     end
 
     # Closes the statement that spawned this result set.

data/lib/sqlite3/statement.rb

@@ -42,11 +42,33 @@ module SQLite3
     # See Database#execute for a description of the valid placeholder
     # syntaxes.
     #
+    # Type mapping from Ruby to SQLite3:
+    # - +nil+                            → NULL
+    # - Integer                          → INTEGER (or REAL when outside the signed int64 range)
+    # - Float                            → REAL
+    # - SQLite3::Blob                    → BLOB
+    # - String with Encoding::ASCII_8BIT
+    #   (a.k.a. BINARY)                  → BLOB
+    # - String with Encoding::UTF_16LE
+    #   or Encoding::UTF_16BE            → TEXT (bound as UTF-16)
+    # - String (all other encodings)     → TEXT (re-encoded to UTF-8 if needed)
+    # - Any other type                   → raises RuntimeError
+    #
+    # Note: a String with Encoding::ASCII_8BIT (BINARY) is always bound as a
+    # BLOB, even when its bytes are all valid ASCII. If you want such a string
+    # compared or stored as TEXT, re-encode it before binding:
+    #
+    #   stmt.bind_params(my_binary_str.encode(Encoding::UTF_8))
+    #
     # Example:
     #
     #   stmt = db.prepare( "select * from table where a=? and b=?" )
     #   stmt.bind_params( 15, "hello" )
     #
+    # The values that this method binds stay bound when you execute or reset
+    # the statement. To change a value, bind a new value to the same
+    # parameter. To clear all values, call #clear_bindings!.
+    #
     # See also #execute, #bind_param, Statement#bind_param, and
     # Statement#bind_params.
     def bind_params(*bind_vars)
@@ -65,7 +87,17 @@ module SQLite3
     # statement's virtual machine. If a block was given, the new ResultSet will
     # be yielded to it; otherwise, the ResultSet will be returned.
     #
-    # Any parameters will be bound to the statement using #bind_params.
+    # This method binds each argument to the statement with #bind_params. The
+    # values stay bound after this method returns. If a later call to #execute
+    # does not give a value for a parameter, the statement uses the value from
+    # the earlier call. To set all parameters to NULL before you execute the
+    # statement again, call #clear_bindings!:
+    #
+    #   stmt = db.prepare( "select :a, :b" )
+    #   stmt.execute( a: 1, b: 2 ).to_a  # => [[1, 2]]
+    #   stmt.execute( a: 3 ).to_a        # => [[3, 2]]
+    #   stmt.clear_bindings!
+    #   stmt.execute( a: 3 ).to_a        # => [[3, nil]]
     #
     # Example:
     #
@@ -74,7 +106,7 @@ module SQLite3
     #     ...
     #   end
     #
-    # See also #bind_params, #execute!.
+    # See also #bind_params, #execute!, #clear_bindings!.
     def execute(*bind_vars)
       reset! if active? || done?
 
@@ -91,7 +123,9 @@ module SQLite3
     # rows returned by executing the statement. Otherwise, each row will be
     # yielded to the block.
     #
-    # Any parameters will be bound to the statement using #bind_params.
+    # This method binds each argument to the statement with #bind_params. The
+    # values stay bound after this method returns. For more information, see
+    # #execute.
     #
     # Example:
     #
@@ -112,9 +146,9 @@ module SQLite3
       !done?
     end
 
-    # Return an array of the column names for this statement. Note that this
-    # may execute the statement in order to obtain the metadata; this makes it
-    # a (potentially) expensive operation.
+    # Return a frozen array of the column names for this statement, as frozen
+    # UTF-8 strings. Note that this may execute the statement in order to
+    # obtain the metadata; this makes it a (potentially) expensive operation.
     def columns
       get_metadata unless @columns
       @columns
@@ -128,9 +162,11 @@ module SQLite3
       end
     end
 
-    # Return an array of the data types for each column in this statement. Note
-    # that this may execute the statement in order to obtain the metadata; this
-    # makes it a (potentially) expensive operation.
+    # Return a frozen array of the declared types of the columns in this
+    # statement, as frozen UTF-8 strings with ASCII letters downcased. A column
+    # with no declared type, such as an expression, has a +nil+ type. Note that
+    # this may execute the statement in order to obtain the metadata; this makes
+    # it a (potentially) expensive operation.
     def types
       must_be_open!
       get_metadata unless @types
@@ -180,11 +216,10 @@ module SQLite3
     def get_metadata
       @columns = Array.new(column_count) do |column|
         column_name column
-      end
+      end.freeze
       @types = Array.new(column_count) do |column|
-        val = column_decltype(column)
-        val&.downcase
-      end
+        column_decltype_downcased(column)
+      end.freeze
     end
   end
 end