Escape double quotes in DoubleQuotingString and improve documentation for SQL-safe string handling.

Author: smyrgeorge

sqlx4k/src/commonMain/kotlin/io/github/smyrgeorge/sqlx4k/impl/extensions/encode.kt

@@ -44,7 +44,11 @@ fun Any?.encodeValue(encoders: ValueEncoderRegistry): String {
             "'${replace("'", "''")}'"
         }
 
-        is DoubleQuotingString -> "\"${NoQuotingString(value).encodeValue(encoders)}\""
+        is DoubleQuotingString -> {
+            // Escape double quotes by doubling them (SQL standard for quoted identifiers)
+            // https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS
+            "\"${value.replace("\"", "\"\"")}\""
+        }
 
         is NoQuotingString -> {
             // Fast path: if no single quote present, avoid replace allocation

sqlx4k/src/commonMain/kotlin/io/github/smyrgeorge/sqlx4k/impl/types/DoubleQuotingString.kt

@@ -5,8 +5,15 @@ import kotlin.jvm.JvmInline
 /**
  * A wrapper class for representing a string value that applies double quotes.
  *
- * This class is useful in contexts where a string value needs to be explicitly quoted
- * with double quotation marks, such as when working with SQL identifiers or similar scenarios.
+ * This class is useful for SQL identifiers (table names, column names) that need to be
+ * quoted with double quotation marks. Double quotes within the value are automatically
+ * escaped by doubling them (SQL standard).
+ *
+ * ⚠️ **Best Practice**: Use this ONLY for trusted identifiers. For user-controlled table/column
+ * names, validate against a whitelist before using this class.
+ *
+ * Example: `DoubleQuotingString("user")` → `"user"`
+ * Escaping: `DoubleQuotingString("my\"table")` → `"my""table"`
  *
  * @property value The string value to be wrapped with double quotes.
  */

sqlx4k/src/commonMain/kotlin/io/github/smyrgeorge/sqlx4k/impl/types/NoQuotingString.kt

@@ -3,11 +3,17 @@ package io.github.smyrgeorge.sqlx4k.impl.types
 import kotlin.jvm.JvmInline
 
 /**
- * A wrapper class for representing a string value without applying quotes.
+ * A wrapper class for representing a string value without applying outer quotes.
  *
- * This class is helpful when working with raw SQL or similar contexts where quoting
- * the string is unnecessary or undesired. The value is directly returned
- * as-is when the `toString` function is invoked.
+ * ⚠️ **SECURITY WARNING**: This class bypasses standard SQL quoting and should ONLY be used for
+ * trusted, developer-controlled values such as SQL keywords (e.g., "CURRENT_TIMESTAMP", "DEFAULT").
+ * **NEVER use with user input** - it can lead to SQL injection vulnerabilities!
+ *
+ * While single quotes are escaped internally, the value is not wrapped in quotes, making it
+ * unsafe for user-controlled data.
+ *
+ * Safe usage: `NoQuotingString("CURRENT_TIMESTAMP")` or `NoQuotingString("DEFAULT")`
+ * Unsafe: `NoQuotingString(userInput)` ❌
  *
  * @property value The raw string value represented by this class.
  */