diff --git a/ext/sqlite3/statement.c b/ext/sqlite3/statement.c index 7583f58e..aac10f1b 100644 --- a/ext/sqlite3/statement.c +++ b/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 diff --git a/lib/sqlite3/statement.rb b/lib/sqlite3/statement.rb index f0f1bcc0..d322fa65 100644 --- a/lib/sqlite3/statement.rb +++ b/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=?" )