Added type mappings tests and docs for ALL supported DBs

build-logic/src/main/kotlin/dfbuild.kodex.gradle.kts

@@ -63,6 +63,7 @@ afterEvaluate {
     )
 
     // use `project()` dependencies for connecting contextual KoDEx sources and -caches
+    // Any api/implementation/compileOnly project dependency is added as contextual context.
     val contextualProjects =
         sequenceOf(
             configurations.api,
@@ -94,7 +95,10 @@ afterEvaluate {
             ?.sourceDirectories
             ?.toList()
             ?: emptyList()
-    }.toSet()
+    }
+        // Adding the `:samples` module manually
+        .plus<List<File>>(listOf(findRootDir().resolve("samples/src/test/kotlin")))
+        .toSet()
 
     extension.contextualSourcesDirectories.convention(contextualProjectsSources)
 }

dataframe-jdbc/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/db/Sqlite.kt

@@ -50,28 +50,7 @@ import java.time.LocalTime as JavaLocalTime
  * Used as a result of [DbType.getPreprocessedValueType].
  *
  * ### Example
- * ```
- * val format = LocalDateTime.Format {
- *     year(); char('-'); monthNumber(); char('-'); day()
- *     char(' ')
- *     hour(); char(':'); minute(); char(':'); second()
- *     chars(" UTC")
- * }
- *
- * val sqliteCustom = Sqlite.withCustomConverters {
- *     // Every column declared with "MY_DATETIME" type is parsed from custom text into Instant.
- *     forType("MY_DATETIME") { raw: String? ->
- *         raw?.let { LocalDateTime.parse(it, format).toInstant(TimeZone.UTC) }
- *     }
- *     // Identity shortcut — pin the declared type LONGVARCHAR to `String?` regardless of
- *     // how SQLite's type affinity would classify it.
- *     forType<String?>("LONGVARCHAR")
- *     // The "ratio" column overrides its declared type — read as Double.
- *     forColumn("ratio") { raw: String -> raw.toDouble() }
- * }
- *
- * val df = DataFrame.readSqlTable(connection, "events", dbType = sqliteCustom)
- * ```
+ * @sample [org.jetbrains.kotlinx.dataframe.samples.io.jdbc.SqliteSamples.complexSqlite]
  */
 public data class SqliteCustomTypeConverter<T, R>(
     val expectedType: KType,
@@ -94,28 +73,7 @@ public data class SqliteCustomTypeConverter<T, R>(
  *    declared type and the built-in mapping picks the wrong Kotlin type.
  *
  * ### Example
- * ```
- * val format = LocalDateTime.Format {
- *     year(); char('-'); monthNumber(); char('-'); day()
- *     char(' ')
- *     hour(); char(':'); minute(); char(':'); second()
- *     chars(" UTC")
- * }
- *
- * val sqliteCustom = Sqlite.withCustomConverters {
- *     // Every column declared with "MY_DATETIME" type is parsed from custom text into Instant.
- *     forType("MY_DATETIME") { raw: String? ->
- *         raw?.let { LocalDateTime.parse(it, format).toInstant(TimeZone.UTC) }
- *     }
- *     // Identity shortcut — pin the declared type LONGVARCHAR to `String?` regardless of
- *     // how SQLite's type affinity would classify it.
- *     forType<String?>("LONGVARCHAR")
- *     // The "ratio" column overrides its declared type — read as Double.
- *     forColumn("ratio") { raw: String -> raw.toDouble() }
- * }
- *
- * val df = DataFrame.readSqlTable(connection, "events", dbType = sqliteCustom)
- * ```
+ * @sample [org.jetbrains.kotlinx.dataframe.samples.io.jdbc.SqliteSamples.complexSqlite]
  */
 public class SqliteCustomConvertersBuilder
     @PublishedApi
@@ -357,6 +315,11 @@ public class Sqlite(
             Types.DECIMAL, Types.NUMERIC -> return jdbcToDfConverterFor<Any>(expectedKType)
         }
 
+        // 5) CLOB — stored as String.
+        if ("CLOB" in declaredUpper) {
+            return jdbcToDfConverterFor<String>(expectedKType)
+        }
+
         // 5) Fallback — delegate to the base [DbType] end-to-end pipeline.
         return fallbackConverter(tableColumnMetadata)
     }
@@ -598,25 +561,7 @@ public class Sqlite(
          * The converting lambda receives the raw value and returns the converted result;
          *
          * ### Example
-         * ```
-         * val format = LocalDateTime.Format {
-         *     year(); char('-'); monthNumber(); char('-'); day()
-         *     char(' ')
-         *     hour(); char(':'); minute(); char(':'); second()
-         *     chars(" UTC")
-         * }
-         *
-         * val sqliteCustom = Sqlite.withCustomConverters {
-         *     // Every column declared with "MY_DATETIME" type is parsed from custom text into Instant.
-         *     forType("MY_DATETIME") { raw: String? ->
-         *         raw?.let { LocalDateTime.parse(it, format).toInstant(TimeZone.UTC) }
-         *     }
-         *     // The "ratio" column overrides its declared type — read as Double.
-         *     forColumn("ratio") { raw: String -> raw.toDouble() }
-         * }
-         *
-         * val df = DataFrame.readSqlTable(connection, "events", dbType = sqliteCustom)
-         * ```
+         * @sample [org.jetbrains.kotlinx.dataframe.samples.io.jdbc.SqliteSamples.complexSqlite]
          */
         public fun withCustomConverters(block: SqliteCustomConvertersBuilder.() -> Unit): Sqlite {
             val builder = SqliteCustomConvertersBuilder().also { it.block() }