Fix ASCII-8BIT strings with ASCII-only content binding as BLOB instead of TEXT

ext/sqlite3/statement.c

@@ -216,6 +216,21 @@ 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))
+ *
  * See also #bind_params.
  */
 static VALUE

lib/sqlite3/statement.rb

@@ -42,6 +42,24 @@ def initialize(db, sql)
     # 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=?" )