From cce57cce0aa1df69e1da9d21a9b504e55af56a3f Mon Sep 17 00:00:00 2001
From: "andrei.kislitsyn" <kisandy@yandex.ru>
Date: Fri, 24 Jul 2026 16:58:57 +0400
Subject: [PATCH 01/10] Add SQL type mapping documentation and SQLite metadata
 probe for testing

---
 .../kotlinx/dataframe/io/db/_sqliteProbe.kt   | 129 ++++
 .../kotlinx/dataframe/io/db/jdbcTypesTest.kt  | 630 +++++++++++++++---
 docs/StardustDocs/d.tree                      |   9 +
 .../StardustDocs/topics/readSqlTypeMapping.md |  54 ++
 .../topics/readSqlTypeMapping_DuckDB.md       | 123 ++++
 .../topics/readSqlTypeMapping_H2.md           | 113 ++++
 .../topics/readSqlTypeMapping_MariaDB.md      | 119 ++++
 .../topics/readSqlTypeMapping_MsSql.md        | 113 ++++
 .../topics/readSqlTypeMapping_MySQL.md        | 114 ++++
 .../topics/readSqlTypeMapping_PostgreSQL.md   | 171 +++++
 .../topics/readSqlTypeMapping_SQLite.md       | 176 +++++
 11 files changed, 1673 insertions(+), 78 deletions(-)
 create mode 100644 dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/_sqliteProbe.kt
 create mode 100644 docs/StardustDocs/topics/readSqlTypeMapping.md
 create mode 100644 docs/StardustDocs/topics/readSqlTypeMapping_DuckDB.md
 create mode 100644 docs/StardustDocs/topics/readSqlTypeMapping_H2.md
 create mode 100644 docs/StardustDocs/topics/readSqlTypeMapping_MariaDB.md
 create mode 100644 docs/StardustDocs/topics/readSqlTypeMapping_MsSql.md
 create mode 100644 docs/StardustDocs/topics/readSqlTypeMapping_MySQL.md
 create mode 100644 docs/StardustDocs/topics/readSqlTypeMapping_PostgreSQL.md
 create mode 100644 docs/StardustDocs/topics/readSqlTypeMapping_SQLite.md

diff --git a/dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/_sqliteProbe.kt b/dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/_sqliteProbe.kt
new file mode 100644
index 0000000000..e84e1b3ebe
--- /dev/null
+++ b/dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/_sqliteProbe.kt
@@ -0,0 +1,129 @@
+package org.jetbrains.kotlinx.dataframe.io.db
+
+import org.junit.Ignore
+import org.junit.Test
+import java.io.File
+import java.nio.file.Files
+import java.sql.DriverManager
+import java.sql.Types
+
+/**
+ * Probe used to figure out what the Xerial SQLite JDBC driver reports in the metadata
+ * for common declared column types (SQLite type affinity is applied at storage level, but
+ * the driver preserves the declared type name in `sqlTypeName`).
+ *
+ * Not part of the regular suite; enable ad-hoc if you need to refresh the mapping.
+ */
+@Ignore("Investigation probe — not a real test")
+class SqliteMetadataProbe {
+
+    @Test
+    fun `dump getObject class vs metadata jdbcType for problematic types`() {
+        val file = Files.createTempFile("dataframe_sqlite_probe2_", ".db").toFile()
+        file.deleteOnExit()
+        val url = "jdbc:sqlite:${file.absolutePath}"
+
+        // (declaredType, sql-literal, description)
+        val cases = listOf(
+            Triple("BOOLEAN", "1", "boolean-as-int"),
+            Triple("BOOLEAN", "0", "boolean-as-int-false"),
+            Triple("DATE", "'2020-01-15'", "date-as-iso-text"),
+            Triple("DATE", "1579046400", "date-as-unix-int"),
+            Triple("DATETIME", "'2020-01-15 10:30:00'", "datetime-as-iso-text"),
+            Triple("TIMESTAMP", "'2020-01-15T10:30:00Z'", "timestamp-as-iso-text"),
+            Triple("TIMESTAMP", "1579083000", "timestamp-as-unix-int"),
+            Triple("NUMERIC", "1.5", "numeric-as-real"),
+            Triple("NUMERIC", "42", "numeric-as-int"),
+            Triple("DECIMAL(10,5)", "1.5", "decimal-as-real"),
+            Triple("DATE", "2460146.5", "date-as-julian-real"),
+            Triple("TIMESTAMP", "2460146.5", "timestamp-as-julian-real"),
+        )
+
+        DriverManager.getConnection(url).use { conn ->
+            cases.forEachIndexed { i, (decl, literal, _) ->
+                conn.createStatement().execute("CREATE TABLE t$i (col $decl)")
+                conn.createStatement().execute("INSERT INTO t$i (col) VALUES ($literal)")
+            }
+            for ((i, case) in cases.withIndex()) {
+                val (decl, literal, desc) = case
+                conn.prepareStatement("SELECT col FROM t$i").executeQuery().use { rs ->
+                    val md = rs.metaData
+                    val jdbc = md.getColumnType(1)
+                    val jdbcName = jdbcName(jdbc)
+                    val cls = md.getColumnClassName(1)
+                    rs.next()
+                    val got = rs.getObject(1)
+                    val gotClass = got?.javaClass?.name
+                    println(
+                        "%-25s declared=%-14s literal=%-24s meta.jdbc=%-9s meta.class=%-22s getObject.class=%s value=%s".format(
+                            desc, decl, literal, jdbcName, cls, gotClass, got,
+                        ),
+                    )
+                }
+            }
+        }
+        file.delete()
+    }
+
+    @Test
+    fun `dump metadata for common declared types`() {
+        val file = Files.createTempFile("dataframe_sqlite_probe_", ".db").toFile()
+        file.deleteOnExit()
+        val url = "jdbc:sqlite:${file.absolutePath}"
+
+        val declaredTypes = listOf(
+            "INTEGER", "INT", "TINYINT", "SMALLINT", "MEDIUMINT", "BIGINT", "UNSIGNED BIG INT",
+            "INT2", "INT8",
+            "REAL", "DOUBLE", "DOUBLE PRECISION", "FLOAT",
+            "NUMERIC", "DECIMAL(10,5)",
+            "BOOLEAN",
+            "DATE", "DATETIME", "TIMESTAMP",
+            "TEXT", "VARCHAR(255)", "CHAR(10)", "CLOB", "NVARCHAR(10)", "NCHAR(10)",
+            "BLOB",
+            "",           // no declared type
+            "CUSTOM_TYPE", // unknown → NUMERIC affinity
+        )
+
+        DriverManager.getConnection(url).use { conn ->
+            declaredTypes.forEachIndexed { i, decl ->
+                val col = "col$i ${if (decl.isEmpty()) "" else decl}".trim()
+                conn.createStatement().execute("CREATE TABLE t$i ($col)")
+                // Insert one representative value so the driver can infer the actual storage class.
+                conn.createStatement().execute("INSERT INTO t$i (col$i) VALUES (${sampleValueFor(decl)})")
+            }
+            for ((i, decl) in declaredTypes.withIndex()) {
+                conn.prepareStatement("SELECT col$i FROM t$i").executeQuery().use { rs ->
+                    val md = rs.metaData
+                    val jdbc = md.getColumnType(1)
+                    val jdbcName = jdbcName(jdbc)
+                    val typeName = md.getColumnTypeName(1)
+                    val cls = md.getColumnClassName(1)
+                    println(
+                        "declared=%-24s -> sqlTypeName=%-16s jdbcType=%-8s (%s) classNm=%s".format(
+                            "\"$decl\"", typeName, jdbc.toString(), jdbcName, cls,
+                        ),
+                    )
+                }
+            }
+        }
+        file.delete()
+    }
+
+    private fun jdbcName(t: Int): String =
+        Types::class.java.fields.firstOrNull { it.getInt(null) == t }?.name ?: "?"
+
+    private fun sampleValueFor(decl: String): String {
+        val u = decl.uppercase()
+        return when {
+            u.contains("BLOB") -> "x'00'"
+            u.contains("BOOLEAN") -> "1"
+            u.contains("DATE") || u.contains("TIMESTAMP") || u.contains("TIME") -> "'2020-01-01'"
+            u.contains("CHAR") || u.contains("TEXT") || u.contains("CLOB") -> "'x'"
+            u.contains("REAL") || u.contains("DOUB") || u.contains("FLOA") ||
+                u.contains("NUMERIC") || u.contains("DECIMAL") -> "1.5"
+            u.contains("INT") -> "1"
+            u.isEmpty() -> "1"
+            else -> "'x'"
+        }
+    }
+}
diff --git a/dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/jdbcTypesTest.kt b/dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/jdbcTypesTest.kt
index 56758ec27b..2b86bd102c 100644
--- a/dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/jdbcTypesTest.kt
+++ b/dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/jdbcTypesTest.kt
@@ -3,113 +3,587 @@
 package org.jetbrains.kotlinx.dataframe.io.db
 
 import io.kotest.matchers.shouldBe
-import org.jetbrains.kotlinx.dataframe.io.db.JdbcTypesTest.MySqlDBTypes.BIGINT_UNSIGNED
 import org.junit.Test
 import org.junit.experimental.runners.Enclosed
 import org.junit.runner.RunWith
+import org.postgresql.geometric.PGbox
+import org.postgresql.geometric.PGcircle
+import org.postgresql.geometric.PGline
+import org.postgresql.geometric.PGlseg
+import org.postgresql.geometric.PGpath
+import org.postgresql.geometric.PGpoint
+import org.postgresql.geometric.PGpolygon
+import org.postgresql.util.PGInterval
+import org.postgresql.util.PGmoney
+import java.math.BigDecimal
 import java.math.BigInteger
+import java.sql.Blob
+import java.sql.Clob
+import java.sql.NClob
+import java.sql.Ref
+import java.sql.RowId
+import java.sql.SQLXML
+import java.sql.Time
+import java.sql.Types
+import java.time.OffsetDateTime
+import java.time.OffsetTime
+import java.util.Date
 import kotlin.reflect.KType
+import kotlin.reflect.full.withNullability
 import kotlin.reflect.typeOf
+import kotlin.time.Instant
+import kotlin.uuid.Uuid
+import kotlinx.datetime.LocalDate as KotlinLocalDate
+import kotlinx.datetime.LocalDateTime as KotlinLocalDateTime
+import kotlinx.datetime.LocalTime as KotlinLocalTime
 
-// TODO: complete and enhance (#1736)
+/**
+ * Non-integration tests for [DbType.getExpectedJdbcType] and related type-mapping logic.
+ *
+ * Each DB owns a [TypeMapping] list that acts as the source of truth for its SQL → Kotlin type
+ * mapping. The list is exercised for both nullable and non-nullable columns.
+ *
+ * See https://github.com/Kotlin/dataframe/issues/1736.
+ */
 @RunWith(Enclosed::class)
 class JdbcTypesTest {
 
-    abstract class ColumnType(
-        val sqlTypeName: String,
-        val jdbcType: Int,
-        val javaClassName: String,
-        val isNullable: Boolean,
-        val expectedKotlinType: KType,
-    ) {
-        fun mockkColMetaData() =
-            TableColumnMetadata(
-                "name",
-                sqlTypeName,
-                jdbcType,
-                10,
-                javaClassName,
-                isNullable,
-            )
+    class DefaultDbTypeTypes {
+
+        // A concrete DbType whose behavior is exactly the default one from the base class.
+        private object DefaultDbType : DbType("default") {
+            override val driverClassName: String get() = "does.not.matter"
+
+            override fun isSystemTable(tableMetadata: TableMetadata): Boolean = false
+
+            override fun buildTableMetadata(tables: java.sql.ResultSet): TableMetadata =
+                TableMetadata("t", null, null)
+        }
+
+        @Test
+        fun `common SQL types map to the expected Kotlin type`() {
+            assertMappings(DefaultDbType, commonJdbcTypeMappings)
+        }
+
+        @Test
+        fun `TIMESTAMP with LocalDateTime driver class maps to java_time_LocalDateTime`() {
+            assertMappings(DefaultDbType, listOf(timestampAsLocalDateTime))
+        }
+
+        @Test
+        fun `BINARY with UUID driver class maps to UUID`() {
+            assertMappings(DefaultDbType, listOf(binaryAsUuid))
+        }
+
+        @Test
+        fun `Types_OTHER with byte array javaClassName maps to ByteArray`() {
+            DefaultDbType.getExpectedJdbcType(
+                createColumnMetadata(
+                    sqlTypeName = "OTHER",
+                    jdbcType = Types.OTHER,
+                    javaClassName = "[B",
+                    isNullable = false,
+                ),
+            ) shouldBe typeOf<ByteArray>()
+        }
+
+        @Test
+        fun `Types_OTHER with generic Object maps to Any`() {
+            DefaultDbType.getExpectedJdbcType(
+                createColumnMetadata(
+                    sqlTypeName = "OTHER",
+                    jdbcType = Types.OTHER,
+                    javaClassName = "java.lang.Object",
+                    isNullable = true,
+                ),
+            ) shouldBe typeOf<Any?>()
+        }
+
+        @Test
+        fun `unknown jdbcType falls back to String`() {
+            DefaultDbType.getExpectedJdbcType(
+                createColumnMetadata(
+                    sqlTypeName = "MADE_UP",
+                    jdbcType = UNKNOWN_JDBC_TYPE,
+                    javaClassName = "java.lang.Object",
+                    isNullable = false,
+                ),
+            ) shouldBe typeOf<String>()
+        }
     }
 
-    class MariaDBTypes {
+    class MariaDbTypes {
 
-        object BIGINT_UNSIGNED : ColumnType(
-            "BIGINT UNSIGNED",
-            20,
-            "java.math.BigInteger",
-            false,
-            typeOf<BigInteger>(),
-        )
+        @Test
+        fun `common SQL types map to the expected Kotlin type`() {
+            assertMappings(MariaDb, commonJdbcTypeMappings)
+        }
 
-        val types: List<ColumnType> = listOf(
-            BIGINT_UNSIGNED,
-        )
+        @Test
+        fun `MariaDB-specific overrides`() {
+            assertMappings(MariaDb, mariaDbSpecificMappings)
+        }
 
         @Test
-        fun `all MariaDB SQL types should match expected type`() {
-            types.forEach { type ->
-                MariaDb.getExpectedJdbcType(type.mockkColMetaData()) shouldBe type.expectedKotlinType
-            }
+        fun `unknown jdbcType falls back to String`() {
+            assertUnknownMapsToString(MariaDb)
         }
     }
 
-    class MySqlDBTypes {
+    class MySqlTypes {
 
-        object BIGINT_UNSIGNED : ColumnType(
-            "BIGINT UNSIGNED",
-            20,
-            "java.math.BigInteger",
-            false,
-            typeOf<BigInteger>(),
-        )
+        @Test
+        fun `common SQL types map to the expected Kotlin type`() {
+            assertMappings(MySql, commonJdbcTypeMappings)
+        }
 
-        val types: List<ColumnType> = listOf(
-            BIGINT_UNSIGNED,
-        )
+        @Test
+        fun `MySQL-specific overrides`() {
+            assertMappings(MySql, mySqlSpecificMappings)
+        }
 
         @Test
-        fun `all MariaDB SQL types should match expected type`() {
-            types.forEach { type ->
-                MySql.getExpectedJdbcType(type.mockkColMetaData()) shouldBe type.expectedKotlinType
-            }
+        fun `unknown jdbcType falls back to String`() {
+            assertUnknownMapsToString(MySql)
         }
     }
 
+    /**
+     * SQLite is dynamically typed: it has only 5 storage classes (NULL, INTEGER, REAL, TEXT, BLOB)
+     * and picks one per row based on the value, guided by "type affinity" derived from the
+     * declared column type. The Xerial JDBC driver reports metadata based on the actual stored
+     * value, so `getExpectedJdbcType` sees driver-specific `jdbcType` and `javaClassName` combos
+     * that differ from other databases. The tests below reflect that.
+     */
     class SqliteTypes {
 
-        // Taken from #964
-
-        object LONGVARCHAR_1 : ColumnType(
-            "LONGVARCHAR",
-            -2,
-            "java.lang.Object",
-            false,
-            typeOf<String>(),
-        )
-
-        object LONGVARCHAR_2 : ColumnType(
-            "LONGVARCHAR",
-            12,
-            "java.lang.String",
-            true,
-            typeOf<String?>(),
-        )
-
-        val customTypes: List<ColumnType> = listOf(
-            LONGVARCHAR_1,
-            LONGVARCHAR_2,
-        )
-
-        @Test
-        fun `SQLite custom types`() {
-            val sqliteCustom = Sqlite(
-                mapOf("LONGVARCHAR" to typeOf<String>()),
+        @Test
+        fun `INTEGER affinity — declared int-like types map to Int or Long`() {
+            assertMappings(Sqlite.default, sqliteIntegerAffinityMappings)
+        }
+
+        @Test
+        fun `REAL affinity — declared real-like types map to Double`() {
+            assertMappings(Sqlite.default, sqliteRealAffinityMappings)
+        }
+
+        @Test
+        fun `TEXT affinity — declared text-like types map to String`() {
+            assertMappings(Sqlite.default, sqliteTextAffinityMappings)
+        }
+
+        @Test
+        fun `BLOB affinity — declared BLOB maps to ByteArray`() {
+            assertMappings(Sqlite.default, sqliteBlobAffinityMappings)
+        }
+
+        @Test
+        fun `NUMERIC affinity — declared numeric-like types map by declared type`() {
+            assertMappings(Sqlite.default, sqliteNumericAffinityMappings)
+        }
+
+        @Test
+        fun `BOOLEAN declared type resolves to Boolean`() {
+            // Xerial reports Types.BOOLEAN metadata even though values are stored as INTEGER;
+            // the schema type is Boolean, and `getValueFromResultSet` converts each row via
+            // `rs.getBoolean` (see Sqlite.getValueFromResultSet).
+            Sqlite.default.getExpectedJdbcType(
+                createColumnMetadata(
+                    sqlTypeName = "BOOLEAN",
+                    jdbcType = Types.BOOLEAN,
+                    javaClassName = "java.lang.Integer",
+                    isNullable = false,
+                ),
+            ) shouldBe typeOf<Boolean>()
+
+            Sqlite.default.getExpectedJdbcType(
+                createColumnMetadata(
+                    sqlTypeName = "BOOLEAN",
+                    jdbcType = Types.BOOLEAN,
+                    javaClassName = "java.lang.Integer",
+                    isNullable = true,
+                ),
+            ) shouldBe typeOf<Boolean?>()
+        }
+
+        @Test
+        fun `unrecognised declared type is treated by NUMERIC affinity`() {
+            // For an unknown declared type Xerial applies NUMERIC affinity and reports the
+            // jdbcType of the actual stored value; for a text sample that is VARCHAR.
+            Sqlite.default.getExpectedJdbcType(
+                createColumnMetadata(
+                    sqlTypeName = "CUSTOM_TYPE",
+                    jdbcType = Types.VARCHAR,
+                    javaClassName = "java.lang.String",
+                    isNullable = false,
+                ),
+            ) shouldBe typeOf<String>()
+        }
+
+        @Test
+        fun `customTypesMap overrides the default mapping by SQL type name`() {
+            val custom = Sqlite(
+                customTypesMap = mapOf(
+                    "INTEGER" to typeOf<Long>(),
+                    "MY_TYPE" to typeOf<String>(),
+                ),
+            )
+            // INTEGER is normally Int, but is overridden to Long
+            custom.getExpectedJdbcType(
+                createColumnMetadata(
+                    sqlTypeName = "INTEGER",
+                    jdbcType = Types.INTEGER,
+                    javaClassName = "java.lang.Integer",
+                    isNullable = true,
+                ),
+            ) shouldBe typeOf<Long?>()
+            // Custom type name is respected as-is
+            custom.getExpectedJdbcType(
+                createColumnMetadata(
+                    sqlTypeName = "MY_TYPE",
+                    jdbcType = Types.OTHER,
+                    javaClassName = "java.lang.Object",
+                    isNullable = false,
+                ),
+            ) shouldBe typeOf<String>()
+        }
+
+        @Test
+        fun `unknown jdbcType falls back to String`() {
+            assertUnknownMapsToString(Sqlite.default)
+        }
+    }
+
+    class PostgreSqlTypes {
+
+        @Test
+        fun `common SQL types map to the expected Kotlin type`() {
+            assertMappings(PostgreSql, commonJdbcTypeMappings)
+        }
+
+        @Test
+        fun `PGobject types map to their PGobject Kotlin types`() {
+            assertMappings(PostgreSql, postgreSqlSpecificMappings)
+        }
+
+        @Test
+        fun `PGobject lookup is case-insensitive`() {
+            PostgreSql.getExpectedJdbcType(
+                createColumnMetadata(
+                    sqlTypeName = "POINT",
+                    jdbcType = Types.OTHER,
+                    javaClassName = "org.postgresql.geometric.PGpoint",
+                    isNullable = true,
+                ),
+            ) shouldBe typeOf<PGpoint?>()
+        }
+
+        @Test
+        fun `unknown jdbcType falls back to String`() {
+            assertUnknownMapsToString(PostgreSql)
+        }
+    }
+
+    class MsSqlTypes {
+
+        @Test
+        fun `common SQL types map to the expected Kotlin type`() {
+            assertMappings(MsSql, commonJdbcTypeMappings)
+        }
+
+        @Test
+        fun `unknown jdbcType falls back to String`() {
+            assertUnknownMapsToString(MsSql)
+        }
+    }
+
+    class H2Types {
+
+        @Test
+        fun `Regular mode uses default type mappings`() {
+            assertMappings(H2(H2.Mode.Regular), commonJdbcTypeMappings)
+        }
+
+        @Test
+        fun `MySql mode delegates to MySQL-specific overrides`() {
+            assertMappings(H2(H2.Mode.MySql), mySqlSpecificMappings)
+        }
+
+        @Test
+        fun `MariaDb mode delegates to MariaDB-specific overrides`() {
+            assertMappings(H2(H2.Mode.MariaDb), mariaDbSpecificMappings)
+        }
+
+        @Test
+        fun `unknown jdbcType falls back to String`() {
+            assertUnknownMapsToString(H2(H2.Mode.Regular))
+        }
+    }
+}
+
+// -------------------- Type mapping model & helpers --------------------
+
+/**
+ * A single row in the JDBC → Kotlin type mapping table.
+ *
+ * @property sqlTypeName the human-readable SQL type name (e.g. "BIGINT")
+ * @property jdbcType a constant from [java.sql.Types]
+ * @property javaClassName the JDBC-reported class name for this column (as returned by
+ *   [java.sql.ResultSetMetaData.getColumnClassName])
+ * @property expectedType the expected non-nullable Kotlin type
+ */
+internal data class TypeMapping(
+    val sqlTypeName: String,
+    val jdbcType: Int,
+    val javaClassName: String,
+    val expectedType: KType,
+)
+
+internal const val UNKNOWN_JDBC_TYPE: Int = -9999
+
+/**
+ * Test helper that constructs a [TableColumnMetadata] with sensible defaults.
+ * Not a mock — a lightweight factory to keep test call sites readable.
+ */
+internal fun createColumnMetadata(
+    name: String = "col",
+    sqlTypeName: String,
+    jdbcType: Int,
+    size: Int = 10,
+    javaClassName: String,
+    isNullable: Boolean,
+): TableColumnMetadata =
+    TableColumnMetadata(
+        name = name,
+        sqlTypeName = sqlTypeName,
+        jdbcType = jdbcType,
+        size = size,
+        javaClassName = javaClassName,
+        isNullable = isNullable,
+    )
+
+/**
+ * Verifies each mapping resolves correctly for both nullable and non-nullable columns.
+ * Runs the full type-resolution pipeline (`getExpectedJdbcType` → `getPreprocessedValueType`)
+ * and compares against the **final DataFrame column type**, which is what the reference
+ * documentation describes.
+ */
+internal fun assertMappings(dbType: DbType, mappings: List<TypeMapping>) {
+    mappings.forEach { m ->
+        listOf(false, true).forEach { isNullable ->
+            val meta = createColumnMetadata(
+                sqlTypeName = m.sqlTypeName,
+                jdbcType = m.jdbcType,
+                javaClassName = m.javaClassName,
+                isNullable = isNullable,
             )
-            customTypes.forEach { type ->
-                sqliteCustom.getExpectedJdbcType(type.mockkColMetaData()) shouldBe type.expectedKotlinType
-            }
+            val jdbcType = dbType.getExpectedJdbcType(meta)
+            val finalType = dbType.getPreprocessedValueType(meta, jdbcType)
+            finalType shouldBe m.expectedType.withNullability(isNullable)
         }
     }
 }
+
+internal fun assertUnknownMapsToString(dbType: DbType) {
+    dbType.getExpectedJdbcType(
+        createColumnMetadata(
+            sqlTypeName = "MADE_UP",
+            jdbcType = UNKNOWN_JDBC_TYPE,
+            javaClassName = "java.lang.Object",
+            isNullable = false,
+        ),
+    ) shouldBe typeOf<String>()
+
+    dbType.getExpectedJdbcType(
+        createColumnMetadata(
+            sqlTypeName = "MADE_UP",
+            jdbcType = UNKNOWN_JDBC_TYPE,
+            javaClassName = "java.lang.Object",
+            isNullable = true,
+        ),
+    ) shouldBe typeOf<String?>()
+}
+
+// -------------------- Type mapping tables --------------------
+
+/**
+ * The default SQL → Kotlin type mapping applied by [DbType].
+ * Every DB that does not override the given entry falls through to this table.
+ */
+internal val commonJdbcTypeMappings: List<TypeMapping> = listOf(
+    TypeMapping("BIT", Types.BIT, "java.lang.Boolean", typeOf<Boolean>()),
+    TypeMapping("TINYINT", Types.TINYINT, "java.lang.Integer", typeOf<Int>()),
+    TypeMapping("SMALLINT", Types.SMALLINT, "java.lang.Integer", typeOf<Int>()),
+    TypeMapping("INTEGER", Types.INTEGER, "java.lang.Integer", typeOf<Int>()),
+    TypeMapping("BIGINT", Types.BIGINT, "java.lang.Long", typeOf<Long>()),
+    TypeMapping("FLOAT", Types.FLOAT, "java.lang.Float", typeOf<Float>()),
+    TypeMapping("REAL", Types.REAL, "java.lang.Float", typeOf<Float>()),
+    TypeMapping("DOUBLE", Types.DOUBLE, "java.lang.Double", typeOf<Double>()),
+    TypeMapping("NUMERIC", Types.NUMERIC, "java.math.BigDecimal", typeOf<BigDecimal>()),
+    TypeMapping("DECIMAL", Types.DECIMAL, "java.math.BigDecimal", typeOf<BigDecimal>()),
+    TypeMapping("CHAR", Types.CHAR, "java.lang.String", typeOf<String>()),
+    TypeMapping("VARCHAR", Types.VARCHAR, "java.lang.String", typeOf<String>()),
+    TypeMapping("LONGVARCHAR", Types.LONGVARCHAR, "java.lang.String", typeOf<String>()),
+    TypeMapping("NCHAR", Types.NCHAR, "java.lang.String", typeOf<String>()),
+    TypeMapping("NVARCHAR", Types.NVARCHAR, "java.lang.String", typeOf<String>()),
+    TypeMapping("LONGNVARCHAR", Types.LONGNVARCHAR, "java.lang.String", typeOf<String>()),
+    TypeMapping("DATE", Types.DATE, "java.sql.Date", typeOf<Date>()),
+    TypeMapping("TIME", Types.TIME, "java.sql.Time", typeOf<Time>()),
+    TypeMapping("TIMESTAMP", Types.TIMESTAMP, "java.sql.Timestamp", typeOf<Instant>()),
+    TypeMapping("TIME_WITH_TIMEZONE", Types.TIME_WITH_TIMEZONE, "java.time.OffsetTime", typeOf<OffsetTime>()),
+    TypeMapping(
+        "TIMESTAMP_WITH_TIMEZONE",
+        Types.TIMESTAMP_WITH_TIMEZONE,
+        "java.time.OffsetDateTime",
+        typeOf<OffsetDateTime>(),
+    ),
+    TypeMapping("BINARY", Types.BINARY, "[B", typeOf<ByteArray>()),
+    TypeMapping("VARBINARY", Types.VARBINARY, "[B", typeOf<ByteArray>()),
+    TypeMapping("LONGVARBINARY", Types.LONGVARBINARY, "[B", typeOf<ByteArray>()),
+    TypeMapping("BOOLEAN", Types.BOOLEAN, "java.lang.Boolean", typeOf<Boolean>()),
+    TypeMapping("BLOB", Types.BLOB, "java.sql.Blob", typeOf<Blob>()),
+    TypeMapping("CLOB", Types.CLOB, "java.sql.Clob", typeOf<Clob>()),
+    TypeMapping("NCLOB", Types.NCLOB, "java.sql.NClob", typeOf<NClob>()),
+    TypeMapping("SQLXML", Types.SQLXML, "java.sql.SQLXML", typeOf<SQLXML>()),
+    TypeMapping("ROWID", Types.ROWID, "java.sql.RowId", typeOf<RowId>()),
+    TypeMapping("REF", Types.REF, "java.sql.Ref", typeOf<Ref>()),
+    TypeMapping("REF_CURSOR", Types.REF_CURSOR, "java.sql.Ref", typeOf<Ref>()),
+)
+
+/** TIMESTAMP columns whose JDBC-reported class is `java.time.LocalDateTime` are preprocessed to `kotlinx.datetime.LocalDateTime`. */
+internal val timestampAsLocalDateTime: TypeMapping = TypeMapping(
+    sqlTypeName = "TIMESTAMP",
+    jdbcType = Types.TIMESTAMP,
+    javaClassName = "java.time.LocalDateTime",
+    expectedType = typeOf<KotlinLocalDateTime>(),
+)
+
+/** BINARY columns storing UUIDs (`java.util.UUID`) are preprocessed to `kotlin.uuid.Uuid`. */
+internal val binaryAsUuid: TypeMapping = TypeMapping(
+    sqlTypeName = "BINARY",
+    jdbcType = Types.BINARY,
+    javaClassName = "java.util.UUID",
+    expectedType = typeOf<Uuid>(),
+)
+
+/**
+ * MariaDB overrides on top of [commonJdbcTypeMappings]. Also includes entries that reflect
+ * the MariaDB JDBC driver's specific `javaClassName` reporting (e.g. `BLOB` as `[B`,
+ * `SMALLINT` as `java.lang.Short`).
+ */
+internal val mariaDbSpecificMappings: List<TypeMapping> = listOf(
+    TypeMapping("BIGINT UNSIGNED", Types.BIGINT, "java.math.BigInteger", typeOf<BigInteger>()),
+    TypeMapping("INT UNSIGNED", Types.INTEGER, "java.lang.Long", typeOf<Long>()),
+    TypeMapping("INTEGER UNSIGNED", Types.INTEGER, "java.lang.Long", typeOf<Long>()),
+    TypeMapping("SMALLINT", Types.SMALLINT, "java.lang.Short", typeOf<Short>()),
+    // MariaDB reports BLOB columns as `[B` (byte array), not `java.sql.Blob`.
+    TypeMapping("BLOB", Types.BLOB, "[B", typeOf<ByteArray>()),
+    // YEAR columns are reported as Types.DATE by the driver.
+    TypeMapping("YEAR", Types.DATE, "java.sql.Date", typeOf<Date>()),
+)
+
+/** MySQL overrides on top of [commonJdbcTypeMappings]. */
+internal val mySqlSpecificMappings: List<TypeMapping> = listOf(
+    TypeMapping("BIGINT UNSIGNED", Types.BIGINT, "java.math.BigInteger", typeOf<BigInteger>()),
+    TypeMapping("INT UNSIGNED", Types.INTEGER, "java.lang.Long", typeOf<Long>()),
+)
+
+/** PostgreSQL PGobject overrides — matched by `sqlTypeName` (case-insensitively). */
+internal val postgreSqlSpecificMappings: List<TypeMapping> = listOf(
+    TypeMapping("box", Types.OTHER, "org.postgresql.geometric.PGbox", typeOf<PGbox>()),
+    TypeMapping("circle", Types.OTHER, "org.postgresql.geometric.PGcircle", typeOf<PGcircle>()),
+    TypeMapping("line", Types.OTHER, "org.postgresql.geometric.PGline", typeOf<PGline>()),
+    TypeMapping("lseg", Types.OTHER, "org.postgresql.geometric.PGlseg", typeOf<PGlseg>()),
+    TypeMapping("path", Types.OTHER, "org.postgresql.geometric.PGpath", typeOf<PGpath>()),
+    TypeMapping("point", Types.OTHER, "org.postgresql.geometric.PGpoint", typeOf<PGpoint>()),
+    TypeMapping("polygon", Types.OTHER, "org.postgresql.geometric.PGpolygon", typeOf<PGpolygon>()),
+    TypeMapping("money", Types.OTHER, "org.postgresql.util.PGmoney", typeOf<PGmoney>()),
+    TypeMapping("interval", Types.OTHER, "org.postgresql.util.PGInterval", typeOf<PGInterval>()),
+)
+
+// -------------------- SQLite-specific mappings --------------------
+//
+// SQLite has only 5 storage classes (NULL, INTEGER, REAL, TEXT, BLOB) and applies "type affinity"
+// per column based on the declared type:
+//   - INTEGER affinity: declared type contains "INT"
+//   - TEXT    affinity: declared type contains "CHAR", "CLOB", or "TEXT"
+//   - BLOB    affinity: declared type contains "BLOB" or is missing
+//   - REAL    affinity: declared type contains "REAL", "FLOA", or "DOUB"
+//   - NUMERIC affinity: everything else (e.g. BOOLEAN, DATE, DATETIME, DECIMAL, NUMERIC, ...)
+//
+// The Xerial JDBC driver reports the declared type in `sqlTypeName` and infers `jdbcType` from
+// affinity, but reports `javaClassName` from the *actual stored value*. The mappings below
+// reflect what `getExpectedJdbcType` returns for a column of the given declared type once
+// a representative value has been inserted (i.e. the common case for reading data).
+
+/** INTEGER affinity — declared int-like types storing an int value. */
+internal val sqliteIntegerAffinityMappings: List<TypeMapping> = listOf(
+    TypeMapping("INTEGER", Types.INTEGER, "java.lang.Integer", typeOf<Int>()),
+    TypeMapping("INT", Types.INTEGER, "java.lang.Integer", typeOf<Int>()),
+    TypeMapping("MEDIUMINT", Types.INTEGER, "java.lang.Integer", typeOf<Int>()),
+    TypeMapping("TINYINT", Types.TINYINT, "java.lang.Integer", typeOf<Int>()),
+    TypeMapping("SMALLINT", Types.SMALLINT, "java.lang.Integer", typeOf<Int>()),
+    TypeMapping("INT2", Types.SMALLINT, "java.lang.Integer", typeOf<Int>()),
+    TypeMapping("BIGINT", Types.BIGINT, "java.lang.Integer", typeOf<Long>()),
+    TypeMapping("UNSIGNED BIG INT", Types.BIGINT, "java.lang.Integer", typeOf<Long>()),
+    TypeMapping("INT8", Types.BIGINT, "java.lang.Integer", typeOf<Long>()),
+)
+
+/** REAL affinity — declared real-like types storing a floating-point value. */
+internal val sqliteRealAffinityMappings: List<TypeMapping> = listOf(
+    TypeMapping("REAL", Types.REAL, "java.lang.Double", typeOf<Double>()),
+    TypeMapping("FLOAT", Types.FLOAT, "java.lang.Double", typeOf<Double>()),
+    TypeMapping("DOUBLE", Types.DOUBLE, "java.lang.Double", typeOf<Double>()),
+    TypeMapping("DOUBLE PRECISION", Types.DOUBLE, "java.lang.Double", typeOf<Double>()),
+)
+
+/** TEXT affinity — declared text-like types storing a string. */
+internal val sqliteTextAffinityMappings: List<TypeMapping> = listOf(
+    TypeMapping("TEXT", Types.VARCHAR, "java.lang.String", typeOf<String>()),
+    TypeMapping("VARCHAR", Types.VARCHAR, "java.lang.String", typeOf<String>()),
+    TypeMapping("NVARCHAR", Types.VARCHAR, "java.lang.String", typeOf<String>()),
+    TypeMapping("CHAR", Types.CHAR, "java.lang.String", typeOf<String>()),
+    TypeMapping("NCHAR", Types.CHAR, "java.lang.String", typeOf<String>()),
+    // CLOB falls through to `defaultJdbcTypeToKTypeMapping[Types.CLOB]` (= java.sql.Clob),
+    // regardless of the reported javaClassName.
+    TypeMapping("CLOB", Types.CLOB, "java.lang.String", typeOf<java.sql.Clob>()),
+)
+
+/** BLOB affinity — declared BLOB storing binary bytes. */
+internal val sqliteBlobAffinityMappings: List<TypeMapping> = listOf(
+    TypeMapping("BLOB", Types.BLOB, "java.lang.Object", typeOf<ByteArray>()),
+)
+
+/**
+ * NUMERIC affinity — DECIMAL and NUMERIC follow the actual storage class (numeric ambiguity;
+ * there is no single "canonical" numeric type). DATE / DATETIME / TIME / TIMESTAMP get an
+ * idiomatic Kotlin date-time type in the DataFrame schema (`kotlinx.datetime.LocalDate` /
+ * `kotlinx.datetime.LocalDateTime` / `kotlinx.datetime.LocalTime` / `kotlin.time.Instant`) and
+ * are converted from their storage class during preprocessing — see the SQLite type mapping doc.
+ *
+ * Detection is by `sqlTypeName` (not `jdbcType`), because Xerial changes the reported jdbcType
+ * based on the actual storage: e.g. a `DATE` column with a REAL value is reported as `FLOAT`.
+ */
+internal val sqliteNumericAffinityMappings: List<TypeMapping> = listOf(
+    TypeMapping("NUMERIC", Types.NUMERIC, "java.lang.Double", typeOf<Double>()),
+    TypeMapping("NUMERIC", Types.NUMERIC, "java.lang.Integer", typeOf<Int>()),
+    TypeMapping("DECIMAL", Types.DECIMAL, "java.lang.Double", typeOf<Double>()),
+
+    // DATE with all three storage classes:
+    TypeMapping("DATE", Types.DATE, "java.lang.String", typeOf<KotlinLocalDate>()),    // TEXT (ISO)
+    TypeMapping("DATE", Types.DATE, "java.lang.Integer", typeOf<KotlinLocalDate>()),   // INTEGER (Unix)
+    TypeMapping("DATE", Types.FLOAT, "java.lang.Double", typeOf<KotlinLocalDate>()),   // REAL (Julian day)
+
+    // DATETIME variants:
+    TypeMapping("DATETIME", Types.DATE, "java.lang.String", typeOf<KotlinLocalDateTime>()),
+    TypeMapping("DATETIME", Types.DATE, "java.lang.Integer", typeOf<KotlinLocalDateTime>()),
+
+    // TIME variants:
+    TypeMapping("TIME", Types.TIME, "java.lang.String", typeOf<KotlinLocalTime>()),
+    TypeMapping("TIME", Types.INTEGER, "java.lang.Integer", typeOf<KotlinLocalTime>()),
+
+    // TIMESTAMP with all three storage classes:
+    TypeMapping("TIMESTAMP", Types.TIMESTAMP, "java.lang.String", typeOf<Instant>()),   // TEXT (ISO)
+    TypeMapping("TIMESTAMP", Types.TIMESTAMP, "java.lang.Integer", typeOf<Instant>()),  // INTEGER (Unix)
+    TypeMapping("TIMESTAMP", Types.FLOAT, "java.lang.Double", typeOf<Instant>()),       // REAL (Julian day)
+)
diff --git a/docs/StardustDocs/d.tree b/docs/StardustDocs/d.tree
index 58da03d425..2003e3ffa9 100644
--- a/docs/StardustDocs/d.tree
+++ b/docs/StardustDocs/d.tree
@@ -68,6 +68,15 @@
             <toc-element topic="read.md"/>
             <toc-element topic="readSqlDatabases.md"/>
             <toc-element topic="readSqlFromCustomDatabase.md"/>
+            <toc-element topic="readSqlTypeMapping.md">
+                <toc-element topic="readSqlTypeMapping_MariaDB.md"/>
+                <toc-element topic="readSqlTypeMapping_MySQL.md"/>
+                <toc-element topic="readSqlTypeMapping_PostgreSQL.md"/>
+                <toc-element topic="readSqlTypeMapping_MsSql.md"/>
+                <toc-element topic="readSqlTypeMapping_H2.md"/>
+                <toc-element topic="readSqlTypeMapping_SQLite.md"/>
+                <toc-element topic="readSqlTypeMapping_DuckDB.md"/>
+            </toc-element>
             <toc-element topic="write.md"/>
         </toc-element>
         <toc-element topic="info.md">
diff --git a/docs/StardustDocs/topics/readSqlTypeMapping.md b/docs/StardustDocs/topics/readSqlTypeMapping.md
new file mode 100644
index 0000000000..3f48df57c5
--- /dev/null
+++ b/docs/StardustDocs/topics/readSqlTypeMapping.md
@@ -0,0 +1,54 @@
+[//]: # (title: SQL to DataFrame type mapping)
+
+<web-summary>
+Overview of how SQL column types are mapped to Kotlin types when reading a DataFrame
+from each supported JDBC database.
+</web-summary>
+
+<card-summary>
+Overview of the SQL to Kotlin type mapping used by `dataframe-jdbc`.
+</card-summary>
+
+<link-summary>
+Overview and index of the per-database SQL to Kotlin type mapping used by `dataframe-jdbc`.
+</link-summary>
+
+When reading from a JDBC database, DataFrame determines the Kotlin type of each column in
+two steps:
+
+1. **Type resolution** — the SQL/JDBC type reported by the driver is mapped to a JDBC-side
+   Kotlin type (`DbType.getExpectedJdbcType`).
+2. **Value preprocessing** — a few JDBC types are converted to more idiomatic Kotlin types
+   before being placed into the DataFrame (`DbType.preprocessValue`). For example,
+   `java.sql.Timestamp` is turned into `kotlin.time.Instant`.
+
+Nullable columns produce nullable Kotlin types (`Int?` instead of `Int`).
+
+## Type alias handling
+
+Most SQL dialects define **type aliases** (e.g. `INT8` for `BIGINT` in MariaDB/MySQL/PostgreSQL,
+`BOOL` for `BOOLEAN`, `INTEGER` for `INT`, ...). Every database supported by DataFrame — **except
+SQLite** — canonicalises the declared type name at `CREATE TABLE` time, so the JDBC driver reports
+only the canonical form in `ResultSetMetaData.getColumnTypeName`. That means DataFrame never sees
+the alias, only its canonical mapping. Each per-database page lists the aliases in the same row as
+the canonical type.
+
+**SQLite is the exception** — it preserves the declared type verbatim in metadata and applies
+"type affinity" instead. See the [SQLite page](readSqlTypeMapping_SQLite.md) for how this works.
+
+## Per-database type mapping pages
+
+| Database                                                     | How it uses `DbType`                                                       |
+|--------------------------------------------------------------|-----------------------------------------------------------------------------|
+| [MariaDB](readSqlTypeMapping_MariaDB.md)                     | Default `DbType` + overrides for unsigned integer types.                    |
+| [MySQL](readSqlTypeMapping_MySQL.md)                         | Default `DbType` + overrides for unsigned integer types.                    |
+| [PostgreSQL](readSqlTypeMapping_PostgreSQL.md)               | Default `DbType` + `PGobject` overrides (`box`, `point`, `money`, ...).     |
+| [MS SQL Server](readSqlTypeMapping_MsSql.md)                 | Default `DbType`, no overrides.                                             |
+| [H2](readSqlTypeMapping_H2.md)                               | Default `DbType` in `Regular` mode; other modes delegate to another dialect.|
+| [SQLite](readSqlTypeMapping_SQLite.md)                       | Custom: type affinity resolves declared types dynamically.                  |
+| [DuckDB](readSqlTypeMapping_DuckDB.md)                       | Bypasses `getExpectedJdbcType`; uses its own converter.                     |
+
+## Extending the mapping
+
+If none of the built-in mappings fit your use case, you can register a custom `DbType`;
+see [Reading from a custom SQL database](readSqlFromCustomDatabase.md).
diff --git a/docs/StardustDocs/topics/readSqlTypeMapping_DuckDB.md b/docs/StardustDocs/topics/readSqlTypeMapping_DuckDB.md
new file mode 100644
index 0000000000..4ef7d39d3d
--- /dev/null
+++ b/docs/StardustDocs/topics/readSqlTypeMapping_DuckDB.md
@@ -0,0 +1,123 @@
+[//]: # (title: DuckDB type mapping)
+
+<web-summary>
+Reference table of how each DuckDB column type is mapped to a Kotlin type when read into
+a Kotlin DataFrame.
+</web-summary>
+
+<card-summary>
+How DuckDB column types are read into DataFrame, including nested types.
+</card-summary>
+
+<link-summary>
+Full mapping of DuckDB SQL types to Kotlin types, including aliases and nested-type support.
+</link-summary>
+
+DuckDB uses a dedicated converter that bypasses `DbType.getExpectedJdbcType` and matches
+directly on DuckDB's type names (see `DuckDb.parseDuckDbType`).
+The tables below list every DuckDB column type
+([DuckDB Data Types](https://duckdb.org/docs/sql/data_types/overview)) and the resulting
+Kotlin type. Aliases are canonicalised by DuckDB at `CREATE TABLE` time, so DataFrame only
+ever sees the canonical type; they are listed in the same row as the canonical type for
+reference.
+
+Nullable columns produce nullable Kotlin types (`Int?` instead of `Int`).
+
+## Boolean
+
+| Canonical | Aliases            | DataFrame type | Notes |
+|-----------|--------------------|----------------|-------|
+| `BOOLEAN` | `BOOL`, `LOGICAL`  | `Boolean`      |       |
+
+## Signed integer types
+
+| Canonical    | Aliases          | DataFrame type          | Notes                                  |
+|--------------|------------------|-------------------------|----------------------------------------|
+| `TINYINT`    | `INT1`           | `Byte`                  | 1-byte signed.                         |
+| `SMALLINT`   | `INT2`, `SHORT`  | `Short`                 | 2-byte signed.                         |
+| `INTEGER`    | `INT4`, `INT`, `SIGNED` | `Int`            | 4-byte signed.                         |
+| `BIGINT`     | `INT8`, `LONG`   | `Long`                  | 8-byte signed.                         |
+| `HUGEINT`    | *none*           | `java.math.BigInteger`  | 16-byte signed (`-2^127 .. 2^127 - 1`).|
+
+## Unsigned integer types
+
+| Canonical    | Aliases | DataFrame type          | Notes                                          |
+|--------------|---------|-------------------------|------------------------------------------------|
+| `UTINYINT`   | *none*  | `Short`                 | 1-byte unsigned; widened to `Short`.           |
+| `USMALLINT`  | *none*  | `Int`                   | 2-byte unsigned; widened to `Int`.             |
+| `UINTEGER`   | *none*  | `Long`                  | 4-byte unsigned; widened to `Long`.            |
+| `UBIGINT`    | *none*  | `java.math.BigInteger`  | 8-byte unsigned; exceeds `Long`.               |
+| `UHUGEINT`   | *none*  | `java.math.BigInteger`  | 16-byte unsigned.                              |
+
+## Floating-point and fixed-point
+
+| Canonical     | Aliases                             | DataFrame type          | Notes                                          |
+|---------------|-------------------------------------|-------------------------|------------------------------------------------|
+| `FLOAT`       | `FLOAT4`, `REAL`                    | `Float`                 | 4-byte float.                                  |
+| `DOUBLE`      | `FLOAT8`, `DOUBLE PRECISION`        | `Double`                | 8-byte float.                                  |
+| `DECIMAL(p,s)`| `NUMERIC(p,s)`                      | `java.math.BigDecimal`  | Fixed-point; `NUMERIC` without precision defaults to `DECIMAL(18,3)`. |
+
+## String and binary
+
+| Canonical   | Aliases                                         | DataFrame type   | Notes                                                                    |
+|-------------|-------------------------------------------------|------------------|--------------------------------------------------------------------------|
+| `VARCHAR`   | `CHAR`, `BPCHAR`, `TEXT`, `STRING`              | `String`         | Variable-length text.                                                    |
+| `BLOB`      | `BYTEA`, `BINARY`, `VARBINARY`                  | `java.sql.Blob`  | Binary large object.                                                     |
+| `BIT`       | *none*                                          | `String`         | Fixed-length bit string; read as text.                                   |
+
+## Date and time
+
+| Canonical                    | Aliases                            | DataFrame type              | Notes                                                        |
+|------------------------------|------------------------------------|-----------------------------|--------------------------------------------------------------|
+| `DATE`                       | *none*                             | `kotlinx.datetime.LocalDate`| Preprocessed from `java.time.LocalDate`.                     |
+| `TIME`                       | *none*                             | `kotlinx.datetime.LocalTime`| Preprocessed from `java.time.LocalTime`.                     |
+| `TIME_NS`                    | *none*                             | `kotlinx.datetime.LocalTime`| Nanosecond-precision time.                                   |
+| `TIME WITH TIME ZONE`        | `TIMETZ`                           | `java.time.OffsetTime`      |                                                              |
+| `TIMESTAMP`                  | `DATETIME`                         | `kotlin.time.Instant`       | Preprocessed from `java.sql.Timestamp`.                      |
+| `TIMESTAMP_MS`               | *none*                             | `kotlin.time.Instant`       | Millisecond-precision timestamp.                             |
+| `TIMESTAMP_NS`               | *none*                             | `kotlin.time.Instant`       | Nanosecond-precision timestamp.                              |
+| `TIMESTAMP_S`                | *none*                             | `kotlin.time.Instant`       | Second-precision timestamp.                                  |
+| `TIMESTAMP WITH TIME ZONE`   | `TIMESTAMPTZ`                      | `java.time.OffsetDateTime`  | Timestamp with time zone.                                    |
+| `INTERVAL`                   | *none*                             | `String`                    | Read as text.                                                |
+
+## Complex / nested types
+
+DuckDB supports nested / composite types, which the DataFrame converter resolves recursively.
+
+| Canonical                    | Aliases | DataFrame type                     | Notes                                                                                     |
+|------------------------------|---------|------------------------------------|-------------------------------------------------------------------------------------------|
+| `LIST` (`T[]`)               | *none*  | `List<T>`                          | Element type is resolved recursively.                                                     |
+| `ARRAY` (`T[N]`)             | *none*  | `List<T>`                          | Same as `LIST`; the element type is resolved recursively.                                 |
+| `MAP(K, V)`                  | *none*  | `Map<K, V>`                        | Key and value types are resolved recursively.                                             |
+| `STRUCT(...)`                | *none*  | column group (`DataRow`)           | Fields resolved recursively; array-of-struct becomes a frame column.                      |
+| `UNION`                      | *none*  | `Any`                              | Not currently unpacked in Kotlin.                                                         |
+| `VARIANT`                    | *none*  | `Any`                              | Not currently unpacked in Kotlin.                                                         |
+
+## Other
+
+| Canonical    | Aliases | DataFrame type       | Notes                                                                                    |
+|--------------|---------|----------------------|------------------------------------------------------------------------------------------|
+| `UUID`       | *none*  | `kotlin.uuid.Uuid`   | Preprocessed from `java.util.UUID`.                                                      |
+| `JSON`       | *none*  | `String` (parsed)    | Read as JSON text and passed through `tryParse` + type inference.                        |
+| `ENUM`       | *none*  | `String`             | Read as the enum label.                                                                  |
+| `GEOMETRY`   | *none*  | `java.sql.Blob`      | Binary WKB read as `Blob`.                                                               |
+| `UNKNOWN`    | *none*  | `String`             | Fallback for anything not recognised by the converter.                                   |
+
+## DuckDB specifics
+
+- DuckDB bypasses `DbType.getExpectedJdbcType` — its type resolution goes through
+  `DuckDb.parseDuckDbType` and matches directly on the DuckDB type name.
+- Nested types (`LIST`, `ARRAY`, `MAP`, `STRUCT`) are resolved recursively: `INTEGER[]`
+  becomes `List<Int>`, `MAP(VARCHAR, INTEGER)` becomes `Map<String, Int>`, and so on.
+- `STRUCT(...)` becomes a **column group** (`DataRow`); arrays of `STRUCT` become **frame
+  columns** (`DataFrame`).
+- Reading a DuckDB `JSON` column parses the text and re-infers the resulting DataFrame's
+  type — the column ends up as whatever the parser detected.
+
+## Unsupported types
+
+- `UNION` and `VARIANT` values are read as raw `Any` — the payload's actual type is not
+  unpacked in Kotlin.
+- `INTERVAL` values are read as their text form; no `Duration` conversion is applied.
+- Extension types (spatial via `duckdb_spatial`, full-text search, etc.) are read as the
+  extension's underlying storage type (usually `Blob` or `String`).
diff --git a/docs/StardustDocs/topics/readSqlTypeMapping_H2.md b/docs/StardustDocs/topics/readSqlTypeMapping_H2.md
new file mode 100644
index 0000000000..c52c9e5d5a
--- /dev/null
+++ b/docs/StardustDocs/topics/readSqlTypeMapping_H2.md
@@ -0,0 +1,113 @@
+[//]: # (title: H2 type mapping)
+
+<web-summary>
+Reference table of how each H2 column type is mapped to a Kotlin type when read into
+a Kotlin DataFrame.
+</web-summary>
+
+<card-summary>
+How H2 column types are read into DataFrame.
+</card-summary>
+
+<link-summary>
+Full mapping of H2 SQL types to Kotlin types, including aliases and mode-specific behavior.
+</link-summary>
+
+The tables below list every H2 column type ([H2 Data Types](https://www.h2database.com/html/datatypes.html))
+and the Kotlin type produced when the column is read into a DataFrame in `H2.Mode.Regular`.
+Aliases are canonicalised by H2 at `CREATE TABLE` time, so DataFrame only ever sees the
+canonical type; they are listed in the same row as the canonical type for reference.
+
+For non-`Regular` modes, H2 delegates to the emulated dialect — see the [Mode section](#h2-modes) below.
+
+Nullable columns produce nullable Kotlin types (`Int?` instead of `Int`).
+
+## Character types
+
+| Canonical               | Aliases                                                                | DataFrame type | Notes                          |
+|-------------------------|------------------------------------------------------------------------|----------------|--------------------------------|
+| `CHAR[(n)]`             | `CHARACTER`, `NCHAR`                                                   | `String`       | Fixed-length text.             |
+| `VARCHAR[(n)]`          | `CHARACTER VARYING`, `LONGVARCHAR`, `VARCHAR2`, `NVARCHAR`, `NVARCHAR2`, `VARCHAR_CASESENSITIVE` | `String` | Variable-length text.  |
+| `VARCHAR_IGNORECASE[(n)]` | *none*                                                               | `String`       | Case-insensitive comparison; stored as text.        |
+| `CLOB`                  | `CHARACTER LARGE OBJECT`, `TINYTEXT`, `TEXT`, `MEDIUMTEXT`, `LONGTEXT`, `NTEXT`, `NCLOB` | `java.sql.Clob` | Large text object. |
+
+## Binary types
+
+| Canonical      | Aliases                                                                | DataFrame type | Notes                          |
+|----------------|------------------------------------------------------------------------|----------------|--------------------------------|
+| `BINARY[(n)]`  | `RAW`                                                                  | `ByteArray`    | Fixed-length binary.           |
+| `VARBINARY[(n)]` | `LONGVARBINARY`, `BINARY VARYING`                                    | `ByteArray`    | Variable-length binary.        |
+| `BLOB`         | `BINARY LARGE OBJECT`, `TINYBLOB`, `MEDIUMBLOB`, `LONGBLOB`, `IMAGE`   | `java.sql.Blob` | Large binary object.          |
+
+## Boolean
+
+| Canonical | Aliases                | DataFrame type | Notes                                    |
+|-----------|------------------------|----------------|------------------------------------------|
+| `BOOLEAN` | `BOOL`, `BIT`, `LOGICAL` | `Boolean`    | Single-bit boolean.                      |
+
+## Numeric types
+
+| Canonical                        | Aliases                                        | DataFrame type          | Notes                                          |
+|----------------------------------|------------------------------------------------|-------------------------|------------------------------------------------|
+| `TINYINT`                        | *none*                                         | `Int`                   | 1-byte signed integer.                         |
+| `SMALLINT`                       | `INT2`, `YEAR`                                 | `Int`                   | 2-byte signed integer.                         |
+| `INTEGER`                        | `INT`, `INT4`, `MEDIUMINT`, `SIGNED`           | `Int`                   | 4-byte signed integer.                         |
+| `BIGINT`                         | `INT8`                                         | `Long`                  | 8-byte signed integer.                         |
+| `NUMERIC[(p[,s])]`               | `DECIMAL[(p[,s])]`, `DEC[(p[,s])]`, `NUMBER[(p[,s])]` | `java.math.BigDecimal` | Fixed-point.                               |
+| `REAL`                           | `FLOAT4`                                       | `Float`                 | 4-byte float.                                  |
+| `DOUBLE PRECISION`               | `DOUBLE`, `FLOAT`, `FLOAT8`                    | `Double`                | 8-byte float.                                  |
+| `DECFLOAT[(p)]`                  | *none*                                         | `java.math.BigDecimal`  | Decimal floating-point (H2 2.0+).              |
+
+## Date and time types
+
+| Canonical                                  | Aliases       | DataFrame type              | Notes                                                        |
+|--------------------------------------------|---------------|-----------------------------|--------------------------------------------------------------|
+| `DATE`                                     | *none*        | `java.util.Date`            |                                                              |
+| `TIME[(p)] [WITHOUT TIME ZONE]`            | *none*        | `java.sql.Time`             |                                                              |
+| `TIME[(p)] WITH TIME ZONE`                 | *none*        | `java.time.OffsetTime`      |                                                              |
+| `TIMESTAMP[(p)] [WITHOUT TIME ZONE]`       | `DATETIME`, `SMALLDATETIME` | `kotlin.time.Instant`     | Preprocessed from `java.sql.Timestamp`.                      |
+| `TIMESTAMP[(p)] WITH TIME ZONE`            | `DATETIMEOFFSET`, `TIMESTAMPTZ` | `java.time.OffsetDateTime` |                                                    |
+| `INTERVAL YEAR[(p)]`, `INTERVAL MONTH[(p)]`, ... | *none*  | `String`                    | Any of the 13 interval subtypes; read as text.               |
+
+## Other types
+
+| Canonical            | Aliases        | DataFrame type      | Notes                                                                                    |
+|----------------------|----------------|---------------------|------------------------------------------------------------------------------------------|
+| `UUID`               | *none*         | `kotlin.uuid.Uuid`  | Preprocessed from `java.util.UUID`. Driver reports `Types.BINARY` + `java.util.UUID` class. |
+| `JAVA_OBJECT`        | `OTHER`        | `Any`               | Serialised Java object; read as opaque `Any`.                                            |
+| `ENUM`               | *none*         | `String`            | User-declared enum labels.                                                               |
+| `GEOMETRY`           | *none*         | `String`            | WKT text as reported by the driver.                                                      |
+| `JSON`               | *none*         | `String`            | JSON text.                                                                               |
+| `ARRAY`              | *none*         | `Array<*>`          | Element type inferred; falls back to `Any` for heterogeneous arrays.                     |
+| `ROW(...)`           | *none*         | *unsupported*       | See [Unsupported types](#unsupported-types).                                             |
+
+## H2 modes
+
+`H2(mode = ...)` selects the dialect H2 emulates and delegates its type mapping to that
+dialect. The default mode is `Regular`.
+
+| Mode           | Delegates to                                                    |
+|----------------|-----------------------------------------------------------------|
+| `Regular`      | Default H2 mapping (this page)                                  |
+| `MySql`        | [MySQL](readSqlTypeMapping_MySQL.md)                            |
+| `PostgreSql`   | [PostgreSQL](readSqlTypeMapping_PostgreSQL.md)                  |
+| `MsSqlServer`  | [MS SQL](readSqlTypeMapping_MsSql.md)                           |
+| `MariaDb`      | [MariaDB](readSqlTypeMapping_MariaDB.md)                        |
+
+## H2 specifics
+
+- H2 supports **compatibility modes** that emulate other dialects — set them via the JDBC URL
+  (`;MODE=MySQL`) and construct the corresponding `H2.Mode`. In compatibility modes, H2's
+  reserved-word list, function set, and type mapping change to match the emulated dialect.
+- `TIMESTAMP` and `DATETIME` are canonicalised to the same `TIMESTAMP` in metadata.
+- H2's `UUID` type is a first-class type (unlike PostgreSQL's, which is read as text) — the
+  driver reports it as a `BINARY` JDBC type with `java.util.UUID` class, so the mapping
+  produces `kotlin.uuid.Uuid` after preprocessing.
+- `NUMERIC` and `DECIMAL` are identical in H2 — both map to `BigDecimal`.
+
+## Unsupported types
+
+- `ROW(...)` composite / structured types.
+- `INTERVAL` subtypes (all 13 read as their string form).
+- Domain types (H2 supports `CREATE DOMAIN`), read as the underlying primitive.
+- `GEOMETRY` in binary/WKB form (WKT string is what the driver returns by default).
diff --git a/docs/StardustDocs/topics/readSqlTypeMapping_MariaDB.md b/docs/StardustDocs/topics/readSqlTypeMapping_MariaDB.md
new file mode 100644
index 0000000000..95a38f4e42
--- /dev/null
+++ b/docs/StardustDocs/topics/readSqlTypeMapping_MariaDB.md
@@ -0,0 +1,119 @@
+[//]: # (title: MariaDB type mapping)
+
+<web-summary>
+Reference table of how each MariaDB column type is mapped to a Kotlin type when read into
+a Kotlin DataFrame.
+</web-summary>
+
+<card-summary>
+How MariaDB column types are read into DataFrame.
+</card-summary>
+
+<link-summary>
+Full mapping of MariaDB SQL types to Kotlin types, including aliases and driver caveats.
+</link-summary>
+
+The tables below list every MariaDB column type ([MariaDB Data Types](https://mariadb.com/kb/en/data-types/))
+and the Kotlin type produced when the column is read into a DataFrame. Aliases are
+canonicalised by MariaDB at `CREATE TABLE` time, so DataFrame only ever sees the canonical
+type; they are listed in the same row as the canonical type for reference.
+
+Nullable columns produce nullable Kotlin types (`Int?` instead of `Int`).
+
+## Numeric types
+
+| Canonical              | Aliases                | DataFrame type          | Notes                                                          |
+|------------------------|------------------------|-------------------------|----------------------------------------------------------------|
+| `TINYINT[(M)]`         | `INT1`                 | `Int`                   | 1-byte signed integer (`-128 .. 127`).                         |
+| `TINYINT UNSIGNED`     | `INT1 UNSIGNED`        | `Int`                   | 1-byte unsigned integer (`0 .. 255`).                          |
+| `BOOL`, `BOOLEAN`      | *(alias only)*         | `Boolean`               | Stored as `TINYINT(1)`; values are `0`/`1`.                    |
+| `SMALLINT[(M)]`        | `INT2`                 | `Int`                   | 2-byte signed integer. Becomes `Short` if the driver reports the column class as `java.lang.Short`. |
+| `SMALLINT UNSIGNED`    | `INT2 UNSIGNED`        | `Int`                   | 2-byte unsigned integer.                                       |
+| `MEDIUMINT[(M)]`       | `INT3`, `MIDDLEINT`    | `Int`                   | 3-byte signed integer.                                         |
+| `MEDIUMINT UNSIGNED`   | `INT3 UNSIGNED`, `MIDDLEINT UNSIGNED` | `Int`    | 3-byte unsigned integer.                                       |
+| `INT[(M)]`             | `INTEGER`, `INT4`      | `Int`                   | 4-byte signed integer.                                         |
+| `INT UNSIGNED`         | `INTEGER UNSIGNED`, `INT4 UNSIGNED` | `Long`     | MariaDB override: fits in `Long`, not `Int`.                   |
+| `BIGINT[(M)]`          | `INT8`                 | `Long`                  | 8-byte signed integer.                                         |
+| `BIGINT UNSIGNED`      | `INT8 UNSIGNED`        | `java.math.BigInteger`  | MariaDB override: exceeds `Long`, needs `BigInteger`.          |
+| `DECIMAL(M,D)`         | `DEC`, `NUMERIC`, `FIXED` | `java.math.BigDecimal` | Fixed-point.                                                   |
+| `FLOAT[(P)]`           | `FLOAT4`               | `Float`                 | 4-byte float. Becomes `Double` if the driver reports the column class as `java.lang.Double`. |
+| `DOUBLE`               | `FLOAT8`, `DOUBLE PRECISION`, `REAL` | `Double`  | 8-byte float.                                                  |
+| `BIT(M)`               | *none*                 | `ByteArray`             | Reported as `VARBINARY` for `M > 1`; `BIT(1)` may map to `Boolean`. |
+
+## Date and time types
+
+| Canonical           | Aliases        | DataFrame type              | Notes                                                                      |
+|---------------------|----------------|-----------------------------|----------------------------------------------------------------------------|
+| `DATE`              | *none*         | `java.util.Date`            |                                                                            |
+| `TIME[(fsp)]`       | *none*         | `java.sql.Time`             | `fsp` is fractional seconds precision (0–6).                               |
+| `DATETIME[(fsp)]`   | *none*         | `kotlin.time.Instant`       | Preprocessed from `java.sql.Timestamp`.                                    |
+| `TIMESTAMP[(fsp)]`  | *none*         | `kotlin.time.Instant`       | Preprocessed from `java.sql.Timestamp`.                                    |
+| `YEAR[(4)]`         | *none*         | `java.util.Date`            | 1-byte year (`1901..2155`); driver reports it as `Types.DATE`.             |
+
+## String types
+
+| Canonical                | Aliases                              | DataFrame type       | Notes                                                                    |
+|--------------------------|--------------------------------------|----------------------|--------------------------------------------------------------------------|
+| `CHAR(M)`                | `CHARACTER(M)`, `NATIONAL CHAR(M)`, `NCHAR(M)` | `String`   | Fixed-length text. Max `M = 255`.                                        |
+| `VARCHAR(M)`             | `CHARACTER VARYING(M)`, `NATIONAL VARCHAR(M)`, `NVARCHAR(M)` | `String` | Variable-length text.                                            |
+| `BINARY(M)`              | *none*                               | `ByteArray`          | Fixed-length binary.                                                     |
+| `VARBINARY(M)`           | `BINARY VARYING(M)`                  | `ByteArray`          | Variable-length binary.                                                  |
+| `TINYBLOB`               | *none*                               | `ByteArray`          | Up to 255 bytes.                                                         |
+| `TINYTEXT`               | *none*                               | `String`             | Up to 255 bytes.                                                         |
+| `BLOB[(M)]`              | *none*                               | `ByteArray`          | Up to 64 KiB.                                                            |
+| `TEXT[(M)]`              | *none*                               | `String`             | Up to 64 KiB.                                                            |
+| `MEDIUMBLOB`             | `LONG VARBINARY`                     | `ByteArray`          | Up to 16 MiB.                                                            |
+| `MEDIUMTEXT`             | `LONG VARCHAR`, `LONG`               | `String`             | Up to 16 MiB.                                                            |
+| `LONGBLOB`               | *none*                               | `ByteArray`          | Up to 4 GiB.                                                             |
+| `LONGTEXT`               | *none*                               | `String`             | Up to 4 GiB.                                                             |
+| `ENUM(...)`              | *none*                               | `String`             | Enumeration; values read as their string form.                           |
+| `SET(...)`               | *none*                               | `String`             | Comma-separated set of values, as a single string.                       |
+
+## JSON and UUID
+
+| Canonical  | Aliases | DataFrame type          | Notes                                                                                |
+|------------|---------|-------------------------|--------------------------------------------------------------------------------------|
+| `JSON`     | *none*  | `String`                | Physically stored as `LONGTEXT` in MariaDB; JDBC reports `LONGVARCHAR` → `String`.   |
+| `UUID`     | *none*  | `String`                | Available in MariaDB 10.7+. Read as text.                                            |
+| `INET4`    | *none*  | `String`                | Available in MariaDB 10.10+.                                                         |
+| `INET6`    | *none*  | `String`                | Available in MariaDB 10.10+.                                                         |
+| `ROW(...)` | *none*  | *unsupported*           | Anonymous row types are not currently mapped; see [Unsupported types](#unsupported-types). |
+
+## Spatial types
+
+All spatial types are read as `ByteArray` (WKB / EWKB binary as reported by the driver).
+Parse them with a client-side geometry library.
+
+| Canonical            | Aliases | DataFrame type | Notes |
+|----------------------|---------|----------------|-------|
+| `GEOMETRY`           | *none*  | `ByteArray`    |       |
+| `POINT`              | *none*  | `ByteArray`    |       |
+| `LINESTRING`         | *none*  | `ByteArray`    |       |
+| `POLYGON`            | *none*  | `ByteArray`    |       |
+| `MULTIPOINT`         | *none*  | `ByteArray`    |       |
+| `MULTILINESTRING`    | *none*  | `ByteArray`    |       |
+| `MULTIPOLYGON`       | *none*  | `ByteArray`    |       |
+| `GEOMETRYCOLLECTION` | *none*  | `ByteArray`    |       |
+
+## MariaDB specifics
+
+- `INT UNSIGNED` / `INTEGER UNSIGNED` and `BIGINT UNSIGNED` are the only types that need
+  MariaDB-specific handling. `INT UNSIGNED` is widened to `Long` and `BIGINT UNSIGNED`
+  becomes `BigInteger` because its range exceeds `Long`.
+- `SMALLINT` may become `Short` (rather than `Int`) when the JDBC driver reports the column
+  class as `java.lang.Short`.
+- `BIT(1)` and `BOOLEAN` are stored the same way (as `TINYINT(1)`) in older MariaDB versions;
+  which Kotlin type surfaces depends on driver behavior.
+- Zero-fill and display-width modifiers (e.g. `INT(11)`, `TINYINT ZEROFILL`) do not affect the
+  DataFrame type.
+
+## Unsupported types
+
+The following types are not mapped and read into DataFrame as best effort — either as
+`String` (via the driver's `getString` fallback) or as `ByteArray`. Explicit support may be
+added in future releases; for now, prefer explicit `CAST(... AS TEXT)` in the query or
+supply a custom converter via [a custom DbType](readSqlFromCustomDatabase.md).
+
+- Anonymous `ROW(...)` types.
+- `VECTOR` (MariaDB 11.7+).
+- Native representations of spatial types (they read as raw WKB `ByteArray`).
diff --git a/docs/StardustDocs/topics/readSqlTypeMapping_MsSql.md b/docs/StardustDocs/topics/readSqlTypeMapping_MsSql.md
new file mode 100644
index 0000000000..ad9d209555
--- /dev/null
+++ b/docs/StardustDocs/topics/readSqlTypeMapping_MsSql.md
@@ -0,0 +1,113 @@
+[//]: # (title: MS SQL Server type mapping)
+
+<web-summary>
+Reference table of how each MS SQL Server column type is mapped to a Kotlin type when read
+into a Kotlin DataFrame.
+</web-summary>
+
+<card-summary>
+How MS SQL Server column types are read into DataFrame.
+</card-summary>
+
+<link-summary>
+Full mapping of MS SQL Server SQL types to Kotlin types, including aliases and driver caveats.
+</link-summary>
+
+The tables below list every MS SQL Server column type
+([Transact-SQL Data types](https://learn.microsoft.com/en-us/sql/t-sql/data-types/data-types-transact-sql))
+and the Kotlin type produced when the column is read into a DataFrame. Aliases are
+canonicalised by SQL Server at `CREATE TABLE` time, so DataFrame only ever sees the canonical
+type; they are listed in the same row as the canonical type for reference.
+
+Nullable columns produce nullable Kotlin types (`Int?` instead of `Int`).
+
+## Exact numeric types
+
+| Canonical           | Aliases                | DataFrame type          | Notes                                                                                     |
+|---------------------|------------------------|-------------------------|-------------------------------------------------------------------------------------------|
+| `bit`               | *none*                 | `Boolean`               | Single-bit integer (`0`/`1`/`NULL`).                                                      |
+| `tinyint`           | *none*                 | `Int`                   | 1-byte **unsigned** integer (`0..255`) — unusual: SQL Server's `tinyint` is unsigned.     |
+| `smallint`          | *none*                 | `Int`                   | 2-byte signed integer.                                                                    |
+| `int`               | `integer`              | `Int`                   | 4-byte signed integer.                                                                    |
+| `bigint`            | *none*                 | `Long`                  | 8-byte signed integer.                                                                    |
+| `decimal(p,s)`      | `dec(p,s)`, `numeric(p,s)` | `java.math.BigDecimal` | Fixed-point. `NUMERIC` and `DECIMAL` are stored identically.                          |
+| `smallmoney`        | *none*                 | `java.math.BigDecimal`  | 4-byte fixed-point money (`-214,748.3648 .. 214,748.3647`).                               |
+| `money`             | *none*                 | `java.math.BigDecimal`  | 8-byte fixed-point money.                                                                 |
+
+## Approximate numeric types
+
+| Canonical             | Aliases                            | DataFrame type | Notes                                                    |
+|-----------------------|------------------------------------|----------------|----------------------------------------------------------|
+| `float(n)`            | `double precision` (n = 53)        | `Double`       | Default `n = 53`. `float(1..24)` maps to `Float`.        |
+| `real`                | *(alias)* `float(24)`              | `Float`        | Explicit 4-byte float; equivalent to `float(24)`.        |
+
+## Date and time types
+
+| Canonical               | Aliases | DataFrame type              | Notes                                                                     |
+|-------------------------|---------|-----------------------------|---------------------------------------------------------------------------|
+| `date`                  | *none*  | `java.util.Date`            | Date only (`0001-01-01 .. 9999-12-31`).                                   |
+| `time(n)`               | *none*  | `java.sql.Time`             | Time only with fractional-second precision (0–7).                         |
+| `smalldatetime`         | *none*  | `kotlin.time.Instant`       | Date + minute-precision time.                                             |
+| `datetime`              | *none*  | `kotlin.time.Instant`       | Legacy date + time; ~3.33 ms precision.                                   |
+| `datetime2(n)`          | *none*  | `kotlin.time.Instant`       | Modern date + time with fractional-second precision (0–7).                |
+| `datetimeoffset(n)`     | *none*  | `java.time.OffsetDateTime`  | Date + time + explicit UTC offset.                                        |
+
+## Character strings
+
+| Canonical             | Aliases                                   | DataFrame type | Notes                                                              |
+|-----------------------|-------------------------------------------|----------------|--------------------------------------------------------------------|
+| `char(n)`             | `character(n)`                            | `String`       | Fixed-length non-Unicode text (max `n = 8000`).                    |
+| `varchar(n | max)`    | `character varying(n)`                    | `String`       | Variable-length non-Unicode text.                                  |
+| `text`                | *none*                                    | `String`       | **Deprecated** — use `varchar(max)`.                               |
+| `nchar(n)`            | `national character(n)`, `national char(n)` | `String`     | Fixed-length UTF-16 text (max `n = 4000`).                         |
+| `nvarchar(n | max)`   | `national character varying(n)`, `national char varying(n)` | `String` | Variable-length UTF-16 text.                                 |
+| `ntext`               | `national text`                           | `String`       | **Deprecated** — use `nvarchar(max)`.                              |
+
+## Binary strings
+
+| Canonical             | Aliases                          | DataFrame type | Notes                                              |
+|-----------------------|----------------------------------|----------------|----------------------------------------------------|
+| `binary(n)`           | *none*                           | `ByteArray`    | Fixed-length binary (max `n = 8000`).              |
+| `varbinary(n | max)`  | `binary varying(n)`              | `ByteArray`    | Variable-length binary.                            |
+| `image`               | *none*                           | `ByteArray`    | **Deprecated** — use `varbinary(max)`.             |
+
+## Row-version and identity
+
+| Canonical         | Aliases       | DataFrame type | Notes                                                                                                     |
+|-------------------|---------------|----------------|-----------------------------------------------------------------------------------------------------------|
+| `rowversion`      | `timestamp`   | `ByteArray`    | 8-byte row-version. **Note:** SQL Server's `timestamp` is *not* a date/time type. Use `datetime2` instead. |
+| `uniqueidentifier`| *none*        | `String`       | 16-byte GUID, read as its 36-character string form.                                                       |
+
+## Other types
+
+| Canonical      | Aliases | DataFrame type    | Notes                                                                                              |
+|----------------|---------|-------------------|----------------------------------------------------------------------------------------------------|
+| `xml`          | *none*  | `String`          | XML document text.                                                                                 |
+| `sql_variant`  | *none*  | `Any`             | Column holds a value of any base type; driver returns as generic `Object`.                         |
+| `hierarchyid`  | *none*  | `ByteArray`       | Hierarchical position (raw binary).                                                                |
+| `geometry`     | *none*  | `ByteArray`       | Planar spatial (WKB / EWKB).                                                                       |
+| `geography`    | *none*  | `ByteArray`       | Geodetic spatial (WKB / EWKB).                                                                     |
+
+## MS SQL Server specifics
+
+- Unlike most databases, SQL Server's `tinyint` is **unsigned** (`0..255`), not signed.
+- The keyword `TIMESTAMP` in T-SQL is a synonym for `rowversion` (a row-version stamp), **not**
+  a date/time type. Use `datetime2` for wall-clock timestamps.
+- `text`, `ntext`, and `image` are deprecated; SQL Server documentation recommends
+  `varchar(max)` / `nvarchar(max)` / `varbinary(max)` respectively.
+- `float(n)` with `n <= 24` returns `Float`; `n >= 25` returns `Double`. `float` alone means
+  `float(53)` and returns `Double`. `real` is `float(24)` and returns `Float`.
+- MS SQL Server does not need any DB-specific overrides in DataFrame — the default `DbType`
+  mapping is used as-is.
+
+## Unsupported types
+
+Types below are read as best effort (usually `ByteArray` or `String`). Explicit typed
+support may be added later; for now, cast in your query (`geom.STAsText()`,
+`CAST(v AS NVARCHAR)`) or supply a custom converter via
+[a custom DbType](readSqlFromCustomDatabase.md).
+
+- `geometry`, `geography` (read as raw WKB `ByteArray`).
+- `hierarchyid` (read as raw `ByteArray`).
+- `sql_variant` (read as generic `Any`).
+- `cursor` and `table` types cannot be columns; they only occur as procedure parameters.
diff --git a/docs/StardustDocs/topics/readSqlTypeMapping_MySQL.md b/docs/StardustDocs/topics/readSqlTypeMapping_MySQL.md
new file mode 100644
index 0000000000..79552e870e
--- /dev/null
+++ b/docs/StardustDocs/topics/readSqlTypeMapping_MySQL.md
@@ -0,0 +1,114 @@
+[//]: # (title: MySQL type mapping)
+
+<web-summary>
+Reference table of how each MySQL column type is mapped to a Kotlin type when read into
+a Kotlin DataFrame.
+</web-summary>
+
+<card-summary>
+How MySQL column types are read into DataFrame.
+</card-summary>
+
+<link-summary>
+Full mapping of MySQL SQL types to Kotlin types, including aliases and driver caveats.
+</link-summary>
+
+The tables below list every MySQL column type ([MySQL 8.0 Data Types](https://dev.mysql.com/doc/refman/8.0/en/data-types.html))
+and the Kotlin type produced when the column is read into a DataFrame. Aliases are
+canonicalised by MySQL at `CREATE TABLE` time, so DataFrame only ever sees the canonical
+type; they are listed in the same row as the canonical type for reference.
+
+Nullable columns produce nullable Kotlin types (`Int?` instead of `Int`).
+
+## Numeric types
+
+| Canonical              | Aliases                | DataFrame type          | Notes                                                                                     |
+|------------------------|------------------------|-------------------------|-------------------------------------------------------------------------------------------|
+| `TINYINT[(M)]`         | `INT1`                 | `Int`                   | 1-byte signed integer (`-128 .. 127`).                                                    |
+| `TINYINT UNSIGNED`     | `INT1 UNSIGNED`        | `Int`                   | 1-byte unsigned integer (`0 .. 255`).                                                     |
+| `BOOL`, `BOOLEAN`      | *(alias only)*         | `Boolean`               | Stored as `TINYINT(1)`; values are `0`/`1`.                                               |
+| `SMALLINT[(M)]`        | `INT2`                 | `Int`                   | 2-byte signed integer.                                                                    |
+| `SMALLINT UNSIGNED`    | `INT2 UNSIGNED`        | `Int`                   | 2-byte unsigned integer.                                                                  |
+| `MEDIUMINT[(M)]`       | `INT3`, `MIDDLEINT`    | `Int`                   | 3-byte signed integer.                                                                    |
+| `MEDIUMINT UNSIGNED`   | `INT3 UNSIGNED`, `MIDDLEINT UNSIGNED` | `Int`    | 3-byte unsigned integer.                                                                  |
+| `INT[(M)]`             | `INTEGER`, `INT4`      | `Int`                   | 4-byte signed integer.                                                                    |
+| `INT UNSIGNED`         | `INTEGER UNSIGNED`, `INT4 UNSIGNED` | `Long`     | MySQL override: fits in `Long`, not `Int`.                                                |
+| `BIGINT[(M)]`          | `INT8`                 | `Long`                  | 8-byte signed integer.                                                                    |
+| `BIGINT UNSIGNED`      | `INT8 UNSIGNED`        | `java.math.BigInteger`  | MySQL override: exceeds `Long`, needs `BigInteger`.                                       |
+| `DECIMAL(M,D)`         | `DEC`, `NUMERIC`, `FIXED` | `java.math.BigDecimal` | Fixed-point.                                                                              |
+| `FLOAT[(P)]`           | `FLOAT4`               | `Float`                 | 4-byte float. Becomes `Double` if the driver reports the column class as `java.lang.Double`. |
+| `DOUBLE`               | `FLOAT8`, `DOUBLE PRECISION` | `Double`         | 8-byte float.                                                                             |
+| `REAL`                 | *(alias only)*         | `Double`                | By default `REAL` is `DOUBLE`. Becomes `FLOAT` under the `REAL_AS_FLOAT` SQL mode.         |
+| `BIT(M)`               | *none*                 | `ByteArray`             | Reported as `BIT`/`VARBINARY`; `BIT(1)` may map to `Boolean`.                              |
+
+## Date and time types
+
+| Canonical           | Aliases  | DataFrame type          | Notes                                                                     |
+|---------------------|----------|-------------------------|---------------------------------------------------------------------------|
+| `DATE`              | *none*   | `java.util.Date`        |                                                                           |
+| `TIME[(fsp)]`       | *none*   | `java.sql.Time`         | `fsp` is fractional seconds precision (0–6).                              |
+| `DATETIME[(fsp)]`   | *none*   | `kotlin.time.Instant`   | Preprocessed from `java.sql.Timestamp`.                                   |
+| `TIMESTAMP[(fsp)]`  | *none*   | `kotlin.time.Instant`   | Preprocessed from `java.sql.Timestamp`.                                   |
+| `YEAR[(4)]`         | *none*   | `java.util.Date`        | 1-byte year (`1901..2155`); driver reports it as `Types.DATE`. Two-digit form `YEAR(2)` was removed in 5.7.5. |
+
+## String types
+
+| Canonical             | Aliases                                                       | DataFrame type       | Notes                                                                    |
+|-----------------------|---------------------------------------------------------------|----------------------|--------------------------------------------------------------------------|
+| `CHAR(M)`             | `CHARACTER(M)`, `NATIONAL CHAR(M)`, `NCHAR(M)`                | `String`             | Fixed-length text. Max `M = 255`.                                        |
+| `VARCHAR(M)`          | `CHARACTER VARYING(M)`, `NATIONAL VARCHAR(M)`, `NVARCHAR(M)`  | `String`             | Variable-length text.                                                    |
+| `BINARY(M)`           | *none*                                                        | `ByteArray`          | Fixed-length binary.                                                     |
+| `VARBINARY(M)`        | `BINARY VARYING(M)`                                           | `ByteArray`          | Variable-length binary.                                                  |
+| `TINYBLOB`            | *none*                                                        | `ByteArray`          | Up to 255 bytes.                                                         |
+| `TINYTEXT`            | *none*                                                        | `String`             | Up to 255 bytes.                                                         |
+| `BLOB[(M)]`           | *none*                                                        | `ByteArray`          | Up to 64 KiB.                                                            |
+| `TEXT[(M)]`           | *none*                                                        | `String`             | Up to 64 KiB.                                                            |
+| `MEDIUMBLOB`          | `LONG VARBINARY`                                              | `ByteArray`          | Up to 16 MiB.                                                            |
+| `MEDIUMTEXT`          | `LONG VARCHAR`, `LONG`                                        | `String`             | Up to 16 MiB.                                                            |
+| `LONGBLOB`            | *none*                                                        | `ByteArray`          | Up to 4 GiB.                                                             |
+| `LONGTEXT`            | *none*                                                        | `String`             | Up to 4 GiB.                                                             |
+| `ENUM(...)`           | *none*                                                        | `String`             | Enumeration; values read as their string form.                           |
+| `SET(...)`            | *none*                                                        | `String`             | Comma-separated set of values, as a single string.                       |
+
+## JSON
+
+| Canonical | Aliases | DataFrame type | Notes                                                                                              |
+|-----------|---------|----------------|----------------------------------------------------------------------------------------------------|
+| `JSON`    | *none*  | `String`       | Validated JSON text. Physically distinct from `LONGTEXT` in MySQL; JDBC still returns it as text. |
+
+## Spatial types
+
+All spatial types are read as `ByteArray` (WKB / EWKB binary as reported by the driver).
+Parse them with a client-side geometry library.
+
+| Canonical            | Aliases | DataFrame type | Notes |
+|----------------------|---------|----------------|-------|
+| `GEOMETRY`           | *none*  | `ByteArray`    |       |
+| `POINT`              | *none*  | `ByteArray`    |       |
+| `LINESTRING`         | *none*  | `ByteArray`    |       |
+| `POLYGON`            | *none*  | `ByteArray`    |       |
+| `MULTIPOINT`         | *none*  | `ByteArray`    |       |
+| `MULTILINESTRING`    | *none*  | `ByteArray`    |       |
+| `MULTIPOLYGON`       | *none*  | `ByteArray`    |       |
+| `GEOMETRYCOLLECTION` | *none*  | `ByteArray`    |       |
+
+## MySQL specifics
+
+- `INT UNSIGNED` and `BIGINT UNSIGNED` are the only types that need MySQL-specific handling.
+  `INT UNSIGNED` is widened to `Long`; `BIGINT UNSIGNED` becomes `BigInteger` because its range
+  exceeds `Long`.
+- The value of `REAL` depends on the [`REAL_AS_FLOAT`](https://dev.mysql.com/doc/refman/8.0/en/sql-mode.html)
+  SQL mode: default `REAL` is `DOUBLE`; with `REAL_AS_FLOAT` set, it's `FLOAT`.
+- Zero-fill and display-width modifiers (e.g. `INT(11)`, `TINYINT ZEROFILL`) do not affect the
+  DataFrame type; MySQL 8.0.17+ ignores them for most numeric types.
+- Unlike MariaDB, MySQL 8.0 does **not** have native `UUID` / `INET4` / `INET6` types; use
+  `CHAR(36)` or `BINARY(16)` and convert client-side.
+
+## Unsupported types
+
+- Native representations of spatial types (they read as raw WKB `ByteArray`).
+- `VECTOR` (MySQL 9.0+); currently read as `ByteArray`.
+- User-defined `TYPE` (rarely used in MySQL).
+
+For explicit support of these, either cast in your query (e.g. `SELECT ST_AsText(geom)`)
+or supply a custom converter via [a custom DbType](readSqlFromCustomDatabase.md).
diff --git a/docs/StardustDocs/topics/readSqlTypeMapping_PostgreSQL.md b/docs/StardustDocs/topics/readSqlTypeMapping_PostgreSQL.md
new file mode 100644
index 0000000000..89bbc6f250
--- /dev/null
+++ b/docs/StardustDocs/topics/readSqlTypeMapping_PostgreSQL.md
@@ -0,0 +1,171 @@
+[//]: # (title: PostgreSQL type mapping)
+
+<web-summary>
+Reference table of how each PostgreSQL column type is mapped to a Kotlin type when read
+into a Kotlin DataFrame.
+</web-summary>
+
+<card-summary>
+How PostgreSQL column types are read into DataFrame.
+</card-summary>
+
+<link-summary>
+Full mapping of PostgreSQL SQL types to Kotlin types, including aliases, PGobject overrides,
+and driver caveats.
+</link-summary>
+
+The tables below list every PostgreSQL column type ([PostgreSQL Data Types](https://www.postgresql.org/docs/current/datatype.html))
+and the Kotlin type produced when the column is read into a DataFrame. Aliases are
+canonicalised by PostgreSQL at `CREATE TABLE` time, so DataFrame only ever sees the canonical
+type; they are listed in the same row as the canonical type for reference.
+
+Nullable columns produce nullable Kotlin types (`Int?` instead of `Int`).
+
+## Numeric types
+
+| Canonical           | Aliases            | DataFrame type          | Notes                                                                                     |
+|---------------------|--------------------|-------------------------|-------------------------------------------------------------------------------------------|
+| `smallint`          | `int2`             | `Int`                   | 2-byte signed integer.                                                                    |
+| `integer`           | `int`, `int4`      | `Int`                   | 4-byte signed integer.                                                                    |
+| `bigint`            | `int8`             | `Long`                  | 8-byte signed integer.                                                                    |
+| `smallserial`       | `serial2`          | `Int`                   | Auto-incrementing `smallint` backed by a sequence.                                        |
+| `serial`            | `serial4`          | `Int`                   | Auto-incrementing `integer`.                                                              |
+| `bigserial`         | `serial8`          | `Long`                  | Auto-incrementing `bigint`.                                                               |
+| `numeric[(p,s)]`    | `decimal[(p,s)]`   | `java.math.BigDecimal`  | Arbitrary-precision decimal.                                                              |
+| `real`              | `float4`           | `Float`                 | 4-byte float.                                                                             |
+| `double precision`  | `float8`           | `Double`                | 8-byte float.                                                                             |
+| `money`             | *none*             | `org.postgresql.util.PGmoney` | PostgreSQL override: read as `PGmoney`.                                             |
+
+## Boolean
+
+| Canonical | Aliases | DataFrame type | Notes |
+|-----------|---------|----------------|-------|
+| `boolean` | `bool`  | `Boolean`      |       |
+
+## Character types
+
+| Canonical            | Aliases                   | DataFrame type | Notes                          |
+|----------------------|---------------------------|----------------|--------------------------------|
+| `character(n)`       | `char(n)`                 | `String`       | Fixed-length text.             |
+| `character varying(n)` | `varchar(n)`            | `String`       | Variable-length text.          |
+| `text`               | *none*                    | `String`       | Unbounded text.                |
+
+## Binary
+
+| Canonical | Aliases | DataFrame type | Notes                                                                       |
+|-----------|---------|----------------|-----------------------------------------------------------------------------|
+| `bytea`   | *none*  | `ByteArray`    | Raw binary. Driver reports it as `[B` (`byte[]`).                           |
+
+## Date and time types
+
+| Canonical                             | Aliases          | DataFrame type              | Notes                                                                     |
+|---------------------------------------|------------------|-----------------------------|---------------------------------------------------------------------------|
+| `date`                                | *none*           | `java.util.Date`            |                                                                           |
+| `time [without time zone] [(p)]`      | *none*           | `java.sql.Time`             | `p` is fractional-second precision (0–6).                                 |
+| `time with time zone [(p)]`           | `timetz`         | `java.time.OffsetTime`      |                                                                           |
+| `timestamp [without time zone] [(p)]` | *none*           | `kotlin.time.Instant`       | Preprocessed from `java.sql.Timestamp`.                                   |
+| `timestamp with time zone [(p)]`      | `timestamptz`    | `java.time.OffsetDateTime`  |                                                                           |
+| `interval [fields] [(p)]`             | *none*           | `org.postgresql.util.PGInterval` | PostgreSQL override.                                                 |
+
+## Geometric types (PostgreSQL overrides)
+
+Case-insensitive `sqlTypeName` lookup selects a PostgreSQL-specific PGobject wrapper.
+
+| Canonical | Aliases | DataFrame type                              | Notes            |
+|-----------|---------|---------------------------------------------|------------------|
+| `box`     | *none*  | `org.postgresql.geometric.PGbox`            | Rectangle        |
+| `circle`  | *none*  | `org.postgresql.geometric.PGcircle`         | Circle           |
+| `line`    | *none*  | `org.postgresql.geometric.PGline`           | Infinite line    |
+| `lseg`    | *none*  | `org.postgresql.geometric.PGlseg`           | Line segment     |
+| `path`    | *none*  | `org.postgresql.geometric.PGpath`           | Open or closed   |
+| `point`   | *none*  | `org.postgresql.geometric.PGpoint`          | 2-D point        |
+| `polygon` | *none*  | `org.postgresql.geometric.PGpolygon`        | Polygon          |
+
+## Bit strings
+
+| Canonical         | Aliases   | DataFrame type | Notes                                                                    |
+|-------------------|-----------|----------------|--------------------------------------------------------------------------|
+| `bit(n)`          | *none*    | `String`       | Reported by the driver as `String` — `"0"` and `"1"` characters.         |
+| `bit varying(n)`  | `varbit`  | `String`       |                                                                          |
+
+## UUID, XML, JSON
+
+| Canonical | Aliases | DataFrame type | Notes                                                                             |
+|-----------|---------|----------------|-----------------------------------------------------------------------------------|
+| `uuid`    | *none*  | `String`       | Read as text by default. Use a client-side parser to get `kotlin.uuid.Uuid`.      |
+| `xml`     | *none*  | `String`       |                                                                                   |
+| `json`    | *none*  | `String`       | Raw JSON text.                                                                    |
+| `jsonb`   | *none*  | `String`       | Binary-stored JSON, read as text.                                                 |
+
+## Network address types
+
+| Canonical    | Aliases | DataFrame type | Notes                                        |
+|--------------|---------|----------------|----------------------------------------------|
+| `inet`       | *none*  | `String`       | IPv4 or IPv6 host / network.                 |
+| `cidr`       | *none*  | `String`       | IPv4 or IPv6 network.                        |
+| `macaddr`    | *none*  | `String`       | MAC address (6 bytes).                       |
+| `macaddr8`   | *none*  | `String`       | MAC address (8 bytes / EUI-64).              |
+
+## Range types
+
+Range types are read as `String` (their canonical `[lo,hi)` text form). Parse client-side.
+
+| Canonical      | Aliases | DataFrame type | Notes                                                             |
+|----------------|---------|----------------|-------------------------------------------------------------------|
+| `int4range`    | *none*  | `String`       |                                                                   |
+| `int8range`    | *none*  | `String`       |                                                                   |
+| `numrange`     | *none*  | `String`       |                                                                   |
+| `tsrange`      | *none*  | `String`       |                                                                   |
+| `tstzrange`    | *none*  | `String`       |                                                                   |
+| `daterange`    | *none*  | `String`       |                                                                   |
+| `int4multirange`, `int8multirange`, `nummultirange`, `tsmultirange`, `tstzmultirange`, `datemultirange` | *none* | `String` | Multi-ranges (PG 14+). Read as text. |
+
+## Full-text search
+
+| Canonical  | Aliases | DataFrame type | Notes                          |
+|------------|---------|----------------|--------------------------------|
+| `tsvector` | *none*  | `String`       | Text search document.          |
+| `tsquery`  | *none*  | `String`       | Text search query.             |
+
+## Object identifiers
+
+| Canonical          | Aliases | DataFrame type | Notes                                              |
+|--------------------|---------|----------------|----------------------------------------------------|
+| `oid`              | *none*  | `Long`         | Underlying storage is 32-bit unsigned integer.     |
+| `regclass`         | *none*  | `String`       | Reported as text alias.                            |
+| `regconfig`, `regdictionary`, `regoper`, `regoperator`, `regproc`, `regprocedure`, `regrole`, `regnamespace`, `regtype`, `regcollation`, `regnamespace`, `regcollation` | *none* | `String` | Various OID aliases. |
+
+## Other
+
+| Canonical            | Aliases   | DataFrame type          | Notes                                                                                                               |
+|----------------------|-----------|-------------------------|---------------------------------------------------------------------------------------------------------------------|
+| `pg_lsn`             | *none*    | `String`                | Write-Ahead Log sequence number.                                                                                    |
+| `pg_snapshot`, `txid_snapshot` | *none* | `String`             | Snapshot info.                                                                                                      |
+| user-defined `ENUM`  | *none*    | `String`                | User-declared enum types are read as their string label.                                                            |
+| user-defined `DOMAIN`| *none*    | as the underlying type  | Domains are transparent; the underlying type's mapping applies.                                                     |
+
+## PostgreSQL specifics
+
+- Type name lookup for PGobject types (`box`, `point`, `money`, ...) is
+  case-insensitive.
+- Composite (row) types like `ROW(a INTEGER, b VARCHAR(10))` are not mapped and read as raw
+  `String` (their canonical text form). See [Unsupported types](#unsupported-types).
+- User-defined `DOMAIN` types are transparent to the driver — the underlying primitive's
+  mapping applies.
+- Auto-incrementing `SERIAL` variants are `INTEGER` / `BIGINT` in the metadata; they are not
+  reported as a separate JDBC type.
+
+## Unsupported types
+
+The following types are not currently mapped to a dedicated Kotlin type; they are read as
+`String` (default fallback) or as the driver's raw form. Explicit support may be added
+later; for now, either cast in your query (e.g. `SELECT ST_AsText(geom)` / `field::text`)
+or supply a custom converter via [a custom DbType](readSqlFromCustomDatabase.md).
+
+- Composite (`ROW(...)`) and user-defined composite types.
+- Array types (`type[]`) — currently read as SQL `ARRAY` and post-processed to `Array<*>`,
+  but element types beyond the primitives listed here are not resolved.
+- `hstore` extension type.
+- PostGIS types (`geometry`, `geography`, ...) from the PostGIS extension.
+- Range / multi-range internal representation (read as text).
+- `bit(n)` / `bit varying(n)` (read as text).
diff --git a/docs/StardustDocs/topics/readSqlTypeMapping_SQLite.md b/docs/StardustDocs/topics/readSqlTypeMapping_SQLite.md
new file mode 100644
index 0000000000..0b306a332d
--- /dev/null
+++ b/docs/StardustDocs/topics/readSqlTypeMapping_SQLite.md
@@ -0,0 +1,176 @@
+[//]: # (title: SQLite type mapping)
+
+<web-summary>
+How SQLite's dynamic type system is mapped to Kotlin types when read into a Kotlin DataFrame,
+including the type-affinity rules DataFrame relies on.
+</web-summary>
+
+<card-summary>
+How SQLite column types are read into DataFrame, including type affinity and dynamic typing.
+</card-summary>
+
+<link-summary>
+Full mapping of SQLite declared types to Kotlin types via affinity, plus DataFrame's SQLite-specific
+overrides.
+</link-summary>
+
+SQLite differs meaningfully from the other JDBC databases: it uses **dynamic typing** and
+has only **5 storage classes** (`NULL`, `INTEGER`, `REAL`, `TEXT`, `BLOB`). The declared
+column type is used only as a hint via
+[type affinity](https://www.sqlite.org/datatype3.html#type_affinity):
+
+| Declared type contains        | Affinity   |
+|-------------------------------|------------|
+| `INT`                         | `INTEGER`  |
+| `CHAR`, `CLOB`, `TEXT`        | `TEXT`     |
+| `BLOB`, or no declared type   | `BLOB`     |
+| `REAL`, `FLOA`, `DOUB`        | `REAL`     |
+| anything else                 | `NUMERIC`  |
+
+**Unlike the other databases in this documentation, SQLite does NOT canonicalize declared
+types.** `sqlTypeName` in the driver's metadata is byte-for-byte what you wrote in
+`CREATE TABLE`. So `INT8`, `INTEGER`, `TINYINT`, `MEDIUMINT`, `UNSIGNED BIG INT` all share
+INTEGER affinity but each keeps its literal declared name. There is no separate alias
+table — every declared name is resolved directly via the affinity tables below.
+
+Because SQLite is dynamically typed, the Xerial JDBC driver reports `getColumnClassName`
+based on the **actual stored value in the current row**, not on the declared column type.
+DataFrame handles the two flavours of SQLite ambiguity differently:
+
+- **`DATE` / `DATETIME` / `TIME` / `TIMESTAMP`** — column type is fixed to an idiomatic Kotlin
+  date-time type (`kotlinx.datetime.LocalDate` / `kotlinx.datetime.LocalDateTime` /
+  `kotlinx.datetime.LocalTime` / `kotlin.time.Instant`); each value is **converted** from
+  its storage class during preprocessing (ISO text → parsed via `LocalDate`/`LocalDateTime`/
+  `Instant.parse`; Unix INTEGER → epoch seconds; Julian REAL → date via the Julian-day formula).
+  This gives one stable Kotlin type per column even when values are stored in mixed forms.
+  `DATE` and `DATETIME` both surface as `Types.DATE` in the driver — they are distinguished by
+  the declared type name.
+- **`DECIMAL` / `NUMERIC`** — no canonical numeric type; DataFrame trusts the storage class of
+  each column (`Double` / `Int` / `Long` / `BigDecimal`, ...).
+
+Nullable columns produce nullable Kotlin types (`Int?` instead of `Int`).
+
+## INTEGER affinity
+
+Declared type contains `INT`.
+
+| Declared type                                     | DataFrame type | Notes                                                                                     |
+|---------------------------------------------------|----------------|-------------------------------------------------------------------------------------------|
+| `INT`                                             | `Int`          |                                                                                           |
+| `INTEGER`                                         | `Int`          | Also used implicitly for `INTEGER PRIMARY KEY` (rowid alias).                             |
+| `TINYINT`                                         | `Int`          |                                                                                           |
+| `SMALLINT`, `INT2`                                | `Int`          |                                                                                           |
+| `MEDIUMINT`                                       | `Int`          |                                                                                           |
+| `BIGINT`, `INT8`, `UNSIGNED BIG INT`              | `Long`         | Xerial reports `Types.BIGINT`; default map returns `Long`.                                |
+
+## REAL affinity
+
+Declared type contains `REAL`, `FLOA`, or `DOUB`.
+
+| Declared type                       | DataFrame type | Notes                                                                                       |
+|-------------------------------------|----------------|---------------------------------------------------------------------------------------------|
+| `REAL`, `FLOAT`                     | `Double`       | Note: not `Float`. Driver reports `java.lang.Double` for the stored value, which triggers the `Types.REAL/FLOAT if java.lang.Double -> Double` override. |
+| `DOUBLE`, `DOUBLE PRECISION`        | `Double`       |                                                                                             |
+
+## TEXT affinity
+
+Declared type contains `CHAR`, `CLOB`, or `TEXT`.
+
+| Declared type                       | DataFrame type   | Notes                                                                                    |
+|-------------------------------------|------------------|------------------------------------------------------------------------------------------|
+| `TEXT`, `VARCHAR(n)`, `NVARCHAR(n)` | `String`         |                                                                                          |
+| `CHAR(n)`, `NCHAR(n)`               | `String`         |                                                                                          |
+| `VARYING CHARACTER(n)`, `NATIVE CHARACTER(n)`, `CHARACTER(n)` | `String` | All fall under TEXT affinity via the `CHAR` substring.                             |
+| `CLOB`                              | `java.sql.Clob`  | Follows the default JDBC mapping; the actual stored value is text.                       |
+
+## BLOB affinity
+
+Declared type contains `BLOB` or the column has no declared type.
+
+| Declared type | DataFrame type | Notes                                              |
+|---------------|----------------|----------------------------------------------------|
+| `BLOB`        | `ByteArray`    |                                                    |
+| *(none)*      | `ByteArray`    | Column with no declared type falls back to BLOB.   |
+
+## NUMERIC affinity (fallback for everything else)
+
+### DATE / DATETIME / TIME / TIMESTAMP — column type is fixed, values are converted
+
+The DataFrame column type is an idiomatic Kotlin date-time type; each row's value is
+converted from its storage class during preprocessing.
+
+| Declared type          | DataFrame type                       | Storage class → conversion                                                                                    |
+|------------------------|--------------------------------------|---------------------------------------------------------------------------------------------------------------|
+| `DATE`                 | `kotlinx.datetime.LocalDate`         | TEXT (ISO `YYYY-MM-DD`) → `LocalDate.parse`; INTEGER → date at Unix-seconds UTC; REAL → date at Julian day. |
+| `DATETIME`             | `kotlinx.datetime.LocalDateTime`     | TEXT (`YYYY-MM-DD HH:MM:SS` or `YYYY-MM-DDTHH:MM:SS`) → `LocalDateTime.parse`; INTEGER → date-time at Unix-seconds UTC; REAL → date-time at Julian day. |
+| `TIME`                 | `kotlinx.datetime.LocalTime`         | TEXT (`HH:MM:SS`) → `LocalTime.parse`; INTEGER → seconds since midnight.                                      |
+| `TIMESTAMP`            | `kotlin.time.Instant`                | TEXT (ISO) → `Instant.parse`; INTEGER → `Instant.fromEpochSeconds` (Unix seconds); REAL → `Instant` at Julian day. |
+
+**Detection is by declared type name, not `jdbcType`.** Xerial changes the reported `jdbcType`
+based on the actual stored value — e.g. a `DATE` column with a Julian-day REAL value is
+reported as `Types.FLOAT`, and a `TIMESTAMP` column with an INTEGER value is reported as
+`Types.INTEGER`. DataFrame's SQLite adapter looks at `sqlTypeName` (substring match: `DATETIME`,
+`TIMESTAMP`, `DATE`, `TIME`) to preserve the intended date-time semantics regardless.
+
+If a value cannot be parsed (e.g. a `DATE` column contains an unexpected format), reading
+throws with a clear error message referencing the column name and stored value. Opt out
+of conversion by supplying a custom mapping, e.g.
+
+```kotlin
+val sqlite = Sqlite(customTypesMap = mapOf("DATETIME" to typeOf<String>()))
+```
+
+### DECIMAL / NUMERIC / BOOLEAN / unknown types — follow the storage class
+
+| Declared type    | Storage class | DataFrame type          | Notes                                                                                     |
+|------------------|---------------|-------------------------|-------------------------------------------------------------------------------------------|
+| `BOOLEAN`        | INTEGER (0/1) | `Boolean`               | Stored as INTEGER but the driver still reports `Types.BOOLEAN`. `Sqlite.getValueFromResultSet` uses `rs.getBoolean` to return a real `Boolean`. |
+| `NUMERIC`        | INTEGER       | `Int` / `Long`          | Follows the actual value's class.                                                         |
+| `NUMERIC`        | REAL          | `Double`                |                                                                                           |
+| `DECIMAL(P,S)`   | REAL          | `Double`                |                                                                                           |
+| `DECIMAL(P,S)`   | INTEGER       | `Int` / `Long`          |                                                                                           |
+| unrecognised type| any           | depends on stored value | E.g. a text value in a `CUSTOM_TYPE` column is reported as `Types.VARCHAR` and read as `String`. |
+
+## STRICT tables
+
+SQLite supports [`STRICT` tables](https://www.sqlite.org/stricttables.html) which enforce a
+limited set of storage class names (`ANY`, `INT`, `INTEGER`, `REAL`, `TEXT`, `BLOB`) and
+reject values of the wrong storage class. In `STRICT` tables the declared type is guaranteed
+to match the storage class, so the affinity tables above still hold — just without the
+ambiguity of ordinary tables. There are no dedicated `BOOLEAN` / `DATE` / `TIMESTAMP`
+storage classes in `STRICT` tables either.
+
+The `ANY` column type accepts any storage class and reports the class of the stored value in
+metadata — DataFrame maps this via the same storage-class rules (`String` / `Int` / `Long` /
+`Double` / `ByteArray`).
+
+## SQLite specifics
+
+- **No canonicalisation** — the driver preserves the declared type verbatim in
+  `sqlTypeName`. Two columns declared `INTEGER` and `TINYINT` both have INTEGER affinity but
+  distinct `sqlTypeName` values in metadata.
+- **`BOOLEAN` requires a workaround.** SQLite has no boolean storage class — values are
+  stored as INTEGER (0/1). Xerial reports the metadata as `Types.BOOLEAN`, but
+  `rs.getObject` returns `Integer`. DataFrame calls `rs.getBoolean` explicitly to convert
+  each value back to a real Kotlin `Boolean`.
+- **`DATE` / `DATETIME` / `TIME` / `TIMESTAMP` are converted from storage class to an idiomatic
+  Kotlin date-time type.** ISO strings, Unix epoch integers, and Julian days are all normalised
+  to `kotlinx.datetime.LocalDate` / `LocalDateTime` / `LocalTime` / `kotlin.time.Instant` in
+  preprocessing. This keeps the schema stable across rows even when values are stored in
+  different formats. Unsupported inputs throw with a message pointing at the column and stored
+  value.
+- **`DECIMAL` and `NUMERIC` follow the actual value's type.** A DECIMAL column with a stored
+  double value becomes `Double`; with a stored integer value it becomes `Int` / `Long`.
+- **Custom overrides** can be supplied via `Sqlite(customTypesMap = ...)` — entries are
+  matched by declared type name (`sqlTypeName`) and take precedence over the built-in mapping:
+
+  ```kotlin
+  val sqlite = Sqlite(customTypesMap = mapOf("MY_TYPE" to typeOf<String>()))
+  ```
+
+## Unsupported types
+
+- SQLite JSON values are simply TEXT — read as `String`. Use client-side parsing.
+- Dates and timestamps are read as raw storage-class values (`String` / `Int` / `Long` /
+  `Double`) — DataFrame does not attempt to parse them into `kotlinx.datetime` types.
+- Client-defined types via SQLite's JSON1 or R*Tree extensions are read as their storage class.

From fbadf7e5bcf8fb74abb4af30144adbaa9f57d1ce Mon Sep 17 00:00:00 2001
From: "andrei.kislitsyn" <kisandy@yandex.ru>
Date: Fri, 24 Jul 2026 17:00:55 +0400
Subject: [PATCH 02/10] Remove `SqliteMetadataProbe` test code for
 investigation purposes

---
 .../kotlinx/dataframe/io/db/_sqliteProbe.kt   | 129 ------------------
 1 file changed, 129 deletions(-)
 delete mode 100644 dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/_sqliteProbe.kt

diff --git a/dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/_sqliteProbe.kt b/dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/_sqliteProbe.kt
deleted file mode 100644
index e84e1b3ebe..0000000000
--- a/dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/_sqliteProbe.kt
+++ /dev/null
@@ -1,129 +0,0 @@
-package org.jetbrains.kotlinx.dataframe.io.db
-
-import org.junit.Ignore
-import org.junit.Test
-import java.io.File
-import java.nio.file.Files
-import java.sql.DriverManager
-import java.sql.Types
-
-/**
- * Probe used to figure out what the Xerial SQLite JDBC driver reports in the metadata
- * for common declared column types (SQLite type affinity is applied at storage level, but
- * the driver preserves the declared type name in `sqlTypeName`).
- *
- * Not part of the regular suite; enable ad-hoc if you need to refresh the mapping.
- */
-@Ignore("Investigation probe — not a real test")
-class SqliteMetadataProbe {
-
-    @Test
-    fun `dump getObject class vs metadata jdbcType for problematic types`() {
-        val file = Files.createTempFile("dataframe_sqlite_probe2_", ".db").toFile()
-        file.deleteOnExit()
-        val url = "jdbc:sqlite:${file.absolutePath}"
-
-        // (declaredType, sql-literal, description)
-        val cases = listOf(
-            Triple("BOOLEAN", "1", "boolean-as-int"),
-            Triple("BOOLEAN", "0", "boolean-as-int-false"),
-            Triple("DATE", "'2020-01-15'", "date-as-iso-text"),
-            Triple("DATE", "1579046400", "date-as-unix-int"),
-            Triple("DATETIME", "'2020-01-15 10:30:00'", "datetime-as-iso-text"),
-            Triple("TIMESTAMP", "'2020-01-15T10:30:00Z'", "timestamp-as-iso-text"),
-            Triple("TIMESTAMP", "1579083000", "timestamp-as-unix-int"),
-            Triple("NUMERIC", "1.5", "numeric-as-real"),
-            Triple("NUMERIC", "42", "numeric-as-int"),
-            Triple("DECIMAL(10,5)", "1.5", "decimal-as-real"),
-            Triple("DATE", "2460146.5", "date-as-julian-real"),
-            Triple("TIMESTAMP", "2460146.5", "timestamp-as-julian-real"),
-        )
-
-        DriverManager.getConnection(url).use { conn ->
-            cases.forEachIndexed { i, (decl, literal, _) ->
-                conn.createStatement().execute("CREATE TABLE t$i (col $decl)")
-                conn.createStatement().execute("INSERT INTO t$i (col) VALUES ($literal)")
-            }
-            for ((i, case) in cases.withIndex()) {
-                val (decl, literal, desc) = case
-                conn.prepareStatement("SELECT col FROM t$i").executeQuery().use { rs ->
-                    val md = rs.metaData
-                    val jdbc = md.getColumnType(1)
-                    val jdbcName = jdbcName(jdbc)
-                    val cls = md.getColumnClassName(1)
-                    rs.next()
-                    val got = rs.getObject(1)
-                    val gotClass = got?.javaClass?.name
-                    println(
-                        "%-25s declared=%-14s literal=%-24s meta.jdbc=%-9s meta.class=%-22s getObject.class=%s value=%s".format(
-                            desc, decl, literal, jdbcName, cls, gotClass, got,
-                        ),
-                    )
-                }
-            }
-        }
-        file.delete()
-    }
-
-    @Test
-    fun `dump metadata for common declared types`() {
-        val file = Files.createTempFile("dataframe_sqlite_probe_", ".db").toFile()
-        file.deleteOnExit()
-        val url = "jdbc:sqlite:${file.absolutePath}"
-
-        val declaredTypes = listOf(
-            "INTEGER", "INT", "TINYINT", "SMALLINT", "MEDIUMINT", "BIGINT", "UNSIGNED BIG INT",
-            "INT2", "INT8",
-            "REAL", "DOUBLE", "DOUBLE PRECISION", "FLOAT",
-            "NUMERIC", "DECIMAL(10,5)",
-            "BOOLEAN",
-            "DATE", "DATETIME", "TIMESTAMP",
-            "TEXT", "VARCHAR(255)", "CHAR(10)", "CLOB", "NVARCHAR(10)", "NCHAR(10)",
-            "BLOB",
-            "",           // no declared type
-            "CUSTOM_TYPE", // unknown → NUMERIC affinity
-        )
-
-        DriverManager.getConnection(url).use { conn ->
-            declaredTypes.forEachIndexed { i, decl ->
-                val col = "col$i ${if (decl.isEmpty()) "" else decl}".trim()
-                conn.createStatement().execute("CREATE TABLE t$i ($col)")
-                // Insert one representative value so the driver can infer the actual storage class.
-                conn.createStatement().execute("INSERT INTO t$i (col$i) VALUES (${sampleValueFor(decl)})")
-            }
-            for ((i, decl) in declaredTypes.withIndex()) {
-                conn.prepareStatement("SELECT col$i FROM t$i").executeQuery().use { rs ->
-                    val md = rs.metaData
-                    val jdbc = md.getColumnType(1)
-                    val jdbcName = jdbcName(jdbc)
-                    val typeName = md.getColumnTypeName(1)
-                    val cls = md.getColumnClassName(1)
-                    println(
-                        "declared=%-24s -> sqlTypeName=%-16s jdbcType=%-8s (%s) classNm=%s".format(
-                            "\"$decl\"", typeName, jdbc.toString(), jdbcName, cls,
-                        ),
-                    )
-                }
-            }
-        }
-        file.delete()
-    }
-
-    private fun jdbcName(t: Int): String =
-        Types::class.java.fields.firstOrNull { it.getInt(null) == t }?.name ?: "?"
-
-    private fun sampleValueFor(decl: String): String {
-        val u = decl.uppercase()
-        return when {
-            u.contains("BLOB") -> "x'00'"
-            u.contains("BOOLEAN") -> "1"
-            u.contains("DATE") || u.contains("TIMESTAMP") || u.contains("TIME") -> "'2020-01-01'"
-            u.contains("CHAR") || u.contains("TEXT") || u.contains("CLOB") -> "'x'"
-            u.contains("REAL") || u.contains("DOUB") || u.contains("FLOA") ||
-                u.contains("NUMERIC") || u.contains("DECIMAL") -> "1.5"
-            u.contains("INT") -> "1"
-            u.isEmpty() -> "1"
-            else -> "'x'"
-        }
-    }
-}

From f308cd5770086dd52ca7841d13bb0efc051ac839 Mon Sep 17 00:00:00 2001
From: "andrei.kislitsyn" <kisandy@yandex.ru>
Date: Tue, 28 Jul 2026 14:14:03 +0400
Subject: [PATCH 03/10] updated sqlite usage

---
 .../jetbrains/kotlinx/dataframe/io/db/jdbcTypesTest.kt | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/jdbcTypesTest.kt b/dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/jdbcTypesTest.kt
index 2b86bd102c..e483216da3 100644
--- a/dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/jdbcTypesTest.kt
+++ b/dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/jdbcTypesTest.kt
@@ -222,12 +222,10 @@ class JdbcTypesTest {
 
         @Test
         fun `customTypesMap overrides the default mapping by SQL type name`() {
-            val custom = Sqlite(
-                customTypesMap = mapOf(
-                    "INTEGER" to typeOf<Long>(),
-                    "MY_TYPE" to typeOf<String>(),
-                ),
-            )
+            val custom = Sqlite.withCustomConverters {
+                forType<Long>("INTEGER")
+                forType<String>("MY_TYPE")
+            }
             // INTEGER is normally Int, but is overridden to Long
             custom.getExpectedJdbcType(
                 createColumnMetadata(

From d0f70c5314e8ca919218f0708f13fee335957c7c Mon Sep 17 00:00:00 2001
From: "andrei.kislitsyn" <kisandy@yandex.ru>
Date: Fri, 7 Aug 2026 16:31:57 +0400
Subject: [PATCH 04/10] SQLite types tests and docs update

---
 .../kotlinx/dataframe/io/db/jdbcTypesTest.kt  |  84 +++++------
 .../StardustDocs/topics/readSqlTypeMapping.md |   2 +-
 .../topics/readSqlTypeMapping_SQLite.md       | 134 +++++++++++++-----
 3 files changed, 133 insertions(+), 87 deletions(-)

diff --git a/dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/jdbcTypesTest.kt b/dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/jdbcTypesTest.kt
index e483216da3..365cd81b0b 100644
--- a/dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/jdbcTypesTest.kt
+++ b/dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/jdbcTypesTest.kt
@@ -56,8 +56,7 @@ class JdbcTypesTest {
 
             override fun isSystemTable(tableMetadata: TableMetadata): Boolean = false
 
-            override fun buildTableMetadata(tables: java.sql.ResultSet): TableMetadata =
-                TableMetadata("t", null, null)
+            override fun buildTableMetadata(tables: java.sql.ResultSet): TableMetadata = TableMetadata("t", null, null)
         }
 
         @Test
@@ -184,26 +183,16 @@ class JdbcTypesTest {
 
         @Test
         fun `BOOLEAN declared type resolves to Boolean`() {
-            // Xerial reports Types.BOOLEAN metadata even though values are stored as INTEGER;
-            // the schema type is Boolean, and `getValueFromResultSet` converts each row via
-            // `rs.getBoolean` (see Sqlite.getValueFromResultSet).
-            Sqlite.default.getExpectedJdbcType(
-                createColumnMetadata(
-                    sqlTypeName = "BOOLEAN",
-                    jdbcType = Types.BOOLEAN,
-                    javaClassName = "java.lang.Integer",
-                    isNullable = false,
-                ),
-            ) shouldBe typeOf<Boolean>()
-
-            Sqlite.default.getExpectedJdbcType(
-                createColumnMetadata(
-                    sqlTypeName = "BOOLEAN",
-                    jdbcType = Types.BOOLEAN,
-                    javaClassName = "java.lang.Integer",
-                    isNullable = true,
+            // SQLite has no native boolean storage — values are kept as INTEGER (0/1). The Xerial
+            // driver still reports Types.BOOLEAN in metadata, but `rs.getObject` returns Integer.
+            // The final DataFrame column type is `Boolean`, produced by a preprocessor that runs
+            // `convertToBoolean` on each raw value (see `generateConverter`).
+            assertMappings(
+                Sqlite.default,
+                listOf(
+                    TypeMapping("BOOLEAN", Types.BOOLEAN, "java.lang.Integer", typeOf<Boolean>()),
                 ),
-            ) shouldBe typeOf<Boolean?>()
+            )
         }
 
         @Test
@@ -221,29 +210,32 @@ class JdbcTypesTest {
         }
 
         @Test
-        fun `customTypesMap overrides the default mapping by SQL type name`() {
+        fun `custom type mapping overrides the default mapping by SQL type name`() {
+            // The identity `forType<T>(name)` overload pins the resulting DataFrame column type
+            // to `T`. Nullability is part of `T` (there is no implicit widening from the column's
+            // isNullable metadata) — declare `T` as nullable explicitly if you want nullable.
             val custom = Sqlite.withCustomConverters {
-                forType<Long>("INTEGER")
+                forType<Long?>("INTEGER")
                 forType<String>("MY_TYPE")
             }
-            // INTEGER is normally Int, but is overridden to Long
-            custom.getExpectedJdbcType(
-                createColumnMetadata(
+            // INTEGER is normally Int, but is overridden to Long? — regardless of column nullability.
+            listOf(false, true).forEach { isNullable ->
+                val meta = createColumnMetadata(
                     sqlTypeName = "INTEGER",
                     jdbcType = Types.INTEGER,
                     javaClassName = "java.lang.Integer",
-                    isNullable = true,
-                ),
-            ) shouldBe typeOf<Long?>()
-            // Custom type name is respected as-is
-            custom.getExpectedJdbcType(
-                createColumnMetadata(
-                    sqlTypeName = "MY_TYPE",
-                    jdbcType = Types.OTHER,
-                    javaClassName = "java.lang.Object",
-                    isNullable = false,
-                ),
-            ) shouldBe typeOf<String>()
+                    isNullable = isNullable,
+                )
+                custom.getPreprocessedValueType(meta, custom.getExpectedJdbcType(meta)) shouldBe typeOf<Long?>()
+            }
+            // Custom type name is respected as-is: `MY_TYPE` -> String
+            val meta = createColumnMetadata(
+                sqlTypeName = "MY_TYPE",
+                jdbcType = Types.OTHER,
+                javaClassName = "java.lang.Object",
+                isNullable = false,
+            )
+            custom.getPreprocessedValueType(meta, custom.getExpectedJdbcType(meta)) shouldBe typeOf<String>()
         }
 
         @Test
@@ -566,22 +558,18 @@ internal val sqliteNumericAffinityMappings: List<TypeMapping> = listOf(
     TypeMapping("NUMERIC", Types.NUMERIC, "java.lang.Double", typeOf<Double>()),
     TypeMapping("NUMERIC", Types.NUMERIC, "java.lang.Integer", typeOf<Int>()),
     TypeMapping("DECIMAL", Types.DECIMAL, "java.lang.Double", typeOf<Double>()),
-
     // DATE with all three storage classes:
-    TypeMapping("DATE", Types.DATE, "java.lang.String", typeOf<KotlinLocalDate>()),    // TEXT (ISO)
-    TypeMapping("DATE", Types.DATE, "java.lang.Integer", typeOf<KotlinLocalDate>()),   // INTEGER (Unix)
-    TypeMapping("DATE", Types.FLOAT, "java.lang.Double", typeOf<KotlinLocalDate>()),   // REAL (Julian day)
-
+    TypeMapping("DATE", Types.DATE, "java.lang.String", typeOf<KotlinLocalDate>()), // TEXT (ISO)
+    TypeMapping("DATE", Types.DATE, "java.lang.Integer", typeOf<KotlinLocalDate>()), // INTEGER (Unix)
+    TypeMapping("DATE", Types.FLOAT, "java.lang.Double", typeOf<KotlinLocalDate>()), // REAL (Julian day)
     // DATETIME variants:
     TypeMapping("DATETIME", Types.DATE, "java.lang.String", typeOf<KotlinLocalDateTime>()),
     TypeMapping("DATETIME", Types.DATE, "java.lang.Integer", typeOf<KotlinLocalDateTime>()),
-
     // TIME variants:
     TypeMapping("TIME", Types.TIME, "java.lang.String", typeOf<KotlinLocalTime>()),
     TypeMapping("TIME", Types.INTEGER, "java.lang.Integer", typeOf<KotlinLocalTime>()),
-
     // TIMESTAMP with all three storage classes:
-    TypeMapping("TIMESTAMP", Types.TIMESTAMP, "java.lang.String", typeOf<Instant>()),   // TEXT (ISO)
-    TypeMapping("TIMESTAMP", Types.TIMESTAMP, "java.lang.Integer", typeOf<Instant>()),  // INTEGER (Unix)
-    TypeMapping("TIMESTAMP", Types.FLOAT, "java.lang.Double", typeOf<Instant>()),       // REAL (Julian day)
+    TypeMapping("TIMESTAMP", Types.TIMESTAMP, "java.lang.String", typeOf<Instant>()), // TEXT (ISO)
+    TypeMapping("TIMESTAMP", Types.TIMESTAMP, "java.lang.Integer", typeOf<Instant>()), // INTEGER (Unix)
+    TypeMapping("TIMESTAMP", Types.FLOAT, "java.lang.Double", typeOf<Instant>()), // REAL (Julian day)
 )
diff --git a/docs/StardustDocs/topics/readSqlTypeMapping.md b/docs/StardustDocs/topics/readSqlTypeMapping.md
index 3f48df57c5..082e731585 100644
--- a/docs/StardustDocs/topics/readSqlTypeMapping.md
+++ b/docs/StardustDocs/topics/readSqlTypeMapping.md
@@ -45,7 +45,7 @@ the canonical type.
 | [PostgreSQL](readSqlTypeMapping_PostgreSQL.md)               | Default `DbType` + `PGobject` overrides (`box`, `point`, `money`, ...).     |
 | [MS SQL Server](readSqlTypeMapping_MsSql.md)                 | Default `DbType`, no overrides.                                             |
 | [H2](readSqlTypeMapping_H2.md)                               | Default `DbType` in `Regular` mode; other modes delegate to another dialect.|
-| [SQLite](readSqlTypeMapping_SQLite.md)                       | Custom: type affinity resolves declared types dynamically.                  |
+| [SQLite](readSqlTypeMapping_SQLite.md)                       | Custom: type affinity + per-storage-class conversion for `BOOLEAN`/`DATE`/`DATETIME`/`TIME`/`TIMESTAMP`. |
 | [DuckDB](readSqlTypeMapping_DuckDB.md)                       | Bypasses `getExpectedJdbcType`; uses its own converter.                     |
 
 ## Extending the mapping
diff --git a/docs/StardustDocs/topics/readSqlTypeMapping_SQLite.md b/docs/StardustDocs/topics/readSqlTypeMapping_SQLite.md
index 0b306a332d..f4363daa85 100644
--- a/docs/StardustDocs/topics/readSqlTypeMapping_SQLite.md
+++ b/docs/StardustDocs/topics/readSqlTypeMapping_SQLite.md
@@ -34,19 +34,28 @@ INTEGER affinity but each keeps its literal declared name. There is no separate
 table — every declared name is resolved directly via the affinity tables below.
 
 Because SQLite is dynamically typed, the Xerial JDBC driver reports `getColumnClassName`
-based on the **actual stored value in the current row**, not on the declared column type.
-DataFrame handles the two flavours of SQLite ambiguity differently:
-
-- **`DATE` / `DATETIME` / `TIME` / `TIMESTAMP`** — column type is fixed to an idiomatic Kotlin
-  date-time type (`kotlinx.datetime.LocalDate` / `kotlinx.datetime.LocalDateTime` /
-  `kotlinx.datetime.LocalTime` / `kotlin.time.Instant`); each value is **converted** from
-  its storage class during preprocessing (ISO text → parsed via `LocalDate`/`LocalDateTime`/
-  `Instant.parse`; Unix INTEGER → epoch seconds; Julian REAL → date via the Julian-day formula).
-  This gives one stable Kotlin type per column even when values are stored in mixed forms.
-  `DATE` and `DATETIME` both surface as `Types.DATE` in the driver — they are distinguished by
-  the declared type name.
-- **`DECIMAL` / `NUMERIC`** — no canonical numeric type; DataFrame trusts the storage class of
-  each column (`Double` / `Int` / `Long` / `BigDecimal`, ...).
+based on the **actual stored value in the current row**, not on the declared column type. The
+raw values returned by `rs.getObject(int)` therefore fall into a fixed set — Xerial produces
+exactly one of `Integer` / `Long` / `Double` / `String` / `byte[]` / `null`, chosen per row
+from the storage class of that value.
+
+DataFrame's SQLite handler resolves each column in the following order:
+
+1. **User-supplied [custom converters](#custom-converters)** (by column name, then by declared
+   type name) always win.
+2. **`DATE` / `DATETIME` / `TIME` / `TIMESTAMP`** — detected by a substring match on the declared
+   type name. Column type is fixed to an idiomatic Kotlin date-time type
+   (`kotlinx.datetime.LocalDate` / `LocalDateTime` / `LocalTime` / `kotlin.time.Instant`); each
+   value is **converted** from its storage class during preprocessing (ISO text → parsed via
+   `LocalDate`/`LocalDateTime`/`Instant.parse`; Unix INTEGER → epoch seconds; Julian REAL → date
+   via the Julian-day formula). This gives one stable Kotlin type per column even when values
+   are stored in mixed forms.
+3. **`BOOLEAN` / `BIT`** — Xerial reports `Types.BOOLEAN` but `rs.getObject` returns Integer
+   (0/1). A preprocessor converts every raw value (Int, Long, Double, or `"true"`/`"1"`/`"y"`
+   String) to a real Kotlin `Boolean`.
+4. **`DECIMAL` / `NUMERIC`** — no canonical numeric type; DataFrame trusts the driver-reported
+   class of each column (`Int` / `Long` / `Double` / `ByteArray` / `String`).
+5. **Everything else** falls through to the base `DbType` end-to-end mapping.
 
 Nullable columns produce nullable Kotlin types (`Int?` instead of `Int`).
 
@@ -103,7 +112,7 @@ converted from its storage class during preprocessing.
 |------------------------|--------------------------------------|---------------------------------------------------------------------------------------------------------------|
 | `DATE`                 | `kotlinx.datetime.LocalDate`         | TEXT (ISO `YYYY-MM-DD`) → `LocalDate.parse`; INTEGER → date at Unix-seconds UTC; REAL → date at Julian day. |
 | `DATETIME`             | `kotlinx.datetime.LocalDateTime`     | TEXT (`YYYY-MM-DD HH:MM:SS` or `YYYY-MM-DDTHH:MM:SS`) → `LocalDateTime.parse`; INTEGER → date-time at Unix-seconds UTC; REAL → date-time at Julian day. |
-| `TIME`                 | `kotlinx.datetime.LocalTime`         | TEXT (`HH:MM:SS`) → `LocalTime.parse`; INTEGER → seconds since midnight.                                      |
+| `TIME`                 | `kotlinx.datetime.LocalTime`         | TEXT (`HH:MM:SS` or `HH:MM:SS.SSS`) → `LocalTime.parse`; INTEGER → seconds since midnight; REAL → seconds since midnight (fractional part ignored). |
 | `TIMESTAMP`            | `kotlin.time.Instant`                | TEXT (ISO) → `Instant.parse`; INTEGER → `Instant.fromEpochSeconds` (Unix seconds); REAL → `Instant` at Julian day. |
 
 **Detection is by declared type name, not `jdbcType`.** Xerial changes the reported `jdbcType`
@@ -114,22 +123,37 @@ reported as `Types.FLOAT`, and a `TIMESTAMP` column with an INTEGER value is rep
 
 If a value cannot be parsed (e.g. a `DATE` column contains an unexpected format), reading
 throws with a clear error message referencing the column name and stored value. Opt out
-of conversion by supplying a custom mapping, e.g.
+of conversion by supplying a [custom converter](#custom-converters), e.g.
 
 ```kotlin
-val sqlite = Sqlite(customTypesMap = mapOf("DATETIME" to typeOf<String>()))
+val sqlite = Sqlite.withCustomConverters {
+    // Pin DATETIME columns to raw String — skip the built-in LocalDateTime conversion.
+    forType<String?>("DATETIME")
+}
 ```
 
-### DECIMAL / NUMERIC / BOOLEAN / unknown types — follow the storage class
+### BOOLEAN — INTEGER 0/1 converted to Boolean
 
-| Declared type    | Storage class | DataFrame type          | Notes                                                                                     |
-|------------------|---------------|-------------------------|-------------------------------------------------------------------------------------------|
-| `BOOLEAN`        | INTEGER (0/1) | `Boolean`               | Stored as INTEGER but the driver still reports `Types.BOOLEAN`. `Sqlite.getValueFromResultSet` uses `rs.getBoolean` to return a real `Boolean`. |
-| `NUMERIC`        | INTEGER       | `Int` / `Long`          | Follows the actual value's class.                                                         |
-| `NUMERIC`        | REAL          | `Double`                |                                                                                           |
-| `DECIMAL(P,S)`   | REAL          | `Double`                |                                                                                           |
-| `DECIMAL(P,S)`   | INTEGER       | `Int` / `Long`          |                                                                                           |
-| unrecognised type| any           | depends on stored value | E.g. a text value in a `CUSTOM_TYPE` column is reported as `Types.VARCHAR` and read as `String`. |
+| Declared type    | Storage class     | DataFrame type | Notes                                                                                                                              |
+|------------------|-------------------|----------------|------------------------------------------------------------------------------------------------------------------------------------|
+| `BOOLEAN`, `BIT` | INTEGER (0/1)     | `Boolean`      | The preprocessor treats non-zero as `true`, zero as `false`.                                                                        |
+| `BOOLEAN`, `BIT` | REAL              | `Boolean`      | Same convention (non-zero → `true`).                                                                                                |
+| `BOOLEAN`, `BIT` | TEXT              | `Boolean`      | Case-insensitively accepts `true`/`1`/`yes`/`y`/`t` → `true` and `false`/`0`/`no`/`n`/`f` → `false`. Unrecognised text throws.        |
+
+`BOOL`/`BIT` substring in the declared name is also caught (e.g. columns declared `IS_ACTIVE_BOOL`).
+
+### DECIMAL / NUMERIC — follow the storage class
+
+`DECIMAL` and `NUMERIC` columns have no canonical numeric type; DataFrame reads the raw stored
+value as-is (`Int`, `Long`, or `Double` depending on how each row was inserted).
+
+| Declared type    | Storage class | DataFrame type          | Notes                                            |
+|------------------|---------------|-------------------------|--------------------------------------------------|
+| `NUMERIC`        | INTEGER       | `Int` / `Long`          | Follows the actual value's class.                |
+| `NUMERIC`        | REAL          | `Double`                |                                                  |
+| `DECIMAL(P,S)`   | REAL          | `Double`                |                                                  |
+| `DECIMAL(P,S)`   | INTEGER       | `Int` / `Long`          |                                                  |
+| unrecognised type| any           | depends on stored value | E.g. a text value in a `CUSTOM_TYPE` column is reported as `Types.VARCHAR` and read as `String`. Use a [custom converter](#custom-converters) to pin a specific type. |
 
 ## STRICT tables
 
@@ -144,33 +168,67 @@ The `ANY` column type accepts any storage class and reports the class of the sto
 metadata — DataFrame maps this via the same storage-class rules (`String` / `Int` / `Long` /
 `Double` / `ByteArray`).
 
+## Custom converters
+
+Use `Sqlite.withCustomConverters { ... }` to register per-column or per-declared-type overrides.
+Column-name overrides win over type-name overrides.
+
+Two overloads are available for each side:
+
+- **Converter form** — `forType<T, R>(name) { raw -> ... }` / `forColumn<T, R>(name) { raw -> ... }`.
+  A lambda transforms each raw stored value; the DataFrame column's Kotlin type is derived from
+  the reified `R` via `typeOf<R>()`.
+- **Identity form** — `forType<T>(name)` / `forColumn<T>(name)`. No transformation — values pass
+  through as `T`. Handy when SQLite's type affinity misclassifies your column and the built-in
+  mapping picks the wrong Kotlin type. Note: **nullability is part of `T`** — declare it
+  explicitly (`forType<Long?>("BIGINT")`) if you want a nullable column type.
+
+```kotlin
+val format = LocalDateTime.Format {
+    year(); char('-'); monthNumber(); char('-'); day()
+    char(' ')
+    hour(); char(':'); minute(); char(':'); second()
+    chars(" UTC")
+}
+
+val sqlite = Sqlite.withCustomConverters {
+    // Parse a proprietary text format into Instant.
+    forType("MY_DATETIME") { raw: String? ->
+        raw?.let { LocalDateTime.parse(it, format).toInstant(TimeZone.UTC) }
+    }
+    // Pin LONGVARCHAR to String? even though SQLite affinity says NUMERIC.
+    forType<String?>("LONGVARCHAR")
+    // Override a specific column by name — this wins over any type-name override.
+    forColumn("ratio") { raw: String -> raw.toDouble() }
+}
+
+val df = DataFrame.readSqlTable(connection, "events", dbType = sqlite)
+```
+
 ## SQLite specifics
 
 - **No canonicalisation** — the driver preserves the declared type verbatim in
   `sqlTypeName`. Two columns declared `INTEGER` and `TINYINT` both have INTEGER affinity but
   distinct `sqlTypeName` values in metadata.
-- **`BOOLEAN` requires a workaround.** SQLite has no boolean storage class — values are
-  stored as INTEGER (0/1). Xerial reports the metadata as `Types.BOOLEAN`, but
-  `rs.getObject` returns `Integer`. DataFrame calls `rs.getBoolean` explicitly to convert
-  each value back to a real Kotlin `Boolean`.
+- **Xerial's `rs.getObject(int)` returns exactly one of `Integer` / `Long` / `Double` /
+  `String` / `byte[]` / `null`.** No `Timestamp` / `LocalDate` / `Boolean` / `Blob` ever
+  reaches DataFrame from a SQLite driver — hence the SQLite adapter needs to translate.
 - **`DATE` / `DATETIME` / `TIME` / `TIMESTAMP` are converted from storage class to an idiomatic
   Kotlin date-time type.** ISO strings, Unix epoch integers, and Julian days are all normalised
   to `kotlinx.datetime.LocalDate` / `LocalDateTime` / `LocalTime` / `kotlin.time.Instant` in
   preprocessing. This keeps the schema stable across rows even when values are stored in
   different formats. Unsupported inputs throw with a message pointing at the column and stored
-  value.
+  value and suggesting `Sqlite.withCustomConverters { }` as the escape hatch.
+- **`BOOLEAN` and `BIT` are converted to Boolean.** SQLite has no boolean storage class —
+  values are stored as INTEGER (0/1). The preprocessor converts every raw value (Int, Long,
+  Double, or textual `true`/`false`/`yes`/`no`) back to a real Kotlin `Boolean`.
 - **`DECIMAL` and `NUMERIC` follow the actual value's type.** A DECIMAL column with a stored
   double value becomes `Double`; with a stored integer value it becomes `Int` / `Long`.
-- **Custom overrides** can be supplied via `Sqlite(customTypesMap = ...)` — entries are
-  matched by declared type name (`sqlTypeName`) and take precedence over the built-in mapping:
-
-  ```kotlin
-  val sqlite = Sqlite(customTypesMap = mapOf("MY_TYPE" to typeOf<String>()))
-  ```
+- **Custom overrides** are registered via `Sqlite.withCustomConverters { ... }`. See the
+  [Custom converters](#custom-converters) section above.
 
 ## Unsupported types
 
 - SQLite JSON values are simply TEXT — read as `String`. Use client-side parsing.
-- Dates and timestamps are read as raw storage-class values (`String` / `Int` / `Long` /
-  `Double`) — DataFrame does not attempt to parse them into `kotlinx.datetime` types.
 - Client-defined types via SQLite's JSON1 or R*Tree extensions are read as their storage class.
+  Use a [custom converter](#custom-converters) to translate to a domain type.

From b1eed7ce419d7d00c7bdf84b001423cc0468a7f7 Mon Sep 17 00:00:00 2001
From: "andrei.kislitsyn" <kisandy@yandex.ru>
Date: Tue, 18 Aug 2026 14:25:45 +0400
Subject: [PATCH 05/10] Add examples for resolving SQLite type issues in
 troubleshooting docs

---
 ...a-Schemas-And-Extension-Properties-Troubleshooting.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/docs/StardustDocs/topics/schemas/Data-Schemas-And-Extension-Properties-Troubleshooting.md b/docs/StardustDocs/topics/schemas/Data-Schemas-And-Extension-Properties-Troubleshooting.md
index ab0c5bc1f8..6447b6954e 100644
--- a/docs/StardustDocs/topics/schemas/Data-Schemas-And-Extension-Properties-Troubleshooting.md
+++ b/docs/StardustDocs/topics/schemas/Data-Schemas-And-Extension-Properties-Troubleshooting.md
@@ -113,6 +113,15 @@ You can explicitly specify the resulting Kotlin type using the `Sqlite.withCusto
 - `forType<T>(typeName)` sets the `T` Kotlin type for all columns declared with the specified SQL type.
 - `forColumn(...) { ... }` and `forType(...) { ... }` additionally let you transform the raw stored value.
 
+For example:
+- You have a `LONGVARCHAR` column containing text (i.e., `String` or `String?` values).
+  However, SQLite type affinity assigns it the `INTEGER` basic type, so the JDBC driver expects
+  `Int` or `Long` values. Use `forType<String?>("LONGVARCHAR")` to explicitly specify the expected column type.
+- You have several columns of the `DATETIME` type. They are stored as `TEXT`, and Kotlin DataFrame
+  can automatically parse their values into date-time types. However, suppose the `time_stamp` column
+  contains date-time values in an unusual format. Automatic parsing fails and causes an exception.
+  Use `forColumn("time_stamp") { ... }` to provide a custom converter specifically for this column.
+
 <!---FUN readSqliteCustom-->
 
 ```kotlin

From b5658d0ac5e49830103427882352c65ac62db65c Mon Sep 17 00:00:00 2001
From: "andrei.kislitsyn" <kisandy@yandex.ru>
Date: Tue, 18 Aug 2026 14:26:01 +0400
Subject: [PATCH 06/10] Clarify test documentation for JDBC type mapping logic

---
 .../org/jetbrains/kotlinx/dataframe/io/db/jdbcTypesTest.kt | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/jdbcTypesTest.kt b/dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/jdbcTypesTest.kt
index 365cd81b0b..1795b10b5d 100644
--- a/dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/jdbcTypesTest.kt
+++ b/dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/jdbcTypesTest.kt
@@ -38,12 +38,13 @@ import kotlinx.datetime.LocalDateTime as KotlinLocalDateTime
 import kotlinx.datetime.LocalTime as KotlinLocalTime
 
 /**
- * Non-integration tests for [DbType.getExpectedJdbcType] and related type-mapping logic.
+ * Tests for [DbType.getExpectedJdbcType] and related type-mapping logic.
+ *
+ * For each DB type implemented in Kotlin Dataframe, checks mapping between the SQL type and the expected type
+ * for a [org.jetbrains.kotlinx.dataframe.DataFrame] [column][org.jetbrains.kotlinx.dataframe.DataColumn].
  *
  * Each DB owns a [TypeMapping] list that acts as the source of truth for its SQL → Kotlin type
  * mapping. The list is exercised for both nullable and non-nullable columns.
- *
- * See https://github.com/Kotlin/dataframe/issues/1736.
  */
 @RunWith(Enclosed::class)
 class JdbcTypesTest {

From fa70221b21220e061f461a99a29a4e0ab81dfc1f Mon Sep 17 00:00:00 2001
From: "andrei.kislitsyn" <kisandy@yandex.ru>
Date: Tue, 18 Aug 2026 17:28:45 +0400
Subject: [PATCH 07/10] Expand JDBC type mapping docs with SQLite and DuckDB
 examples, add details on `AdvancedDbType` and custom converters.

---
 .../topics/readSqlFromCustomDatabase.md       | 11 +++++-
 .../StardustDocs/topics/readSqlTypeMapping.md | 34 ++++++++++++-------
 ...nd-Extension-Properties-Troubleshooting.md |  4 +--
 3 files changed, 33 insertions(+), 16 deletions(-)

diff --git a/docs/StardustDocs/topics/readSqlFromCustomDatabase.md b/docs/StardustDocs/topics/readSqlFromCustomDatabase.md
index 09626c202b..7673d0c667 100644
--- a/docs/StardustDocs/topics/readSqlFromCustomDatabase.md
+++ b/docs/StardustDocs/topics/readSqlFromCustomDatabase.md
@@ -498,6 +498,15 @@ we introduced the `AdvancedDbType` and `JdbcToDataFrameConverter` classes.
 This API is still experimental and may change in the future, but if you're interested in using it,
 check our [DuckDB implementation](https://github.com/Kotlin/dataframe/blob/master/dataframe-jdbc/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/db/DuckDb.kt).
 
+Another example is [SQLite](https://www.sqlite.org/datatype3.html), which uses [type affinity](https://www.sqlite.org/datatype3.html#type_affinity):
+every column is assigned one of five basic types, while the user-declared type serves as a hint and is exposed through metadata.
+
+However, the assigned column type does not always represent the actual values type,
+or you may want to provide custom type converters from primitive types
+(for example, to convert a `DATETIME` value stored as a `String`).
+`AdvancedDbType` and `JdbcToDataFrameConverter` help with these cases,
+making it easier to add support for custom types. 
+Check out [our SQLite implementation](https://github.com/Kotlin/dataframe/blob/master/dataframe-jdbc/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/db/Sqlite.kt).
+
 > **Note:** The set of overridable methods and properties may change in the next Beta release as we continue to improve
 > the API based on user feedback.
-
diff --git a/docs/StardustDocs/topics/readSqlTypeMapping.md b/docs/StardustDocs/topics/readSqlTypeMapping.md
index 082e731585..7fb69e5f46 100644
--- a/docs/StardustDocs/topics/readSqlTypeMapping.md
+++ b/docs/StardustDocs/topics/readSqlTypeMapping.md
@@ -14,7 +14,8 @@ Overview and index of the per-database SQL to Kotlin type mapping used by `dataf
 </link-summary>
 
 When reading from a JDBC database, DataFrame determines the Kotlin type of each column in
-two steps:
+two steps using `DbType` — a class responsible for handling column metadata and creating
+[`DataFrame`](DataFrame.md) columns based on it:
 
 1. **Type resolution** — the SQL/JDBC type reported by the driver is mapped to a JDBC-side
    Kotlin type (`DbType.getExpectedJdbcType`).
@@ -22,14 +23,19 @@ two steps:
    before being placed into the DataFrame (`DbType.preprocessValue`). For example,
    `java.sql.Timestamp` is turned into `kotlin.time.Instant`.
 
-Nullable columns produce nullable Kotlin types (`Int?` instead of `Int`).
+Nullable columns produce nullable Kotlin types (`Int?` instead of `Int`).`
+
+For some databases (such as [DuckDB](readSqlTypeMapping_DuckDB.md) and [SQLite](readSqlTypeMapping_SQLite.md)),
+this logic is overridden with custom dialect-specific converters based on column metadata —
+`JdbcToDataFrameConverter`. See [`AdvancedDbType`](readSqlFromCustomDatabase.md#advanceddbtype-new-in-1-0-0-beta5)
+for more information.
 
 ## Type alias handling
 
 Most SQL dialects define **type aliases** (e.g. `INT8` for `BIGINT` in MariaDB/MySQL/PostgreSQL,
 `BOOL` for `BOOLEAN`, `INTEGER` for `INT`, ...). Every database supported by DataFrame — **except
-SQLite** — canonicalises the declared type name at `CREATE TABLE` time, so the JDBC driver reports
-only the canonical form in `ResultSetMetaData.getColumnTypeName`. That means DataFrame never sees
+SQLite** — canonicalizes the declared type name at `CREATE TABLE` time, so the JDBC driver reports
+only the canonical form while getting a column metadata. That means DataFrame never sees
 the alias, only its canonical mapping. Each per-database page lists the aliases in the same row as
 the canonical type.
 
@@ -38,15 +44,17 @@ the canonical type.
 
 ## Per-database type mapping pages
 
-| Database                                                     | How it uses `DbType`                                                       |
-|--------------------------------------------------------------|-----------------------------------------------------------------------------|
-| [MariaDB](readSqlTypeMapping_MariaDB.md)                     | Default `DbType` + overrides for unsigned integer types.                    |
-| [MySQL](readSqlTypeMapping_MySQL.md)                         | Default `DbType` + overrides for unsigned integer types.                    |
-| [PostgreSQL](readSqlTypeMapping_PostgreSQL.md)               | Default `DbType` + `PGobject` overrides (`box`, `point`, `money`, ...).     |
-| [MS SQL Server](readSqlTypeMapping_MsSql.md)                 | Default `DbType`, no overrides.                                             |
-| [H2](readSqlTypeMapping_H2.md)                               | Default `DbType` in `Regular` mode; other modes delegate to another dialect.|
-| [SQLite](readSqlTypeMapping_SQLite.md)                       | Custom: type affinity + per-storage-class conversion for `BOOLEAN`/`DATE`/`DATETIME`/`TIME`/`TIMESTAMP`. |
-| [DuckDB](readSqlTypeMapping_DuckDB.md)                       | Bypasses `getExpectedJdbcType`; uses its own converter.                     |
+Here is a list of links for each database supported in Kotlin DataFrame:
+
+| Database                                       | How it uses `DbType`                                                                                                   |
+|------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
+| [MariaDB](readSqlTypeMapping_MariaDB.md)       | Default `DbType` + overrides for unsigned integer types.                                                               |
+| [MySQL](readSqlTypeMapping_MySQL.md)           | Default `DbType` + overrides for unsigned integer types.                                                               |
+| [PostgreSQL](readSqlTypeMapping_PostgreSQL.md) | Default `DbType` + `PGobject` overrides (`box`, `point`, `money`, ...).                                                |
+| [MS SQL Server](readSqlTypeMapping_MsSql.md)   | Default `DbType`, no overrides.                                                                                        |
+| [H2](readSqlTypeMapping_H2.md)                 | Default `DbType` in `Regular` mode; other modes delegate to another dialect.                                           |
+| [SQLite](readSqlTypeMapping_SQLite.md)         | `AdvancedDbType` with custom converters for boolean, date-time and numeric types. Allows to provide custom converters. |
+| [DuckDB](readSqlTypeMapping_DuckDB.md)         | `AdvancedDbType` with its own converters.                                                                              |
 
 ## Extending the mapping
 
diff --git a/docs/StardustDocs/topics/schemas/Data-Schemas-And-Extension-Properties-Troubleshooting.md b/docs/StardustDocs/topics/schemas/Data-Schemas-And-Extension-Properties-Troubleshooting.md
index 6447b6954e..234fb67094 100644
--- a/docs/StardustDocs/topics/schemas/Data-Schemas-And-Extension-Properties-Troubleshooting.md
+++ b/docs/StardustDocs/topics/schemas/Data-Schemas-And-Extension-Properties-Troubleshooting.md
@@ -115,10 +115,10 @@ You can explicitly specify the resulting Kotlin type using the `Sqlite.withCusto
 
 For example:
 - You have a `LONGVARCHAR` column containing text (i.e., `String` or `String?` values).
-  However, SQLite type affinity assigns it the `INTEGER` basic type, so the JDBC driver expects
+  However, SQLite type affinity assigns it the `NUMERIC` basic type, so the JDBC driver expects
   `Int` or `Long` values. Use `forType<String?>("LONGVARCHAR")` to explicitly specify the expected column type.
 - You have several columns of the `DATETIME` type. They are stored as `TEXT`, and Kotlin DataFrame
-  can automatically parse their values into date-time types. However, suppose the `time_stamp` column
+  can automatically parse their values into date-time types. However, suppose the `time_stamp` column of the `DATETIME` type
   contains date-time values in an unusual format. Automatic parsing fails and causes an exception.
   Use `forColumn("time_stamp") { ... }` to provide a custom converter specifically for this column.
 

From f1d33cf26bce51d63578437b3d8a22866b986d08 Mon Sep 17 00:00:00 2001
From: "andrei.kislitsyn" <kisandy@yandex.ru>
Date: Wed, 19 Aug 2026 14:41:38 +0400
Subject: [PATCH 08/10] Revise and expand JDBC type mapping documentation for
 H2, SQLite, and MySQL. Standardize column type terminology and add
 unsupported types section.

---
 .../kotlinx/dataframe/io/db/jdbcTypesTest.kt  |  41 ++++-
 .../StardustDocs/topics/readSqlTypeMapping.md |   2 +-
 .../topics/readSqlTypeMapping_DuckDB.md       | 144 +++++++++--------
 .../topics/readSqlTypeMapping_H2.md           | 114 +++++++-------
 .../topics/readSqlTypeMapping_MariaDB.md      | 148 +++++++++---------
 .../topics/readSqlTypeMapping_MsSql.md        |  66 ++++----
 .../topics/readSqlTypeMapping_MySQL.md        | 134 ++++++++--------
 .../topics/readSqlTypeMapping_PostgreSQL.md   |  71 +++++----
 .../topics/readSqlTypeMapping_SQLite.md       |  27 ++--
 9 files changed, 396 insertions(+), 351 deletions(-)

diff --git a/dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/jdbcTypesTest.kt b/dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/jdbcTypesTest.kt
index 1795b10b5d..8260ab1236 100644
--- a/dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/jdbcTypesTest.kt
+++ b/dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/jdbcTypesTest.kt
@@ -38,13 +38,15 @@ import kotlinx.datetime.LocalDateTime as KotlinLocalDateTime
 import kotlinx.datetime.LocalTime as KotlinLocalTime
 
 /**
- * Tests for [DbType.getExpectedJdbcType] and related type-mapping logic.
+ * Non-integraion tests for [DbType.getExpectedJdbcType] and related type-mapping logic.
  *
- * For each DB type implemented in Kotlin Dataframe, checks mapping between the SQL type and the expected type
- * for a [org.jetbrains.kotlinx.dataframe.DataFrame] [column][org.jetbrains.kotlinx.dataframe.DataColumn].
+ * For each DB type implemented in Kotlin Dataframe, checks mapping between the all of SQL types and their
+ * expected types for a [column][org.jetbrains.kotlinx.dataframe.DataColumn].
  *
  * Each DB owns a [TypeMapping] list that acts as the source of truth for its SQL → Kotlin type
  * mapping. The list is exercised for both nullable and non-nullable columns.
+ *
+ * Note that for all DBs (except SQLite), drivers report canonical name, erasing type aliases.
  */
 @RunWith(Enclosed::class)
 class JdbcTypesTest {
@@ -269,6 +271,32 @@ class JdbcTypesTest {
             ) shouldBe typeOf<PGpoint?>()
         }
 
+        @Test
+        fun `unrecognised PGobject types fall back to Any`() {
+            // Composite / hstore / PostGIS types come through the driver as generic PGobject
+            // with Types.OTHER. Because they are not in PostgreSql's pgObjectTypes lookup
+            // table, the mapping falls through to the default DbType handler, which returns
+            // Any for Types.OTHER + non-`[B` javaClassName.
+            listOf(
+                // Anonymous composite / user-defined ROW.
+                "record",
+                // hstore extension.
+                "hstore",
+                // PostGIS types.
+                "geometry",
+                "geography",
+            ).forEach { typeName ->
+                PostgreSql.getExpectedJdbcType(
+                    createColumnMetadata(
+                        sqlTypeName = typeName,
+                        jdbcType = Types.OTHER,
+                        javaClassName = "org.postgresql.util.PGobject",
+                        isNullable = false,
+                    ),
+                ) shouldBe typeOf<Any>()
+            }
+        }
+
         @Test
         fun `unknown jdbcType falls back to String`() {
             assertUnknownMapsToString(PostgreSql)
@@ -315,10 +343,11 @@ class JdbcTypesTest {
 // -------------------- Type mapping model & helpers --------------------
 
 /**
- * A single row in the JDBC → Kotlin type mapping table.
+ * JDBC column metadata → Kotlin type mapping.
+ * Nullability is omitted ([expectedType] should be non-nullable).
  *
- * @property sqlTypeName the human-readable SQL type name (e.g. "BIGINT")
- * @property jdbcType a constant from [java.sql.Types]
+ * @property sqlTypeName the jdbc reported SQL type name (e.g. "BIGINT")
+ * @property jdbcType the jdbc reported SQL type constant from [java.sql.Types]
  * @property javaClassName the JDBC-reported class name for this column (as returned by
  *   [java.sql.ResultSetMetaData.getColumnClassName])
  * @property expectedType the expected non-nullable Kotlin type
diff --git a/docs/StardustDocs/topics/readSqlTypeMapping.md b/docs/StardustDocs/topics/readSqlTypeMapping.md
index 7fb69e5f46..4aac32232d 100644
--- a/docs/StardustDocs/topics/readSqlTypeMapping.md
+++ b/docs/StardustDocs/topics/readSqlTypeMapping.md
@@ -1,4 +1,4 @@
-[//]: # (title: SQL to DataFrame type mapping)
+[//]: # (title: SQL to DataFrame column type mapping)
 
 <web-summary>
 Overview of how SQL column types are mapped to Kotlin types when reading a DataFrame
diff --git a/docs/StardustDocs/topics/readSqlTypeMapping_DuckDB.md b/docs/StardustDocs/topics/readSqlTypeMapping_DuckDB.md
index 4ef7d39d3d..ed85abfeb7 100644
--- a/docs/StardustDocs/topics/readSqlTypeMapping_DuckDB.md
+++ b/docs/StardustDocs/topics/readSqlTypeMapping_DuckDB.md
@@ -13,11 +13,11 @@ How DuckDB column types are read into DataFrame, including nested types.
 Full mapping of DuckDB SQL types to Kotlin types, including aliases and nested-type support.
 </link-summary>
 
-DuckDB uses a dedicated converter that bypasses `DbType.getExpectedJdbcType` and matches
+DuckDB uses `AdvancedDbType` with a dedicated converter that bypasses `DbType.getExpectedJdbcType` and matches
 directly on DuckDB's type names (see `DuckDb.parseDuckDbType`).
 The tables below list every DuckDB column type
 ([DuckDB Data Types](https://duckdb.org/docs/sql/data_types/overview)) and the resulting
-Kotlin type. Aliases are canonicalised by DuckDB at `CREATE TABLE` time, so DataFrame only
+Kotlin type. Aliases are canonicalized by DuckDB at `CREATE TABLE` time, so DataFrame only
 ever sees the canonical type; they are listed in the same row as the canonical type for
 reference.
 
@@ -25,99 +25,105 @@ Nullable columns produce nullable Kotlin types (`Int?` instead of `Int`).
 
 ## Boolean
 
-| Canonical | Aliases            | DataFrame type | Notes |
-|-----------|--------------------|----------------|-------|
-| `BOOLEAN` | `BOOL`, `LOGICAL`  | `Boolean`      |       |
+| Canonical | Aliases           | DataFrame column type | Notes |
+|-----------|-------------------|-----------------------|-------|
+| `BOOLEAN` | `BOOL`, `LOGICAL` | `Boolean`             |       |
 
 ## Signed integer types
 
-| Canonical    | Aliases          | DataFrame type          | Notes                                  |
-|--------------|------------------|-------------------------|----------------------------------------|
-| `TINYINT`    | `INT1`           | `Byte`                  | 1-byte signed.                         |
-| `SMALLINT`   | `INT2`, `SHORT`  | `Short`                 | 2-byte signed.                         |
-| `INTEGER`    | `INT4`, `INT`, `SIGNED` | `Int`            | 4-byte signed.                         |
-| `BIGINT`     | `INT8`, `LONG`   | `Long`                  | 8-byte signed.                         |
-| `HUGEINT`    | *none*           | `java.math.BigInteger`  | 16-byte signed (`-2^127 .. 2^127 - 1`).|
+| Canonical  | Aliases                 | DataFrame column type  | Notes                                   |
+|------------|-------------------------|------------------------|-----------------------------------------|
+| `TINYINT`  | `INT1`                  | `Byte`                 | 1-byte signed.                          |
+| `SMALLINT` | `INT2`, `SHORT`         | `Short`                | 2-byte signed.                          |
+| `INTEGER`  | `INT4`, `INT`, `SIGNED` | `Int`                  | 4-byte signed.                          |
+| `BIGINT`   | `INT8`, `LONG`          | `Long`                 | 8-byte signed.                          |
+| `HUGEINT`  | *none*                  | `java.math.BigInteger` | 16-byte signed (`-2^127 .. 2^127 - 1`). |
 
 ## Unsigned integer types
 
-| Canonical    | Aliases | DataFrame type          | Notes                                          |
-|--------------|---------|-------------------------|------------------------------------------------|
-| `UTINYINT`   | *none*  | `Short`                 | 1-byte unsigned; widened to `Short`.           |
-| `USMALLINT`  | *none*  | `Int`                   | 2-byte unsigned; widened to `Int`.             |
-| `UINTEGER`   | *none*  | `Long`                  | 4-byte unsigned; widened to `Long`.            |
-| `UBIGINT`    | *none*  | `java.math.BigInteger`  | 8-byte unsigned; exceeds `Long`.               |
-| `UHUGEINT`   | *none*  | `java.math.BigInteger`  | 16-byte unsigned.                              |
+| Canonical   | Aliases | DataFrame column type  | Notes                                |
+|-------------|---------|------------------------|--------------------------------------|
+| `UTINYINT`  | *none*  | `Short`                | 1-byte unsigned; widened to `Short`. |
+| `USMALLINT` | *none*  | `Int`                  | 2-byte unsigned; widened to `Int`.   |
+| `UINTEGER`  | *none*  | `Long`                 | 4-byte unsigned; widened to `Long`.  |
+| `UBIGINT`   | *none*  | `java.math.BigInteger` | 8-byte unsigned; exceeds `Long`.     |
+| `UHUGEINT`  | *none*  | `java.math.BigInteger` | 16-byte unsigned.                    |
 
 ## Floating-point and fixed-point
 
-| Canonical     | Aliases                             | DataFrame type          | Notes                                          |
-|---------------|-------------------------------------|-------------------------|------------------------------------------------|
-| `FLOAT`       | `FLOAT4`, `REAL`                    | `Float`                 | 4-byte float.                                  |
-| `DOUBLE`      | `FLOAT8`, `DOUBLE PRECISION`        | `Double`                | 8-byte float.                                  |
-| `DECIMAL(p,s)`| `NUMERIC(p,s)`                      | `java.math.BigDecimal`  | Fixed-point; `NUMERIC` without precision defaults to `DECIMAL(18,3)`. |
+| Canonical      | Aliases                      | DataFrame column type  | Notes                                                                 |
+|----------------|------------------------------|------------------------|-----------------------------------------------------------------------|
+| `FLOAT`        | `FLOAT4`, `REAL`             | `Float`                | 4-byte float.                                                         |
+| `DOUBLE`       | `FLOAT8`, `DOUBLE PRECISION` | `Double`               | 8-byte float.                                                         |
+| `DECIMAL(p,s)` | `NUMERIC(p,s)`               | `java.math.BigDecimal` | Fixed-point; `NUMERIC` without precision defaults to `DECIMAL(18,3)`. |
 
 ## String and binary
 
-| Canonical   | Aliases                                         | DataFrame type   | Notes                                                                    |
-|-------------|-------------------------------------------------|------------------|--------------------------------------------------------------------------|
-| `VARCHAR`   | `CHAR`, `BPCHAR`, `TEXT`, `STRING`              | `String`         | Variable-length text.                                                    |
-| `BLOB`      | `BYTEA`, `BINARY`, `VARBINARY`                  | `java.sql.Blob`  | Binary large object.                                                     |
-| `BIT`       | *none*                                          | `String`         | Fixed-length bit string; read as text.                                   |
+| Canonical | Aliases                            | DataFrame column type | Notes                                  |
+|-----------|------------------------------------|-----------------------|----------------------------------------|
+| `VARCHAR` | `CHAR`, `BPCHAR`, `TEXT`, `STRING` | `String`              | Variable-length text.                  |
+| `BLOB`    | `BYTEA`, `BINARY`, `VARBINARY`     | `java.sql.Blob`       | Binary large object.                   |
+| `BIT`     | *none*                             | `String`              | Fixed-length bit string; read as text. |
 
 ## Date and time
 
-| Canonical                    | Aliases                            | DataFrame type              | Notes                                                        |
-|------------------------------|------------------------------------|-----------------------------|--------------------------------------------------------------|
-| `DATE`                       | *none*                             | `kotlinx.datetime.LocalDate`| Preprocessed from `java.time.LocalDate`.                     |
-| `TIME`                       | *none*                             | `kotlinx.datetime.LocalTime`| Preprocessed from `java.time.LocalTime`.                     |
-| `TIME_NS`                    | *none*                             | `kotlinx.datetime.LocalTime`| Nanosecond-precision time.                                   |
-| `TIME WITH TIME ZONE`        | `TIMETZ`                           | `java.time.OffsetTime`      |                                                              |
-| `TIMESTAMP`                  | `DATETIME`                         | `kotlin.time.Instant`       | Preprocessed from `java.sql.Timestamp`.                      |
-| `TIMESTAMP_MS`               | *none*                             | `kotlin.time.Instant`       | Millisecond-precision timestamp.                             |
-| `TIMESTAMP_NS`               | *none*                             | `kotlin.time.Instant`       | Nanosecond-precision timestamp.                              |
-| `TIMESTAMP_S`                | *none*                             | `kotlin.time.Instant`       | Second-precision timestamp.                                  |
-| `TIMESTAMP WITH TIME ZONE`   | `TIMESTAMPTZ`                      | `java.time.OffsetDateTime`  | Timestamp with time zone.                                    |
-| `INTERVAL`                   | *none*                             | `String`                    | Read as text.                                                |
+| Canonical                  | Aliases       | DataFrame column type        | Notes                                    |
+|----------------------------|---------------|------------------------------|------------------------------------------|
+| `DATE`                     | *none*        | `kotlinx.datetime.LocalDate` | Preprocessed from `java.time.LocalDate`. |
+| `TIME`                     | *none*        | `kotlinx.datetime.LocalTime` | Preprocessed from `java.time.LocalTime`. |
+| `TIME_NS`                  | *none*        | `kotlinx.datetime.LocalTime` | Nanosecond-precision time.               |
+| `TIME WITH TIME ZONE`      | `TIMETZ`      | `java.time.OffsetTime`       | Time with time zone.                     |
+| `TIMESTAMP`                | `DATETIME`    | `kotlin.time.Instant`        | Preprocessed from `java.sql.Timestamp`.  |
+| `TIMESTAMP_MS`             | *none*        | `kotlin.time.Instant`        | Millisecond-precision timestamp.         |
+| `TIMESTAMP_NS`             | *none*        | `kotlin.time.Instant`        | Nanosecond-precision timestamp.          |
+| `TIMESTAMP_S`              | *none*        | `kotlin.time.Instant`        | Second-precision timestamp.              |
+| `TIMESTAMP WITH TIME ZONE` | `TIMESTAMPTZ` | `java.time.OffsetDateTime`   | Timestamp with time zone.                |
+| `INTERVAL`                 | *none*        | `String`                     | Read as text.                            |
 
 ## Complex / nested types
 
 DuckDB supports nested / composite types, which the DataFrame converter resolves recursively.
 
-| Canonical                    | Aliases | DataFrame type                     | Notes                                                                                     |
-|------------------------------|---------|------------------------------------|-------------------------------------------------------------------------------------------|
-| `LIST` (`T[]`)               | *none*  | `List<T>`                          | Element type is resolved recursively.                                                     |
-| `ARRAY` (`T[N]`)             | *none*  | `List<T>`                          | Same as `LIST`; the element type is resolved recursively.                                 |
-| `MAP(K, V)`                  | *none*  | `Map<K, V>`                        | Key and value types are resolved recursively.                                             |
-| `STRUCT(...)`                | *none*  | column group (`DataRow`)           | Fields resolved recursively; array-of-struct becomes a frame column.                      |
-| `UNION`                      | *none*  | `Any`                              | Not currently unpacked in Kotlin.                                                         |
-| `VARIANT`                    | *none*  | `Any`                              | Not currently unpacked in Kotlin.                                                         |
+| Canonical        | Aliases | DataFrame column type    | Notes                                                                |
+|------------------|---------|--------------------------|----------------------------------------------------------------------|
+| `LIST` (`T[]`)   | *none*  | `List<T>`                | Element type is resolved recursively.                                |
+| `ARRAY` (`T[N]`) | *none*  | `List<T>`                | Same as `LIST`; the element type is resolved recursively.            |
+| `MAP(K, V)`      | *none*  | `Map<K, V>`              | Key and value types are resolved recursively.                        |
+| `STRUCT(...)`    | *none*  | column group (`DataRow`) | Fields resolved recursively; array-of-struct becomes a frame column. |
+| `UNION`          | *none*  | `Any`                    | Not currently unpacked in Kotlin DataFrame.                          |
+| `VARIANT`        | *none*  | `Any`                    | Not currently unpacked in Kotlin DataFrame.                          |
 
 ## Other
 
-| Canonical    | Aliases | DataFrame type       | Notes                                                                                    |
-|--------------|---------|----------------------|------------------------------------------------------------------------------------------|
-| `UUID`       | *none*  | `kotlin.uuid.Uuid`   | Preprocessed from `java.util.UUID`.                                                      |
-| `JSON`       | *none*  | `String` (parsed)    | Read as JSON text and passed through `tryParse` + type inference.                        |
-| `ENUM`       | *none*  | `String`             | Read as the enum label.                                                                  |
-| `GEOMETRY`   | *none*  | `java.sql.Blob`      | Binary WKB read as `Blob`.                                                               |
-| `UNKNOWN`    | *none*  | `String`             | Fallback for anything not recognised by the converter.                                   |
+| Canonical  | Aliases | DataFrame column type                                                                              | Notes                                                             |
+|------------|---------|----------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
+| `UUID`     | *none*  | `kotlin.uuid.Uuid`                                                                                 | Preprocessed from `java.util.UUID`.                               |
+| `JSON`     | *none*  | `String`; is tried to parse into frame column (`DataFrame`), column group (`DataRow`) or primitive | Read as JSON text and passed through `tryParse` + type inference. |
+| `ENUM`     | *none*  | `String`                                                                                           | Read as the enum label.                                           |
+| `GEOMETRY` | *none*  | `java.sql.Blob`                                                                                    | Binary WKB read as `Blob`.                                        |
+| `UNKNOWN`  | *none*  | `String`                                                                                           | Fallback for anything not recognised by the converter.            |
 
 ## DuckDB specifics
 
-- DuckDB bypasses `DbType.getExpectedJdbcType` — its type resolution goes through
-  `DuckDb.parseDuckDbType` and matches directly on the DuckDB type name.
-- Nested types (`LIST`, `ARRAY`, `MAP`, `STRUCT`) are resolved recursively: `INTEGER[]`
-  becomes `List<Int>`, `MAP(VARCHAR, INTEGER)` becomes `Map<String, Int>`, and so on.
-- `STRUCT(...)` becomes a **column group** (`DataRow`); arrays of `STRUCT` become **frame
-  columns** (`DataFrame`).
-- Reading a DuckDB `JSON` column parses the text and re-infers the resulting DataFrame's
-  type — the column ends up as whatever the parser detected.
+- [Nested types](https://duckdb.org/docs/sql/data_types/overview#nested--composite-types)
+  (`LIST`, `ARRAY`, `MAP`, `STRUCT`) are resolved recursively: `INTEGER[]` becomes
+  `List<Int>`, `MAP(VARCHAR, INTEGER)` becomes `Map<String, Int>`, and so on.
+- [`STRUCT(...)`](https://duckdb.org/docs/sql/data_types/struct) becomes a **column group**
+  (`DataRow`); arrays of `STRUCT` become **frame columns** (`DataFrame`).
+- Reading a DuckDB [`JSON`](https://duckdb.org/docs/data/json/overview) column
+  [parses](parse.md) the JSON text:
+  - JSON array is read as `DataFrame` into the [frame column](DataColumn.md#framecolumn);
+  - JSON object is read as `DataRow` into the [column group](DataColumn.md#columngroup);
+  - JSON primitives are read as-is;
+  - on fail, keeps raw `String`.
 
 ## Unsupported types
 
-- `UNION` and `VARIANT` values are read as raw `Any` — the payload's actual type is not
-  unpacked in Kotlin.
-- `INTERVAL` values are read as their text form; no `Duration` conversion is applied.
-- Extension types (spatial via `duckdb_spatial`, full-text search, etc.) are read as the
-  extension's underlying storage type (usually `Blob` or `String`).
+- [`UNION`](https://duckdb.org/docs/sql/data_types/union) and
+  [`VARIANT`](https://duckdb.org/docs/sql/data_types/variant) values are read as raw `Any` —
+  the payload's actual type is not unpacked in Kotlin.
+- [`INTERVAL`](https://duckdb.org/docs/sql/data_types/interval) values are read as their text
+  form; no `Duration` conversion is applied.
+- Extension types (spatial via [`duckdb_spatial`](https://duckdb.org/docs/extensions/spatial/overview),
+  full-text search, etc.) are read as the extension's underlying storage type (usually `Blob`
+  or `String`).
diff --git a/docs/StardustDocs/topics/readSqlTypeMapping_H2.md b/docs/StardustDocs/topics/readSqlTypeMapping_H2.md
index c52c9e5d5a..1985ac4ecf 100644
--- a/docs/StardustDocs/topics/readSqlTypeMapping_H2.md
+++ b/docs/StardustDocs/topics/readSqlTypeMapping_H2.md
@@ -15,7 +15,7 @@ Full mapping of H2 SQL types to Kotlin types, including aliases and mode-specifi
 
 The tables below list every H2 column type ([H2 Data Types](https://www.h2database.com/html/datatypes.html))
 and the Kotlin type produced when the column is read into a DataFrame in `H2.Mode.Regular`.
-Aliases are canonicalised by H2 at `CREATE TABLE` time, so DataFrame only ever sees the
+Aliases are canonicalized by H2 at `CREATE TABLE` time, so DataFrame only ever sees the
 canonical type; they are listed in the same row as the canonical type for reference.
 
 For non-`Regular` modes, H2 delegates to the emulated dialect — see the [Mode section](#h2-modes) below.
@@ -24,62 +24,74 @@ Nullable columns produce nullable Kotlin types (`Int?` instead of `Int`).
 
 ## Character types
 
-| Canonical               | Aliases                                                                | DataFrame type | Notes                          |
-|-------------------------|------------------------------------------------------------------------|----------------|--------------------------------|
-| `CHAR[(n)]`             | `CHARACTER`, `NCHAR`                                                   | `String`       | Fixed-length text.             |
-| `VARCHAR[(n)]`          | `CHARACTER VARYING`, `LONGVARCHAR`, `VARCHAR2`, `NVARCHAR`, `NVARCHAR2`, `VARCHAR_CASESENSITIVE` | `String` | Variable-length text.  |
-| `VARCHAR_IGNORECASE[(n)]` | *none*                                                               | `String`       | Case-insensitive comparison; stored as text.        |
-| `CLOB`                  | `CHARACTER LARGE OBJECT`, `TINYTEXT`, `TEXT`, `MEDIUMTEXT`, `LONGTEXT`, `NTEXT`, `NCLOB` | `java.sql.Clob` | Large text object. |
+| Canonical                 | Aliases                                                                                          | DataFrame column type | Notes                                        |
+|---------------------------|--------------------------------------------------------------------------------------------------|-----------------------|----------------------------------------------|
+| `CHAR[(n)]`               | `CHARACTER`, `NCHAR`                                                                             | `String`              | Fixed-length text.                           |
+| `VARCHAR[(n)]`            | `CHARACTER VARYING`, `LONGVARCHAR`, `VARCHAR2`, `NVARCHAR`, `NVARCHAR2`, `VARCHAR_CASESENSITIVE` | `String`              | Variable-length text.                        |
+| `VARCHAR_IGNORECASE[(n)]` | *none*                                                                                           | `String`              | Case-insensitive comparison; stored as text. |
+| `CLOB`                    | `CHARACTER LARGE OBJECT`, `TINYTEXT`, `TEXT`, `MEDIUMTEXT`, `LONGTEXT`, `NTEXT`, `NCLOB`         | `java.sql.Clob`       | Large text object.                           |
 
 ## Binary types
 
-| Canonical      | Aliases                                                                | DataFrame type | Notes                          |
-|----------------|------------------------------------------------------------------------|----------------|--------------------------------|
-| `BINARY[(n)]`  | `RAW`                                                                  | `ByteArray`    | Fixed-length binary.           |
-| `VARBINARY[(n)]` | `LONGVARBINARY`, `BINARY VARYING`                                    | `ByteArray`    | Variable-length binary.        |
-| `BLOB`         | `BINARY LARGE OBJECT`, `TINYBLOB`, `MEDIUMBLOB`, `LONGBLOB`, `IMAGE`   | `java.sql.Blob` | Large binary object.          |
+| Canonical        | Aliases                                                              | DataFrame column type | Notes                   |
+|------------------|----------------------------------------------------------------------|-----------------------|-------------------------|
+| `BINARY[(n)]`    | `RAW`                                                                | `ByteArray`           | Fixed-length binary.    |
+| `VARBINARY[(n)]` | `LONGVARBINARY`, `BINARY VARYING`                                    | `ByteArray`           | Variable-length binary. |
+| `BLOB`           | `BINARY LARGE OBJECT`, `TINYBLOB`, `MEDIUMBLOB`, `LONGBLOB`, `IMAGE` | `java.sql.Blob`       | Large binary object.    |
 
 ## Boolean
 
-| Canonical | Aliases                | DataFrame type | Notes                                    |
-|-----------|------------------------|----------------|------------------------------------------|
-| `BOOLEAN` | `BOOL`, `BIT`, `LOGICAL` | `Boolean`    | Single-bit boolean.                      |
+| Canonical | Aliases                  | DataFrame column type | Notes               |
+|-----------|--------------------------|-----------------------|---------------------|
+| `BOOLEAN` | `BOOL`, `BIT`, `LOGICAL` | `Boolean`             | Single-bit boolean. |
 
 ## Numeric types
 
-| Canonical                        | Aliases                                        | DataFrame type          | Notes                                          |
-|----------------------------------|------------------------------------------------|-------------------------|------------------------------------------------|
-| `TINYINT`                        | *none*                                         | `Int`                   | 1-byte signed integer.                         |
-| `SMALLINT`                       | `INT2`, `YEAR`                                 | `Int`                   | 2-byte signed integer.                         |
-| `INTEGER`                        | `INT`, `INT4`, `MEDIUMINT`, `SIGNED`           | `Int`                   | 4-byte signed integer.                         |
-| `BIGINT`                         | `INT8`                                         | `Long`                  | 8-byte signed integer.                         |
-| `NUMERIC[(p[,s])]`               | `DECIMAL[(p[,s])]`, `DEC[(p[,s])]`, `NUMBER[(p[,s])]` | `java.math.BigDecimal` | Fixed-point.                               |
-| `REAL`                           | `FLOAT4`                                       | `Float`                 | 4-byte float.                                  |
-| `DOUBLE PRECISION`               | `DOUBLE`, `FLOAT`, `FLOAT8`                    | `Double`                | 8-byte float.                                  |
-| `DECFLOAT[(p)]`                  | *none*                                         | `java.math.BigDecimal`  | Decimal floating-point (H2 2.0+).              |
+| Canonical          | Aliases                                               | DataFrame column type  | Notes                             |
+|--------------------|-------------------------------------------------------|------------------------|-----------------------------------|
+| `TINYINT`          | *none*                                                | `Int`                  | 1-byte signed integer.            |
+| `SMALLINT`         | `INT2`, `YEAR`                                        | `Int`                  | 2-byte signed integer.            |
+| `INTEGER`          | `INT`, `INT4`, `MEDIUMINT`, `SIGNED`                  | `Int`                  | 4-byte signed integer.            |
+| `BIGINT`           | `INT8`                                                | `Long`                 | 8-byte signed integer.            |
+| `NUMERIC[(p[,s])]` | `DECIMAL[(p[,s])]`, `DEC[(p[,s])]`, `NUMBER[(p[,s])]` | `java.math.BigDecimal` | Fixed-point.                      |
+| `REAL`             | `FLOAT4`                                              | `Float`                | 4-byte float.                     |
+| `DOUBLE PRECISION` | `DOUBLE`, `FLOAT`, `FLOAT8`                           | `Double`               | 8-byte float.                     |
+| `DECFLOAT[(p)]`    | *none*                                                | `java.math.BigDecimal` | Decimal floating-point (H2 2.0+). |
 
 ## Date and time types
 
-| Canonical                                  | Aliases       | DataFrame type              | Notes                                                        |
-|--------------------------------------------|---------------|-----------------------------|--------------------------------------------------------------|
-| `DATE`                                     | *none*        | `java.util.Date`            |                                                              |
-| `TIME[(p)] [WITHOUT TIME ZONE]`            | *none*        | `java.sql.Time`             |                                                              |
-| `TIME[(p)] WITH TIME ZONE`                 | *none*        | `java.time.OffsetTime`      |                                                              |
-| `TIMESTAMP[(p)] [WITHOUT TIME ZONE]`       | `DATETIME`, `SMALLDATETIME` | `kotlin.time.Instant`     | Preprocessed from `java.sql.Timestamp`.                      |
-| `TIMESTAMP[(p)] WITH TIME ZONE`            | `DATETIMEOFFSET`, `TIMESTAMPTZ` | `java.time.OffsetDateTime` |                                                    |
-| `INTERVAL YEAR[(p)]`, `INTERVAL MONTH[(p)]`, ... | *none*  | `String`                    | Any of the 13 interval subtypes; read as text.               |
+| Canonical                                        | Aliases                         | DataFrame column type      | Notes                                          |
+|--------------------------------------------------|---------------------------------|----------------------------|------------------------------------------------|
+| `DATE`                                           | *none*                          | `java.util.Date`           |                                                |
+| `TIME[(p)] [WITHOUT TIME ZONE]`                  | *none*                          | `java.sql.Time`            |                                                |
+| `TIME[(p)] WITH TIME ZONE`                       | *none*                          | `java.time.OffsetTime`     |                                                |
+| `TIMESTAMP[(p)] [WITHOUT TIME ZONE]`             | `DATETIME`, `SMALLDATETIME`     | `kotlin.time.Instant`      | Preprocessed from `java.sql.Timestamp`.        |
+| `TIMESTAMP[(p)] WITH TIME ZONE`                  | `DATETIMEOFFSET`, `TIMESTAMPTZ` | `java.time.OffsetDateTime` |                                                |
+| `INTERVAL YEAR[(p)]`, `INTERVAL MONTH[(p)]`, ... | *none*                          | `String` (*unsupported*    | Any of the 13 interval subtypes; read as text. |
 
 ## Other types
 
-| Canonical            | Aliases        | DataFrame type      | Notes                                                                                    |
-|----------------------|----------------|---------------------|------------------------------------------------------------------------------------------|
-| `UUID`               | *none*         | `kotlin.uuid.Uuid`  | Preprocessed from `java.util.UUID`. Driver reports `Types.BINARY` + `java.util.UUID` class. |
-| `JAVA_OBJECT`        | `OTHER`        | `Any`               | Serialised Java object; read as opaque `Any`.                                            |
-| `ENUM`               | *none*         | `String`            | User-declared enum labels.                                                               |
-| `GEOMETRY`           | *none*         | `String`            | WKT text as reported by the driver.                                                      |
-| `JSON`               | *none*         | `String`            | JSON text.                                                                               |
-| `ARRAY`              | *none*         | `Array<*>`          | Element type inferred; falls back to `Any` for heterogeneous arrays.                     |
-| `ROW(...)`           | *none*         | *unsupported*       | See [Unsupported types](#unsupported-types).                                             |
+| Canonical     | Aliases | DataFrame column type    | Notes                                                                                       |
+|---------------|---------|--------------------------|---------------------------------------------------------------------------------------------|
+| `UUID`        | *none*  | `kotlin.uuid.Uuid`       | Preprocessed from `java.util.UUID`. Driver reports `Types.BINARY` + `java.util.UUID` class. |
+| `JAVA_OBJECT` | `OTHER` | `Any`                    | Serialised Java object; read as opaque `Any`.                                               |
+| `ENUM`        | *none*  | `String`                 | User-declared enum labels.                                                                  |
+| `GEOMETRY`    | *none*  | `String` (*unsupported*) | Only WKT text.                                                                              |
+| `JSON`        | *none*  | `String`                 | JSON text.                                                                                  |
+| `ARRAY`       | *none*  | `Array<*>`               | Element type inferred; falls back to `Any` for heterogeneous arrays.                        |
+| `ROW(...)`    | *none*  | `String` (*unsupported*) |                                                                                             |
+
+## Unsupported types
+
+- [`ROW(...)`](https://www.h2database.com/html/datatypes.html#row_type) composite /
+  structured types; driver reports `Types.OTHER`; DataFrame column type is `Any`.
+- [`INTERVAL`](https://www.h2database.com/html/datatypes.html#interval_type) subtypes
+  (all 13); read as their text form to a `String` column.
+- [Domain types](https://www.h2database.com/html/commands.html#create_domain) (H2 supports
+  `CREATE DOMAIN`); transparent at the JDBC layer — the underlying primitive's mapping
+  applies with a column of the corresponding type.
+- [`GEOMETRY`](https://www.h2database.com/html/datatypes.html#geometry_type) in binary/WKB
+  form; DataFrame reads only the WKT text form to a `String` column.
 
 ## H2 modes
 
@@ -93,21 +105,3 @@ dialect. The default mode is `Regular`.
 | `PostgreSql`   | [PostgreSQL](readSqlTypeMapping_PostgreSQL.md)                  |
 | `MsSqlServer`  | [MS SQL](readSqlTypeMapping_MsSql.md)                           |
 | `MariaDb`      | [MariaDB](readSqlTypeMapping_MariaDB.md)                        |
-
-## H2 specifics
-
-- H2 supports **compatibility modes** that emulate other dialects — set them via the JDBC URL
-  (`;MODE=MySQL`) and construct the corresponding `H2.Mode`. In compatibility modes, H2's
-  reserved-word list, function set, and type mapping change to match the emulated dialect.
-- `TIMESTAMP` and `DATETIME` are canonicalised to the same `TIMESTAMP` in metadata.
-- H2's `UUID` type is a first-class type (unlike PostgreSQL's, which is read as text) — the
-  driver reports it as a `BINARY` JDBC type with `java.util.UUID` class, so the mapping
-  produces `kotlin.uuid.Uuid` after preprocessing.
-- `NUMERIC` and `DECIMAL` are identical in H2 — both map to `BigDecimal`.
-
-## Unsupported types
-
-- `ROW(...)` composite / structured types.
-- `INTERVAL` subtypes (all 13 read as their string form).
-- Domain types (H2 supports `CREATE DOMAIN`), read as the underlying primitive.
-- `GEOMETRY` in binary/WKB form (WKT string is what the driver returns by default).
diff --git a/docs/StardustDocs/topics/readSqlTypeMapping_MariaDB.md b/docs/StardustDocs/topics/readSqlTypeMapping_MariaDB.md
index 95a38f4e42..caa60c0f59 100644
--- a/docs/StardustDocs/topics/readSqlTypeMapping_MariaDB.md
+++ b/docs/StardustDocs/topics/readSqlTypeMapping_MariaDB.md
@@ -10,90 +10,89 @@ How MariaDB column types are read into DataFrame.
 </card-summary>
 
 <link-summary>
-Full mapping of MariaDB SQL types to Kotlin types, including aliases and driver caveats.
+Full mapping of MariaDB SQL types to Kotlin types, including aliases and driver warnings.
 </link-summary>
 
 The tables below list every MariaDB column type ([MariaDB Data Types](https://mariadb.com/kb/en/data-types/))
-and the Kotlin type produced when the column is read into a DataFrame. Aliases are
-canonicalised by MariaDB at `CREATE TABLE` time, so DataFrame only ever sees the canonical
+and the Kotlin type produced when the column is read into a DataFrame. MariaDB 
+canonicalizes aliases at `CREATE TABLE` time, so DataFrame only ever sees the canonical
 type; they are listed in the same row as the canonical type for reference.
 
 Nullable columns produce nullable Kotlin types (`Int?` instead of `Int`).
 
 ## Numeric types
 
-| Canonical              | Aliases                | DataFrame type          | Notes                                                          |
-|------------------------|------------------------|-------------------------|----------------------------------------------------------------|
-| `TINYINT[(M)]`         | `INT1`                 | `Int`                   | 1-byte signed integer (`-128 .. 127`).                         |
-| `TINYINT UNSIGNED`     | `INT1 UNSIGNED`        | `Int`                   | 1-byte unsigned integer (`0 .. 255`).                          |
-| `BOOL`, `BOOLEAN`      | *(alias only)*         | `Boolean`               | Stored as `TINYINT(1)`; values are `0`/`1`.                    |
-| `SMALLINT[(M)]`        | `INT2`                 | `Int`                   | 2-byte signed integer. Becomes `Short` if the driver reports the column class as `java.lang.Short`. |
-| `SMALLINT UNSIGNED`    | `INT2 UNSIGNED`        | `Int`                   | 2-byte unsigned integer.                                       |
-| `MEDIUMINT[(M)]`       | `INT3`, `MIDDLEINT`    | `Int`                   | 3-byte signed integer.                                         |
-| `MEDIUMINT UNSIGNED`   | `INT3 UNSIGNED`, `MIDDLEINT UNSIGNED` | `Int`    | 3-byte unsigned integer.                                       |
-| `INT[(M)]`             | `INTEGER`, `INT4`      | `Int`                   | 4-byte signed integer.                                         |
-| `INT UNSIGNED`         | `INTEGER UNSIGNED`, `INT4 UNSIGNED` | `Long`     | MariaDB override: fits in `Long`, not `Int`.                   |
-| `BIGINT[(M)]`          | `INT8`                 | `Long`                  | 8-byte signed integer.                                         |
-| `BIGINT UNSIGNED`      | `INT8 UNSIGNED`        | `java.math.BigInteger`  | MariaDB override: exceeds `Long`, needs `BigInteger`.          |
-| `DECIMAL(M,D)`         | `DEC`, `NUMERIC`, `FIXED` | `java.math.BigDecimal` | Fixed-point.                                                   |
-| `FLOAT[(P)]`           | `FLOAT4`               | `Float`                 | 4-byte float. Becomes `Double` if the driver reports the column class as `java.lang.Double`. |
-| `DOUBLE`               | `FLOAT8`, `DOUBLE PRECISION`, `REAL` | `Double`  | 8-byte float.                                                  |
-| `BIT(M)`               | *none*                 | `ByteArray`             | Reported as `VARBINARY` for `M > 1`; `BIT(1)` may map to `Boolean`. |
+| Canonical            | Aliases                               | DataFrame column type  | Notes                                                                                               |
+|----------------------|---------------------------------------|------------------------|-----------------------------------------------------------------------------------------------------|
+| `TINYINT[(M)]`       | `INT1`                                | `Int`                  | 1-byte signed integer (`-128 .. 127`).                                                              |
+| `TINYINT UNSIGNED`   | `INT1 UNSIGNED`                       | `Int`                  | 1-byte unsigned integer (`0 .. 255`).                                                               |
+| `BOOL`, `BOOLEAN`    | alias for `TINYINT(1)`                | `Boolean`              | Stored as `TINYINT(1)`; values are `0`/`1`.                                                         |
+| `SMALLINT[(M)]`      | `INT2`                                | `Int`                  | 2-byte signed integer. Becomes `Short` if the driver reports the column class as `java.lang.Short`. |
+| `SMALLINT UNSIGNED`  | `INT2 UNSIGNED`                       | `Int`                  | 2-byte unsigned integer.                                                                            |
+| `MEDIUMINT[(M)]`     | `INT3`, `MIDDLEINT`                   | `Int`                  | 3-byte signed integer.                                                                              |
+| `MEDIUMINT UNSIGNED` | `INT3 UNSIGNED`, `MIDDLEINT UNSIGNED` | `Int`                  | 3-byte unsigned integer.                                                                            |
+| `INT[(M)]`           | `INTEGER`, `INT4`                     | `Int`                  | 4-byte signed integer.                                                                              |
+| `INT UNSIGNED`       | `INTEGER UNSIGNED`, `INT4 UNSIGNED`   | `Long`                 | MariaDB override: fits in `Long`, not `Int`.                                                        |
+| `BIGINT[(M)]`        | `INT8`                                | `Long`                 | 8-byte signed integer.                                                                              |
+| `BIGINT UNSIGNED`    | `INT8 UNSIGNED`                       | `java.math.BigInteger` | MariaDB override: exceeds `Long`, needs `BigInteger`.                                               |
+| `DECIMAL(M,D)`       | `DEC`, `NUMERIC`, `FIXED`             | `java.math.BigDecimal` | Fixed-point.                                                                                        |
+| `FLOAT[(P)]`         | `FLOAT4`                              | `Float`                | 4-byte float. Becomes `Double` if the driver reports the column class as `java.lang.Double`.        |
+| `DOUBLE`             | `FLOAT8`, `DOUBLE PRECISION`, `REAL`  | `Double`               | 8-byte float.                                                                                       |
+| `BIT(M)`             | *none*                                | `ByteArray`            | Reported as `VARBINARY` for `M > 1`; `BIT(1)` may map to `Boolean`.                                 |
 
 ## Date and time types
 
-| Canonical           | Aliases        | DataFrame type              | Notes                                                                      |
-|---------------------|----------------|-----------------------------|----------------------------------------------------------------------------|
-| `DATE`              | *none*         | `java.util.Date`            |                                                                            |
-| `TIME[(fsp)]`       | *none*         | `java.sql.Time`             | `fsp` is fractional seconds precision (0–6).                               |
-| `DATETIME[(fsp)]`   | *none*         | `kotlin.time.Instant`       | Preprocessed from `java.sql.Timestamp`.                                    |
-| `TIMESTAMP[(fsp)]`  | *none*         | `kotlin.time.Instant`       | Preprocessed from `java.sql.Timestamp`.                                    |
-| `YEAR[(4)]`         | *none*         | `java.util.Date`            | 1-byte year (`1901..2155`); driver reports it as `Types.DATE`.             |
+| Canonical          | Aliases | DataFrame column type | Notes                                                          |
+|--------------------|---------|-----------------------|----------------------------------------------------------------|
+| `DATE`             | *none*  | `java.util.Date`      |                                                                |
+| `TIME[(fsp)]`      | *none*  | `java.sql.Time`       | `fsp` is fractional seconds precision (0–6).                   |
+| `DATETIME[(fsp)]`  | *none*  | `kotlin.time.Instant` | Preprocessed from `java.sql.Timestamp`.                        |
+| `TIMESTAMP[(fsp)]` | *none*  | `kotlin.time.Instant` | Preprocessed from `java.sql.Timestamp`.                        |
+| `YEAR[(4)]`        | *none*  | `java.util.Date`      | 1-byte year (`1901..2155`); driver reports it as `Types.DATE`. |
 
 ## String types
 
-| Canonical                | Aliases                              | DataFrame type       | Notes                                                                    |
-|--------------------------|--------------------------------------|----------------------|--------------------------------------------------------------------------|
-| `CHAR(M)`                | `CHARACTER(M)`, `NATIONAL CHAR(M)`, `NCHAR(M)` | `String`   | Fixed-length text. Max `M = 255`.                                        |
-| `VARCHAR(M)`             | `CHARACTER VARYING(M)`, `NATIONAL VARCHAR(M)`, `NVARCHAR(M)` | `String` | Variable-length text.                                            |
-| `BINARY(M)`              | *none*                               | `ByteArray`          | Fixed-length binary.                                                     |
-| `VARBINARY(M)`           | `BINARY VARYING(M)`                  | `ByteArray`          | Variable-length binary.                                                  |
-| `TINYBLOB`               | *none*                               | `ByteArray`          | Up to 255 bytes.                                                         |
-| `TINYTEXT`               | *none*                               | `String`             | Up to 255 bytes.                                                         |
-| `BLOB[(M)]`              | *none*                               | `ByteArray`          | Up to 64 KiB.                                                            |
-| `TEXT[(M)]`              | *none*                               | `String`             | Up to 64 KiB.                                                            |
-| `MEDIUMBLOB`             | `LONG VARBINARY`                     | `ByteArray`          | Up to 16 MiB.                                                            |
-| `MEDIUMTEXT`             | `LONG VARCHAR`, `LONG`               | `String`             | Up to 16 MiB.                                                            |
-| `LONGBLOB`               | *none*                               | `ByteArray`          | Up to 4 GiB.                                                             |
-| `LONGTEXT`               | *none*                               | `String`             | Up to 4 GiB.                                                             |
-| `ENUM(...)`              | *none*                               | `String`             | Enumeration; values read as their string form.                           |
-| `SET(...)`               | *none*                               | `String`             | Comma-separated set of values, as a single string.                       |
+| Canonical      | Aliases                                                      | DataFrame column type | Notes                                              |
+|----------------|--------------------------------------------------------------|-----------------------|----------------------------------------------------|
+| `CHAR(M)`      | `CHARACTER(M)`, `NATIONAL CHAR(M)`, `NCHAR(M)`               | `String`              | Fixed-length text. Max `M = 255`.                  |
+| `VARCHAR(M)`   | `CHARACTER VARYING(M)`, `NATIONAL VARCHAR(M)`, `NVARCHAR(M)` | `String`              | Variable-length text.                              |
+| `BINARY(M)`    | *none*                                                       | `ByteArray`           | Fixed-length binary.                               |
+| `VARBINARY(M)` | `BINARY VARYING(M)`                                          | `ByteArray`           | Variable-length binary.                            |
+| `TINYBLOB`     | *none*                                                       | `ByteArray`           | Up to 255 bytes.                                   |
+| `TINYTEXT`     | *none*                                                       | `String`              | Up to 255 bytes.                                   |
+| `BLOB[(M)]`    | *none*                                                       | `ByteArray`           | Up to 64 KiB.                                      |
+| `TEXT[(M)]`    | *none*                                                       | `String`              | Up to 64 KiB.                                      |
+| `MEDIUMBLOB`   | `LONG VARBINARY`                                             | `ByteArray`           | Up to 16 MiB.                                      |
+| `MEDIUMTEXT`   | `LONG VARCHAR`, `LONG`                                       | `String`              | Up to 16 MiB.                                      |
+| `LONGBLOB`     | *none*                                                       | `ByteArray`           | Up to 4 GiB.                                       |
+| `LONGTEXT`     | *none*                                                       | `String`              | Up to 4 GiB.                                       |
+| `ENUM(...)`    | *none*                                                       | `String`              | Enumeration; values read as their string form.     |
+| `SET(...)`     | *none*                                                       | `String`              | Comma-separated set of values, as a single string. |
 
 ## JSON and UUID
 
-| Canonical  | Aliases | DataFrame type          | Notes                                                                                |
-|------------|---------|-------------------------|--------------------------------------------------------------------------------------|
-| `JSON`     | *none*  | `String`                | Physically stored as `LONGTEXT` in MariaDB; JDBC reports `LONGVARCHAR` → `String`.   |
-| `UUID`     | *none*  | `String`                | Available in MariaDB 10.7+. Read as text.                                            |
-| `INET4`    | *none*  | `String`                | Available in MariaDB 10.10+.                                                         |
-| `INET6`    | *none*  | `String`                | Available in MariaDB 10.10+.                                                         |
-| `ROW(...)` | *none*  | *unsupported*           | Anonymous row types are not currently mapped; see [Unsupported types](#unsupported-types). |
+| Canonical  | Aliases | DataFrame column type | Notes                                                                                      |
+|------------|---------|-----------------------|--------------------------------------------------------------------------------------------|
+| `JSON`     | *none*  | `String`              | Physically stored as `LONGTEXT` in MariaDB; JDBC reports `LONGVARCHAR` → `String`.         |
+| `UUID`     | *none*  | `String`              | Available in MariaDB 10.7+. Read as text.                                                  |
+| `INET4`    | *none*  | `String`              | Available in MariaDB 10.10+.                                                               |
+| `INET6`    | *none*  | `String`              | Available in MariaDB 10.10+.                                                               |
+| `ROW(...)` | *none*  | *unsupported*         | Anonymous row types are not currently mapped; see [Unsupported types](#unsupported-types). |
 
 ## Spatial types
 
 All spatial types are read as `ByteArray` (WKB / EWKB binary as reported by the driver).
-Parse them with a client-side geometry library.
-
-| Canonical            | Aliases | DataFrame type | Notes |
-|----------------------|---------|----------------|-------|
-| `GEOMETRY`           | *none*  | `ByteArray`    |       |
-| `POINT`              | *none*  | `ByteArray`    |       |
-| `LINESTRING`         | *none*  | `ByteArray`    |       |
-| `POLYGON`            | *none*  | `ByteArray`    |       |
-| `MULTIPOINT`         | *none*  | `ByteArray`    |       |
-| `MULTILINESTRING`    | *none*  | `ByteArray`    |       |
-| `MULTIPOLYGON`       | *none*  | `ByteArray`    |       |
-| `GEOMETRYCOLLECTION` | *none*  | `ByteArray`    |       |
+
+| Canonical            | Aliases | DataFrame column type | Notes |
+|----------------------|---------|-----------------------|-------|
+| `GEOMETRY`           | *none*  | `ByteArray`           |       |
+| `POINT`              | *none*  | `ByteArray`           |       |
+| `LINESTRING`         | *none*  | `ByteArray`           |       |
+| `POLYGON`            | *none*  | `ByteArray`           |       |
+| `MULTIPOINT`         | *none*  | `ByteArray`           |       |
+| `MULTILINESTRING`    | *none*  | `ByteArray`           |       |
+| `MULTIPOLYGON`       | *none*  | `ByteArray`           |       |
+| `GEOMETRYCOLLECTION` | *none*  | `ByteArray`           |       |
 
 ## MariaDB specifics
 
@@ -102,18 +101,19 @@ Parse them with a client-side geometry library.
   becomes `BigInteger` because its range exceeds `Long`.
 - `SMALLINT` may become `Short` (rather than `Int`) when the JDBC driver reports the column
   class as `java.lang.Short`.
-- `BIT(1)` and `BOOLEAN` are stored the same way (as `TINYINT(1)`) in older MariaDB versions;
-  which Kotlin type surfaces depends on driver behavior.
-- Zero-fill and display-width modifiers (e.g. `INT(11)`, `TINYINT ZEROFILL`) do not affect the
-  DataFrame type.
+- `BIT(1)` and `BOOLEAN` are stored the same way (as `TINYINT(1)`) — see MariaDB's
+  [BOOLEAN](https://mariadb.com/kb/en/boolean/) and [BIT](https://mariadb.com/kb/en/bit/)
+  pages. Which Kotlin type surfaces depends on how the driver reports the column's
+  `jdbcType` and `javaClassName`.
+- Display width (`INT(11)`) and `ZEROFILL` are server-side metadata and are not surfaced by
+  the MariaDB JDBC driver in `getColumnTypeName()`; DataFrame only ever sees the canonical
+  name — see [Numeric Data Type Overview](https://mariadb.com/kb/en/numeric-data-type-overview/).
 
 ## Unsupported types
 
-The following types are not mapped and read into DataFrame as best effort — either as
-`String` (via the driver's `getString` fallback) or as `ByteArray`. Explicit support may be
-added in future releases; for now, prefer explicit `CAST(... AS TEXT)` in the query or
-supply a custom converter via [a custom DbType](readSqlFromCustomDatabase.md).
-
-- Anonymous `ROW(...)` types.
-- `VECTOR` (MariaDB 11.7+).
-- Native representations of spatial types (they read as raw WKB `ByteArray`).
+- Anonymous [`ROW(...)`](https://mariadb.com/kb/en/anonymous-compound-statements/) types; read
+  as `String`.
+- [`VECTOR`](https://mariadb.com/kb/en/vector-overview/) (MariaDB 11.7+); read as `ByteArray`
+  (raw binary storage).
+- Native representations of spatial types; read as raw WKB `ByteArray`. Parse with a
+  client-side geometry library.
diff --git a/docs/StardustDocs/topics/readSqlTypeMapping_MsSql.md b/docs/StardustDocs/topics/readSqlTypeMapping_MsSql.md
index ad9d209555..5573717368 100644
--- a/docs/StardustDocs/topics/readSqlTypeMapping_MsSql.md
+++ b/docs/StardustDocs/topics/readSqlTypeMapping_MsSql.md
@@ -23,7 +23,7 @@ Nullable columns produce nullable Kotlin types (`Int?` instead of `Int`).
 
 ## Exact numeric types
 
-| Canonical           | Aliases                | DataFrame type          | Notes                                                                                     |
+| Canonical           | Aliases                | DataFrame column type          | Notes                                                                                     |
 |---------------------|------------------------|-------------------------|-------------------------------------------------------------------------------------------|
 | `bit`               | *none*                 | `Boolean`               | Single-bit integer (`0`/`1`/`NULL`).                                                      |
 | `tinyint`           | *none*                 | `Int`                   | 1-byte **unsigned** integer (`0..255`) — unusual: SQL Server's `tinyint` is unsigned.     |
@@ -36,14 +36,14 @@ Nullable columns produce nullable Kotlin types (`Int?` instead of `Int`).
 
 ## Approximate numeric types
 
-| Canonical             | Aliases                            | DataFrame type | Notes                                                    |
+| Canonical             | Aliases                            | DataFrame column type | Notes                                                    |
 |-----------------------|------------------------------------|----------------|----------------------------------------------------------|
 | `float(n)`            | `double precision` (n = 53)        | `Double`       | Default `n = 53`. `float(1..24)` maps to `Float`.        |
 | `real`                | *(alias)* `float(24)`              | `Float`        | Explicit 4-byte float; equivalent to `float(24)`.        |
 
 ## Date and time types
 
-| Canonical               | Aliases | DataFrame type              | Notes                                                                     |
+| Canonical               | Aliases | DataFrame column type              | Notes                                                                     |
 |-------------------------|---------|-----------------------------|---------------------------------------------------------------------------|
 | `date`                  | *none*  | `java.util.Date`            | Date only (`0001-01-01 .. 9999-12-31`).                                   |
 | `time(n)`               | *none*  | `java.sql.Time`             | Time only with fractional-second precision (0–7).                         |
@@ -54,7 +54,7 @@ Nullable columns produce nullable Kotlin types (`Int?` instead of `Int`).
 
 ## Character strings
 
-| Canonical             | Aliases                                   | DataFrame type | Notes                                                              |
+| Canonical             | Aliases                                   | DataFrame column type | Notes                                                              |
 |-----------------------|-------------------------------------------|----------------|--------------------------------------------------------------------|
 | `char(n)`             | `character(n)`                            | `String`       | Fixed-length non-Unicode text (max `n = 8000`).                    |
 | `varchar(n | max)`    | `character varying(n)`                    | `String`       | Variable-length non-Unicode text.                                  |
@@ -65,7 +65,7 @@ Nullable columns produce nullable Kotlin types (`Int?` instead of `Int`).
 
 ## Binary strings
 
-| Canonical             | Aliases                          | DataFrame type | Notes                                              |
+| Canonical             | Aliases                          | DataFrame column type | Notes                                              |
 |-----------------------|----------------------------------|----------------|----------------------------------------------------|
 | `binary(n)`           | *none*                           | `ByteArray`    | Fixed-length binary (max `n = 8000`).              |
 | `varbinary(n | max)`  | `binary varying(n)`              | `ByteArray`    | Variable-length binary.                            |
@@ -73,41 +73,47 @@ Nullable columns produce nullable Kotlin types (`Int?` instead of `Int`).
 
 ## Row-version and identity
 
-| Canonical         | Aliases       | DataFrame type | Notes                                                                                                     |
+| Canonical         | Aliases       | DataFrame column type | Notes                                                                                                     |
 |-------------------|---------------|----------------|-----------------------------------------------------------------------------------------------------------|
 | `rowversion`      | `timestamp`   | `ByteArray`    | 8-byte row-version. **Note:** SQL Server's `timestamp` is *not* a date/time type. Use `datetime2` instead. |
 | `uniqueidentifier`| *none*        | `String`       | 16-byte GUID, read as its 36-character string form.                                                       |
 
 ## Other types
 
-| Canonical      | Aliases | DataFrame type    | Notes                                                                                              |
-|----------------|---------|-------------------|----------------------------------------------------------------------------------------------------|
-| `xml`          | *none*  | `String`          | XML document text.                                                                                 |
-| `sql_variant`  | *none*  | `Any`             | Column holds a value of any base type; driver returns as generic `Object`.                         |
-| `hierarchyid`  | *none*  | `ByteArray`       | Hierarchical position (raw binary).                                                                |
-| `geometry`     | *none*  | `ByteArray`       | Planar spatial (WKB / EWKB).                                                                       |
-| `geography`    | *none*  | `ByteArray`       | Geodetic spatial (WKB / EWKB).                                                                     |
+| Canonical     | Aliases | DataFrame column type | Notes                                                                      |
+|---------------|---------|-----------------------|----------------------------------------------------------------------------|
+| `xml`         | *none*  | `String`              | XML document text.                                                         |
+| `sql_variant` | *none*  | `Any`                 | Column holds a value of any base type; driver returns as generic `Object`. |
+| `hierarchyid` | *none*  | `ByteArray`           | Hierarchical position (raw binary).                                        |
+| `geometry`    | *none*  | `ByteArray`           | Planar spatial (WKB / EWKB).                                               |
+| `geography`   | *none*  | `ByteArray`           | Geodetic spatial (WKB / EWKB).                                             |
 
 ## MS SQL Server specifics
 
-- Unlike most databases, SQL Server's `tinyint` is **unsigned** (`0..255`), not signed.
-- The keyword `TIMESTAMP` in T-SQL is a synonym for `rowversion` (a row-version stamp), **not**
-  a date/time type. Use `datetime2` for wall-clock timestamps.
-- `text`, `ntext`, and `image` are deprecated; SQL Server documentation recommends
-  `varchar(max)` / `nvarchar(max)` / `varbinary(max)` respectively.
-- `float(n)` with `n <= 24` returns `Float`; `n >= 25` returns `Double`. `float` alone means
-  `float(53)` and returns `Double`. `real` is `float(24)` and returns `Float`.
+- Unlike most databases, SQL Server's [`tinyint`](https://learn.microsoft.com/en-us/sql/t-sql/data-types/int-bigint-smallint-and-tinyint-transact-sql)
+  is **unsigned** (`0..255`), not signed.
+- The keyword `TIMESTAMP` in T-SQL is a synonym for
+  [`rowversion`](https://learn.microsoft.com/en-us/sql/t-sql/data-types/rowversion-transact-sql)
+  (a row-version stamp), **not** a date/time type. Use
+  [`datetime2`](https://learn.microsoft.com/en-us/sql/t-sql/data-types/datetime2-transact-sql)
+  for wall-clock timestamps.
+- [`text`, `ntext`, and `image`](https://learn.microsoft.com/en-us/sql/t-sql/data-types/ntext-text-and-image-transact-sql)
+  are deprecated; SQL Server documentation recommends `varchar(max)` / `nvarchar(max)` /
+  `varbinary(max)` respectively.
+- [`float(n)`](https://learn.microsoft.com/en-us/sql/t-sql/data-types/float-and-real-transact-sql)
+  with `n <= 24` returns `Float`; `n >= 25` returns `Double`. `float` alone means `float(53)`
+  and returns `Double`. `real` is `float(24)` and returns `Float`.
 - MS SQL Server does not need any DB-specific overrides in DataFrame — the default `DbType`
-  mapping is used as-is.
+  mapping is used as-is (see the "common SQL types" case in `JdbcTypesTest`).
 
 ## Unsupported types
 
-Types below are read as best effort (usually `ByteArray` or `String`). Explicit typed
-support may be added later; for now, cast in your query (`geom.STAsText()`,
-`CAST(v AS NVARCHAR)`) or supply a custom converter via
-[a custom DbType](readSqlFromCustomDatabase.md).
-
-- `geometry`, `geography` (read as raw WKB `ByteArray`).
-- `hierarchyid` (read as raw `ByteArray`).
-- `sql_variant` (read as generic `Any`).
-- `cursor` and `table` types cannot be columns; they only occur as procedure parameters.
+- [`geometry`, `geography`](https://learn.microsoft.com/en-us/sql/t-sql/spatial-geometry/spatial-types-geometry-transact-sql);
+  read as raw WKB `ByteArray`.
+- [`hierarchyid`](https://learn.microsoft.com/en-us/sql/t-sql/data-types/hierarchyid-data-type-method-reference);
+  read as raw `ByteArray`.
+- [`sql_variant`](https://learn.microsoft.com/en-us/sql/t-sql/data-types/sql-variant-transact-sql);
+  read as generic `Any`.
+- [`cursor`](https://learn.microsoft.com/en-us/sql/t-sql/data-types/cursor-transact-sql) and
+  [`table`](https://learn.microsoft.com/en-us/sql/t-sql/data-types/table-transact-sql) types
+  cannot be columns; they only occur as procedure parameters.
diff --git a/docs/StardustDocs/topics/readSqlTypeMapping_MySQL.md b/docs/StardustDocs/topics/readSqlTypeMapping_MySQL.md
index 79552e870e..136e0dba5a 100644
--- a/docs/StardustDocs/topics/readSqlTypeMapping_MySQL.md
+++ b/docs/StardustDocs/topics/readSqlTypeMapping_MySQL.md
@@ -22,93 +22,97 @@ Nullable columns produce nullable Kotlin types (`Int?` instead of `Int`).
 
 ## Numeric types
 
-| Canonical              | Aliases                | DataFrame type          | Notes                                                                                     |
-|------------------------|------------------------|-------------------------|-------------------------------------------------------------------------------------------|
-| `TINYINT[(M)]`         | `INT1`                 | `Int`                   | 1-byte signed integer (`-128 .. 127`).                                                    |
-| `TINYINT UNSIGNED`     | `INT1 UNSIGNED`        | `Int`                   | 1-byte unsigned integer (`0 .. 255`).                                                     |
-| `BOOL`, `BOOLEAN`      | *(alias only)*         | `Boolean`               | Stored as `TINYINT(1)`; values are `0`/`1`.                                               |
-| `SMALLINT[(M)]`        | `INT2`                 | `Int`                   | 2-byte signed integer.                                                                    |
-| `SMALLINT UNSIGNED`    | `INT2 UNSIGNED`        | `Int`                   | 2-byte unsigned integer.                                                                  |
-| `MEDIUMINT[(M)]`       | `INT3`, `MIDDLEINT`    | `Int`                   | 3-byte signed integer.                                                                    |
-| `MEDIUMINT UNSIGNED`   | `INT3 UNSIGNED`, `MIDDLEINT UNSIGNED` | `Int`    | 3-byte unsigned integer.                                                                  |
-| `INT[(M)]`             | `INTEGER`, `INT4`      | `Int`                   | 4-byte signed integer.                                                                    |
-| `INT UNSIGNED`         | `INTEGER UNSIGNED`, `INT4 UNSIGNED` | `Long`     | MySQL override: fits in `Long`, not `Int`.                                                |
-| `BIGINT[(M)]`          | `INT8`                 | `Long`                  | 8-byte signed integer.                                                                    |
-| `BIGINT UNSIGNED`      | `INT8 UNSIGNED`        | `java.math.BigInteger`  | MySQL override: exceeds `Long`, needs `BigInteger`.                                       |
-| `DECIMAL(M,D)`         | `DEC`, `NUMERIC`, `FIXED` | `java.math.BigDecimal` | Fixed-point.                                                                              |
-| `FLOAT[(P)]`           | `FLOAT4`               | `Float`                 | 4-byte float. Becomes `Double` if the driver reports the column class as `java.lang.Double`. |
-| `DOUBLE`               | `FLOAT8`, `DOUBLE PRECISION` | `Double`         | 8-byte float.                                                                             |
-| `REAL`                 | *(alias only)*         | `Double`                | By default `REAL` is `DOUBLE`. Becomes `FLOAT` under the `REAL_AS_FLOAT` SQL mode.         |
-| `BIT(M)`               | *none*                 | `ByteArray`             | Reported as `BIT`/`VARBINARY`; `BIT(1)` may map to `Boolean`.                              |
+| Canonical            | Aliases                               | DataFrame column type  | Notes                                                                                        |
+|----------------------|---------------------------------------|------------------------|----------------------------------------------------------------------------------------------|
+| `TINYINT[(M)]`       | `INT1`                                | `Int`                  | 1-byte signed integer (`-128 .. 127`).                                                       |
+| `TINYINT UNSIGNED`   | `INT1 UNSIGNED`                       | `Int`                  | 1-byte unsigned integer (`0 .. 255`).                                                        |
+| `BOOL`, `BOOLEAN`    | *(alias only)*                        | `Boolean`              | Stored as `TINYINT(1)`; values are `0`/`1`.                                                  |
+| `SMALLINT[(M)]`      | `INT2`                                | `Int`                  | 2-byte signed integer.                                                                       |
+| `SMALLINT UNSIGNED`  | `INT2 UNSIGNED`                       | `Int`                  | 2-byte unsigned integer.                                                                     |
+| `MEDIUMINT[(M)]`     | `INT3`, `MIDDLEINT`                   | `Int`                  | 3-byte signed integer.                                                                       |
+| `MEDIUMINT UNSIGNED` | `INT3 UNSIGNED`, `MIDDLEINT UNSIGNED` | `Int`                  | 3-byte unsigned integer.                                                                     |
+| `INT[(M)]`           | `INTEGER`, `INT4`                     | `Int`                  | 4-byte signed integer.                                                                       |
+| `INT UNSIGNED`       | `INTEGER UNSIGNED`, `INT4 UNSIGNED`   | `Long`                 | MySQL override: fits in `Long`, not `Int`.                                                   |
+| `BIGINT[(M)]`        | `INT8`                                | `Long`                 | 8-byte signed integer.                                                                       |
+| `BIGINT UNSIGNED`    | `INT8 UNSIGNED`                       | `java.math.BigInteger` | MySQL override: exceeds `Long`, needs `BigInteger`.                                          |
+| `DECIMAL(M,D)`       | `DEC`, `NUMERIC`, `FIXED`             | `java.math.BigDecimal` | Fixed-point.                                                                                 |
+| `FLOAT[(P)]`         | `FLOAT4`                              | `Float`                | 4-byte float. Becomes `Double` if the driver reports the column class as `java.lang.Double`. |
+| `DOUBLE`             | `FLOAT8`, `DOUBLE PRECISION`          | `Double`               | 8-byte float.                                                                                |
+| `REAL`               | *(alias only)*                        | `Double`               | By default `REAL` is `DOUBLE`. Becomes `FLOAT` under the `REAL_AS_FLOAT` SQL mode.           |
+| `BIT(M)`             | *none*                                | `ByteArray`            | Reported as `BIT`/`VARBINARY`; `BIT(1)` may map to `Boolean`.                                |
 
 ## Date and time types
 
-| Canonical           | Aliases  | DataFrame type          | Notes                                                                     |
-|---------------------|----------|-------------------------|---------------------------------------------------------------------------|
-| `DATE`              | *none*   | `java.util.Date`        |                                                                           |
-| `TIME[(fsp)]`       | *none*   | `java.sql.Time`         | `fsp` is fractional seconds precision (0–6).                              |
-| `DATETIME[(fsp)]`   | *none*   | `kotlin.time.Instant`   | Preprocessed from `java.sql.Timestamp`.                                   |
-| `TIMESTAMP[(fsp)]`  | *none*   | `kotlin.time.Instant`   | Preprocessed from `java.sql.Timestamp`.                                   |
-| `YEAR[(4)]`         | *none*   | `java.util.Date`        | 1-byte year (`1901..2155`); driver reports it as `Types.DATE`. Two-digit form `YEAR(2)` was removed in 5.7.5. |
+| Canonical          | Aliases | DataFrame column type | Notes                                                                                                         |
+|--------------------|---------|-----------------------|---------------------------------------------------------------------------------------------------------------|
+| `DATE`             | *none*  | `java.util.Date`      |                                                                                                               |
+| `TIME[(fsp)]`      | *none*  | `java.sql.Time`       | `fsp` is fractional seconds precision (0–6).                                                                  |
+| `DATETIME[(fsp)]`  | *none*  | `kotlin.time.Instant` | Preprocessed from `java.sql.Timestamp`.                                                                       |
+| `TIMESTAMP[(fsp)]` | *none*  | `kotlin.time.Instant` | Preprocessed from `java.sql.Timestamp`.                                                                       |
+| `YEAR[(4)]`        | *none*  | `java.util.Date`      | 1-byte year (`1901..2155`); driver reports it as `Types.DATE`. Two-digit form `YEAR(2)` was removed in 5.7.5. |
 
 ## String types
 
-| Canonical             | Aliases                                                       | DataFrame type       | Notes                                                                    |
-|-----------------------|---------------------------------------------------------------|----------------------|--------------------------------------------------------------------------|
-| `CHAR(M)`             | `CHARACTER(M)`, `NATIONAL CHAR(M)`, `NCHAR(M)`                | `String`             | Fixed-length text. Max `M = 255`.                                        |
-| `VARCHAR(M)`          | `CHARACTER VARYING(M)`, `NATIONAL VARCHAR(M)`, `NVARCHAR(M)`  | `String`             | Variable-length text.                                                    |
-| `BINARY(M)`           | *none*                                                        | `ByteArray`          | Fixed-length binary.                                                     |
-| `VARBINARY(M)`        | `BINARY VARYING(M)`                                           | `ByteArray`          | Variable-length binary.                                                  |
-| `TINYBLOB`            | *none*                                                        | `ByteArray`          | Up to 255 bytes.                                                         |
-| `TINYTEXT`            | *none*                                                        | `String`             | Up to 255 bytes.                                                         |
-| `BLOB[(M)]`           | *none*                                                        | `ByteArray`          | Up to 64 KiB.                                                            |
-| `TEXT[(M)]`           | *none*                                                        | `String`             | Up to 64 KiB.                                                            |
-| `MEDIUMBLOB`          | `LONG VARBINARY`                                              | `ByteArray`          | Up to 16 MiB.                                                            |
-| `MEDIUMTEXT`          | `LONG VARCHAR`, `LONG`                                        | `String`             | Up to 16 MiB.                                                            |
-| `LONGBLOB`            | *none*                                                        | `ByteArray`          | Up to 4 GiB.                                                             |
-| `LONGTEXT`            | *none*                                                        | `String`             | Up to 4 GiB.                                                             |
-| `ENUM(...)`           | *none*                                                        | `String`             | Enumeration; values read as their string form.                           |
-| `SET(...)`            | *none*                                                        | `String`             | Comma-separated set of values, as a single string.                       |
+| Canonical      | Aliases                                                      | DataFrame column type | Notes                                              |
+|----------------|--------------------------------------------------------------|-----------------------|----------------------------------------------------|
+| `CHAR(M)`      | `CHARACTER(M)`, `NATIONAL CHAR(M)`, `NCHAR(M)`               | `String`              | Fixed-length text. Max `M = 255`.                  |
+| `VARCHAR(M)`   | `CHARACTER VARYING(M)`, `NATIONAL VARCHAR(M)`, `NVARCHAR(M)` | `String`              | Variable-length text.                              |
+| `BINARY(M)`    | *none*                                                       | `ByteArray`           | Fixed-length binary.                               |
+| `VARBINARY(M)` | `BINARY VARYING(M)`                                          | `ByteArray`           | Variable-length binary.                            |
+| `TINYBLOB`     | *none*                                                       | `ByteArray`           | Up to 255 bytes.                                   |
+| `TINYTEXT`     | *none*                                                       | `String`              | Up to 255 bytes.                                   |
+| `BLOB[(M)]`    | *none*                                                       | `ByteArray`           | Up to 64 KiB.                                      |
+| `TEXT[(M)]`    | *none*                                                       | `String`              | Up to 64 KiB.                                      |
+| `MEDIUMBLOB`   | `LONG VARBINARY`                                             | `ByteArray`           | Up to 16 MiB.                                      |
+| `MEDIUMTEXT`   | `LONG VARCHAR`, `LONG`                                       | `String`              | Up to 16 MiB.                                      |
+| `LONGBLOB`     | *none*                                                       | `ByteArray`           | Up to 4 GiB.                                       |
+| `LONGTEXT`     | *none*                                                       | `String`              | Up to 4 GiB.                                       |
+| `ENUM(...)`    | *none*                                                       | `String`              | Enumeration; values read as their string form.     |
+| `SET(...)`     | *none*                                                       | `String`              | Comma-separated set of values, as a single string. |
 
 ## JSON
 
-| Canonical | Aliases | DataFrame type | Notes                                                                                              |
-|-----------|---------|----------------|----------------------------------------------------------------------------------------------------|
-| `JSON`    | *none*  | `String`       | Validated JSON text. Physically distinct from `LONGTEXT` in MySQL; JDBC still returns it as text. |
+| Canonical | Aliases | DataFrame column type | Notes                                                                                             |
+|-----------|---------|-----------------------|---------------------------------------------------------------------------------------------------|
+| `JSON`    | *none*  | `String`              | Validated JSON text. Physically distinct from `LONGTEXT` in MySQL; JDBC still returns it as text. |
 
 ## Spatial types
 
 All spatial types are read as `ByteArray` (WKB / EWKB binary as reported by the driver).
 Parse them with a client-side geometry library.
 
-| Canonical            | Aliases | DataFrame type | Notes |
-|----------------------|---------|----------------|-------|
-| `GEOMETRY`           | *none*  | `ByteArray`    |       |
-| `POINT`              | *none*  | `ByteArray`    |       |
-| `LINESTRING`         | *none*  | `ByteArray`    |       |
-| `POLYGON`            | *none*  | `ByteArray`    |       |
-| `MULTIPOINT`         | *none*  | `ByteArray`    |       |
-| `MULTILINESTRING`    | *none*  | `ByteArray`    |       |
-| `MULTIPOLYGON`       | *none*  | `ByteArray`    |       |
-| `GEOMETRYCOLLECTION` | *none*  | `ByteArray`    |       |
+| Canonical            | Aliases | DataFrame column type | Notes |
+|----------------------|---------|-----------------------|-------|
+| `GEOMETRY`           | *none*  | `ByteArray`           |       |
+| `POINT`              | *none*  | `ByteArray`           |       |
+| `LINESTRING`         | *none*  | `ByteArray`           |       |
+| `POLYGON`            | *none*  | `ByteArray`           |       |
+| `MULTIPOINT`         | *none*  | `ByteArray`           |       |
+| `MULTILINESTRING`    | *none*  | `ByteArray`           |       |
+| `MULTIPOLYGON`       | *none*  | `ByteArray`           |       |
+| `GEOMETRYCOLLECTION` | *none*  | `ByteArray`           |       |
 
 ## MySQL specifics
 
 - `INT UNSIGNED` and `BIGINT UNSIGNED` are the only types that need MySQL-specific handling.
   `INT UNSIGNED` is widened to `Long`; `BIGINT UNSIGNED` becomes `BigInteger` because its range
   exceeds `Long`.
-- The value of `REAL` depends on the [`REAL_AS_FLOAT`](https://dev.mysql.com/doc/refman/8.0/en/sql-mode.html)
+- The value of `REAL` depends on the [`REAL_AS_FLOAT`](https://dev.mysql.com/doc/refman/8.0/en/sql-mode.html#sqlmode_real_as_float)
   SQL mode: default `REAL` is `DOUBLE`; with `REAL_AS_FLOAT` set, it's `FLOAT`.
-- Zero-fill and display-width modifiers (e.g. `INT(11)`, `TINYINT ZEROFILL`) do not affect the
-  DataFrame type; MySQL 8.0.17+ ignores them for most numeric types.
-- Unlike MariaDB, MySQL 8.0 does **not** have native `UUID` / `INET4` / `INET6` types; use
-  `CHAR(36)` or `BINARY(16)` and convert client-side.
+- Display width (`INT(11)`) and `ZEROFILL` are server-side metadata and are not surfaced by
+  MySQL Connector/J in `getColumnTypeName()`; DataFrame only ever sees the canonical name.
+  Both attributes are deprecated for numeric types as of MySQL 8.0.17 — see
+  [Numeric Type Attributes](https://dev.mysql.com/doc/refman/8.0/en/numeric-type-attributes.html).
+- `TINYINT(1)` is a special case: MySQL Connector/J reports it as `Types.BIT` (→ `Boolean`) by
+  default because of the driver's [`tinyInt1isBit`](https://dev.mysql.com/doc/connector-j/en/connector-j-connp-props-datatypes.html)
+  property. Set `tinyInt1isBit=false` in the JDBC URL to read it as `Int` instead.
+- MySQL 8.0 does **not** have native `UUID` / `INET4` / `INET6` types (unlike MariaDB); use
+  `CHAR(36)` or `BINARY(16)` and convert client-side — see
+  [MySQL 8.0 Data Types](https://dev.mysql.com/doc/refman/8.0/en/data-types.html).
 
 ## Unsupported types
 
-- Native representations of spatial types (they read as raw WKB `ByteArray`).
-- `VECTOR` (MySQL 9.0+); currently read as `ByteArray`.
-- User-defined `TYPE` (rarely used in MySQL).
-
-For explicit support of these, either cast in your query (e.g. `SELECT ST_AsText(geom)`)
-or supply a custom converter via [a custom DbType](readSqlFromCustomDatabase.md).
+- Spatial types have no native Kotlin representation — read as raw WKB `ByteArray`. Parse
+  with a client-side geometry library.
+- [`VECTOR`](https://dev.mysql.com/doc/refman/9.0/en/vector.html) (MySQL 9.0+); the driver
+  reports it as a binary type, so DataFrame reads it as `ByteArray`.
diff --git a/docs/StardustDocs/topics/readSqlTypeMapping_PostgreSQL.md b/docs/StardustDocs/topics/readSqlTypeMapping_PostgreSQL.md
index 89bbc6f250..f3fb13f407 100644
--- a/docs/StardustDocs/topics/readSqlTypeMapping_PostgreSQL.md
+++ b/docs/StardustDocs/topics/readSqlTypeMapping_PostgreSQL.md
@@ -16,14 +16,14 @@ and driver caveats.
 
 The tables below list every PostgreSQL column type ([PostgreSQL Data Types](https://www.postgresql.org/docs/current/datatype.html))
 and the Kotlin type produced when the column is read into a DataFrame. Aliases are
-canonicalised by PostgreSQL at `CREATE TABLE` time, so DataFrame only ever sees the canonical
+canonicalized by PostgreSQL at `CREATE TABLE` time, so DataFrame only ever sees the canonical
 type; they are listed in the same row as the canonical type for reference.
 
 Nullable columns produce nullable Kotlin types (`Int?` instead of `Int`).
 
 ## Numeric types
 
-| Canonical           | Aliases            | DataFrame type          | Notes                                                                                     |
+| Canonical           | Aliases            | DataFrame column type          | Notes                                                                                     |
 |---------------------|--------------------|-------------------------|-------------------------------------------------------------------------------------------|
 | `smallint`          | `int2`             | `Int`                   | 2-byte signed integer.                                                                    |
 | `integer`           | `int`, `int4`      | `Int`                   | 4-byte signed integer.                                                                    |
@@ -38,13 +38,13 @@ Nullable columns produce nullable Kotlin types (`Int?` instead of `Int`).
 
 ## Boolean
 
-| Canonical | Aliases | DataFrame type | Notes |
+| Canonical | Aliases | DataFrame column type | Notes |
 |-----------|---------|----------------|-------|
 | `boolean` | `bool`  | `Boolean`      |       |
 
 ## Character types
 
-| Canonical            | Aliases                   | DataFrame type | Notes                          |
+| Canonical            | Aliases                   | DataFrame column type | Notes                          |
 |----------------------|---------------------------|----------------|--------------------------------|
 | `character(n)`       | `char(n)`                 | `String`       | Fixed-length text.             |
 | `character varying(n)` | `varchar(n)`            | `String`       | Variable-length text.          |
@@ -52,13 +52,13 @@ Nullable columns produce nullable Kotlin types (`Int?` instead of `Int`).
 
 ## Binary
 
-| Canonical | Aliases | DataFrame type | Notes                                                                       |
+| Canonical | Aliases | DataFrame column type | Notes                                                                       |
 |-----------|---------|----------------|-----------------------------------------------------------------------------|
 | `bytea`   | *none*  | `ByteArray`    | Raw binary. Driver reports it as `[B` (`byte[]`).                           |
 
 ## Date and time types
 
-| Canonical                             | Aliases          | DataFrame type              | Notes                                                                     |
+| Canonical                             | Aliases          | DataFrame column type              | Notes                                                                     |
 |---------------------------------------|------------------|-----------------------------|---------------------------------------------------------------------------|
 | `date`                                | *none*           | `java.util.Date`            |                                                                           |
 | `time [without time zone] [(p)]`      | *none*           | `java.sql.Time`             | `p` is fractional-second precision (0–6).                                 |
@@ -71,7 +71,7 @@ Nullable columns produce nullable Kotlin types (`Int?` instead of `Int`).
 
 Case-insensitive `sqlTypeName` lookup selects a PostgreSQL-specific PGobject wrapper.
 
-| Canonical | Aliases | DataFrame type                              | Notes            |
+| Canonical | Aliases | DataFrame column type                              | Notes            |
 |-----------|---------|---------------------------------------------|------------------|
 | `box`     | *none*  | `org.postgresql.geometric.PGbox`            | Rectangle        |
 | `circle`  | *none*  | `org.postgresql.geometric.PGcircle`         | Circle           |
@@ -83,14 +83,14 @@ Case-insensitive `sqlTypeName` lookup selects a PostgreSQL-specific PGobject wra
 
 ## Bit strings
 
-| Canonical         | Aliases   | DataFrame type | Notes                                                                    |
+| Canonical         | Aliases   | DataFrame column type | Notes                                                                    |
 |-------------------|-----------|----------------|--------------------------------------------------------------------------|
 | `bit(n)`          | *none*    | `String`       | Reported by the driver as `String` — `"0"` and `"1"` characters.         |
 | `bit varying(n)`  | `varbit`  | `String`       |                                                                          |
 
 ## UUID, XML, JSON
 
-| Canonical | Aliases | DataFrame type | Notes                                                                             |
+| Canonical | Aliases | DataFrame column type | Notes                                                                             |
 |-----------|---------|----------------|-----------------------------------------------------------------------------------|
 | `uuid`    | *none*  | `String`       | Read as text by default. Use a client-side parser to get `kotlin.uuid.Uuid`.      |
 | `xml`     | *none*  | `String`       |                                                                                   |
@@ -99,7 +99,7 @@ Case-insensitive `sqlTypeName` lookup selects a PostgreSQL-specific PGobject wra
 
 ## Network address types
 
-| Canonical    | Aliases | DataFrame type | Notes                                        |
+| Canonical    | Aliases | DataFrame column type | Notes                                        |
 |--------------|---------|----------------|----------------------------------------------|
 | `inet`       | *none*  | `String`       | IPv4 or IPv6 host / network.                 |
 | `cidr`       | *none*  | `String`       | IPv4 or IPv6 network.                        |
@@ -110,7 +110,7 @@ Case-insensitive `sqlTypeName` lookup selects a PostgreSQL-specific PGobject wra
 
 Range types are read as `String` (their canonical `[lo,hi)` text form). Parse client-side.
 
-| Canonical      | Aliases | DataFrame type | Notes                                                             |
+| Canonical      | Aliases | DataFrame column type | Notes                                                             |
 |----------------|---------|----------------|-------------------------------------------------------------------|
 | `int4range`    | *none*  | `String`       |                                                                   |
 | `int8range`    | *none*  | `String`       |                                                                   |
@@ -122,14 +122,14 @@ Range types are read as `String` (their canonical `[lo,hi)` text form). Parse cl
 
 ## Full-text search
 
-| Canonical  | Aliases | DataFrame type | Notes                          |
+| Canonical  | Aliases | DataFrame column type | Notes                          |
 |------------|---------|----------------|--------------------------------|
 | `tsvector` | *none*  | `String`       | Text search document.          |
 | `tsquery`  | *none*  | `String`       | Text search query.             |
 
 ## Object identifiers
 
-| Canonical          | Aliases | DataFrame type | Notes                                              |
+| Canonical          | Aliases | DataFrame column type | Notes                                              |
 |--------------------|---------|----------------|----------------------------------------------------|
 | `oid`              | *none*  | `Long`         | Underlying storage is 32-bit unsigned integer.     |
 | `regclass`         | *none*  | `String`       | Reported as text alias.                            |
@@ -137,7 +137,7 @@ Range types are read as `String` (their canonical `[lo,hi)` text form). Parse cl
 
 ## Other
 
-| Canonical            | Aliases   | DataFrame type          | Notes                                                                                                               |
+| Canonical            | Aliases   | DataFrame column type          | Notes                                                                                                               |
 |----------------------|-----------|-------------------------|---------------------------------------------------------------------------------------------------------------------|
 | `pg_lsn`             | *none*    | `String`                | Write-Ahead Log sequence number.                                                                                    |
 | `pg_snapshot`, `txid_snapshot` | *none* | `String`             | Snapshot info.                                                                                                      |
@@ -146,26 +146,31 @@ Range types are read as `String` (their canonical `[lo,hi)` text form). Parse cl
 
 ## PostgreSQL specifics
 
-- Type name lookup for PGobject types (`box`, `point`, `money`, ...) is
-  case-insensitive.
-- Composite (row) types like `ROW(a INTEGER, b VARCHAR(10))` are not mapped and read as raw
-  `String` (their canonical text form). See [Unsupported types](#unsupported-types).
-- User-defined `DOMAIN` types are transparent to the driver — the underlying primitive's
-  mapping applies.
-- Auto-incrementing `SERIAL` variants are `INTEGER` / `BIGINT` in the metadata; they are not
-  reported as a separate JDBC type.
+- Type name lookup for PGobject types (`box`, `point`, `money`, ...) is case-insensitive.
+- User-defined [`DOMAIN`](https://www.postgresql.org/docs/current/domains.html) types are
+  transparent at the JDBC layer — the underlying primitive's mapping applies.
+- Auto-incrementing [`SERIAL` variants](https://www.postgresql.org/docs/current/datatype-numeric.html#DATATYPE-SERIAL)
+  are `INTEGER` / `BIGINT` in the metadata — the sequence is a server-side default, not a
+  separate JDBC type.
+- Composite / anonymous [`ROW(...)`](https://www.postgresql.org/docs/current/rowtypes.html)
+  values come through the driver as a `PGobject` with `Types.OTHER` and fall through to the
+  default handler → column type is `Any`. Cast to text in your query
+  (e.g. `SELECT (row_col)::text`) or supply a [custom converter](readSqlFromCustomDatabase.md).
 
 ## Unsupported types
 
 The following types are not currently mapped to a dedicated Kotlin type; they are read as
-`String` (default fallback) or as the driver's raw form. Explicit support may be added
-later; for now, either cast in your query (e.g. `SELECT ST_AsText(geom)` / `field::text`)
-or supply a custom converter via [a custom DbType](readSqlFromCustomDatabase.md).
-
-- Composite (`ROW(...)`) and user-defined composite types.
-- Array types (`type[]`) — currently read as SQL `ARRAY` and post-processed to `Array<*>`,
-  but element types beyond the primitives listed here are not resolved.
-- `hstore` extension type.
-- PostGIS types (`geometry`, `geography`, ...) from the PostGIS extension.
-- Range / multi-range internal representation (read as text).
-- `bit(n)` / `bit varying(n)` (read as text).
+`Any` / `String` or as the driver's raw form. Explicit support may be added later; for now,
+cast in your query (e.g. `SELECT ST_AsText(geom)` / `field::text`) or supply a custom
+converter via [a custom DbType](readSqlFromCustomDatabase.md).
+
+- Composite (`ROW(...)`) and user-defined composite types — driver returns `PGobject`,
+  DataFrame column type is `Any`.
+- Array types (`type[]`) — read as SQL `ARRAY` and post-processed to `Array<*>`; element
+  types beyond the primitives listed here are not resolved.
+- [`hstore`](https://www.postgresql.org/docs/current/hstore.html) extension — driver returns
+  a `Map<String, String>` wrapped in `PGobject`; column type is `Any`.
+- [PostGIS](https://postgis.net/documentation/) types (`geometry`, `geography`, ...) —
+  driver returns `PGobject`; column type is `Any`.
+- Range / multi-range internal representation — read as text.
+- `bit(n)` / `bit varying(n)` — driver returns the string form `"0"`/`"1"`.
diff --git a/docs/StardustDocs/topics/readSqlTypeMapping_SQLite.md b/docs/StardustDocs/topics/readSqlTypeMapping_SQLite.md
index f4363daa85..ef4cd2c534 100644
--- a/docs/StardustDocs/topics/readSqlTypeMapping_SQLite.md
+++ b/docs/StardustDocs/topics/readSqlTypeMapping_SQLite.md
@@ -63,7 +63,7 @@ Nullable columns produce nullable Kotlin types (`Int?` instead of `Int`).
 
 Declared type contains `INT`.
 
-| Declared type                                     | DataFrame type | Notes                                                                                     |
+| Declared type                                     | DataFrame column type | Notes                                                                                     |
 |---------------------------------------------------|----------------|-------------------------------------------------------------------------------------------|
 | `INT`                                             | `Int`          |                                                                                           |
 | `INTEGER`                                         | `Int`          | Also used implicitly for `INTEGER PRIMARY KEY` (rowid alias).                             |
@@ -76,7 +76,7 @@ Declared type contains `INT`.
 
 Declared type contains `REAL`, `FLOA`, or `DOUB`.
 
-| Declared type                       | DataFrame type | Notes                                                                                       |
+| Declared type                       | DataFrame column type | Notes                                                                                       |
 |-------------------------------------|----------------|---------------------------------------------------------------------------------------------|
 | `REAL`, `FLOAT`                     | `Double`       | Note: not `Float`. Driver reports `java.lang.Double` for the stored value, which triggers the `Types.REAL/FLOAT if java.lang.Double -> Double` override. |
 | `DOUBLE`, `DOUBLE PRECISION`        | `Double`       |                                                                                             |
@@ -85,7 +85,7 @@ Declared type contains `REAL`, `FLOA`, or `DOUB`.
 
 Declared type contains `CHAR`, `CLOB`, or `TEXT`.
 
-| Declared type                       | DataFrame type   | Notes                                                                                    |
+| Declared type                       | DataFrame column type   | Notes                                                                                    |
 |-------------------------------------|------------------|------------------------------------------------------------------------------------------|
 | `TEXT`, `VARCHAR(n)`, `NVARCHAR(n)` | `String`         |                                                                                          |
 | `CHAR(n)`, `NCHAR(n)`               | `String`         |                                                                                          |
@@ -96,7 +96,7 @@ Declared type contains `CHAR`, `CLOB`, or `TEXT`.
 
 Declared type contains `BLOB` or the column has no declared type.
 
-| Declared type | DataFrame type | Notes                                              |
+| Declared type | DataFrame column type | Notes                                              |
 |---------------|----------------|----------------------------------------------------|
 | `BLOB`        | `ByteArray`    |                                                    |
 | *(none)*      | `ByteArray`    | Column with no declared type falls back to BLOB.   |
@@ -108,7 +108,7 @@ Declared type contains `BLOB` or the column has no declared type.
 The DataFrame column type is an idiomatic Kotlin date-time type; each row's value is
 converted from its storage class during preprocessing.
 
-| Declared type          | DataFrame type                       | Storage class → conversion                                                                                    |
+| Declared type          | DataFrame column type                       | Storage class → conversion                                                                                    |
 |------------------------|--------------------------------------|---------------------------------------------------------------------------------------------------------------|
 | `DATE`                 | `kotlinx.datetime.LocalDate`         | TEXT (ISO `YYYY-MM-DD`) → `LocalDate.parse`; INTEGER → date at Unix-seconds UTC; REAL → date at Julian day. |
 | `DATETIME`             | `kotlinx.datetime.LocalDateTime`     | TEXT (`YYYY-MM-DD HH:MM:SS` or `YYYY-MM-DDTHH:MM:SS`) → `LocalDateTime.parse`; INTEGER → date-time at Unix-seconds UTC; REAL → date-time at Julian day. |
@@ -134,7 +134,7 @@ val sqlite = Sqlite.withCustomConverters {
 
 ### BOOLEAN — INTEGER 0/1 converted to Boolean
 
-| Declared type    | Storage class     | DataFrame type | Notes                                                                                                                              |
+| Declared type    | Storage class     | DataFrame column type | Notes                                                                                                                              |
 |------------------|-------------------|----------------|------------------------------------------------------------------------------------------------------------------------------------|
 | `BOOLEAN`, `BIT` | INTEGER (0/1)     | `Boolean`      | The preprocessor treats non-zero as `true`, zero as `false`.                                                                        |
 | `BOOLEAN`, `BIT` | REAL              | `Boolean`      | Same convention (non-zero → `true`).                                                                                                |
@@ -147,7 +147,7 @@ val sqlite = Sqlite.withCustomConverters {
 `DECIMAL` and `NUMERIC` columns have no canonical numeric type; DataFrame reads the raw stored
 value as-is (`Int`, `Long`, or `Double` depending on how each row was inserted).
 
-| Declared type    | Storage class | DataFrame type          | Notes                                            |
+| Declared type    | Storage class | DataFrame column type          | Notes                                            |
 |------------------|---------------|-------------------------|--------------------------------------------------|
 | `NUMERIC`        | INTEGER       | `Int` / `Long`          | Follows the actual value's class.                |
 | `NUMERIC`        | REAL          | `Double`                |                                                  |
@@ -207,12 +207,13 @@ val df = DataFrame.readSqlTable(connection, "events", dbType = sqlite)
 
 ## SQLite specifics
 
-- **No canonicalisation** — the driver preserves the declared type verbatim in
-  `sqlTypeName`. Two columns declared `INTEGER` and `TINYINT` both have INTEGER affinity but
-  distinct `sqlTypeName` values in metadata.
-- **Xerial's `rs.getObject(int)` returns exactly one of `Integer` / `Long` / `Double` /
-  `String` / `byte[]` / `null`.** No `Timestamp` / `LocalDate` / `Boolean` / `Blob` ever
-  reaches DataFrame from a SQLite driver — hence the SQLite adapter needs to translate.
+- **No canonicalisation** — the [Xerial JDBC driver](https://github.com/xerial/sqlite-jdbc)
+  preserves the declared type verbatim in `sqlTypeName`. Two columns declared `INTEGER` and
+  `TINYINT` both have INTEGER affinity but distinct `sqlTypeName` values in metadata.
+- **`rs.getObject(int)` returns exactly one of `Integer` / `Long` / `Double` / `String` /
+  `byte[]` / `null`.** No `Timestamp` / `LocalDate` / `Boolean` / `Blob` ever reaches
+  DataFrame from a SQLite driver — hence the SQLite adapter needs to translate. See
+  Xerial's [datatype mapping](https://github.com/xerial/sqlite-jdbc/wiki#datatype-mapping).
 - **`DATE` / `DATETIME` / `TIME` / `TIMESTAMP` are converted from storage class to an idiomatic
   Kotlin date-time type.** ISO strings, Unix epoch integers, and Julian days are all normalised
   to `kotlinx.datetime.LocalDate` / `LocalDateTime` / `LocalTime` / `kotlin.time.Instant` in

From d5f268c46e9d7e93faaf120d19dbd96e3a8147fd Mon Sep 17 00:00:00 2001
From: "andrei.kislitsyn" <kisandy@yandex.ru>
Date: Wed, 19 Aug 2026 17:10:22 +0400
Subject: [PATCH 09/10] Expand SQLite JDBC type mapping documentation: clarify
 column type handling, refine examples, and standardize terminology. Add
 support for `CLOB` type conversion.

---
 .../kotlinx/dataframe/io/db/Sqlite.kt         |   5 +
 .../kotlinx/dataframe/io/db/jdbcTypesTest.kt  |   4 +-
 .../topics/readSqlTypeMapping_MariaDB.md      |  17 +-
 .../topics/readSqlTypeMapping_MsSql.md        |   2 -
 .../topics/readSqlTypeMapping_MySQL.md        |   7 +-
 .../topics/readSqlTypeMapping_PostgreSQL.md   | 177 +++++++++---------
 .../topics/readSqlTypeMapping_SQLite.md       | 140 ++++++++------
 7 files changed, 181 insertions(+), 171 deletions(-)

diff --git a/dataframe-jdbc/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/db/Sqlite.kt b/dataframe-jdbc/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/db/Sqlite.kt
index 778bd02539..7e96c5fb1d 100644
--- a/dataframe-jdbc/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/db/Sqlite.kt
+++ b/dataframe-jdbc/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/db/Sqlite.kt
@@ -357,6 +357,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)
     }
diff --git a/dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/jdbcTypesTest.kt b/dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/jdbcTypesTest.kt
index 8260ab1236..fa5a82ef2a 100644
--- a/dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/jdbcTypesTest.kt
+++ b/dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/db/jdbcTypesTest.kt
@@ -564,9 +564,7 @@ internal val sqliteTextAffinityMappings: List<TypeMapping> = listOf(
     TypeMapping("NVARCHAR", Types.VARCHAR, "java.lang.String", typeOf<String>()),
     TypeMapping("CHAR", Types.CHAR, "java.lang.String", typeOf<String>()),
     TypeMapping("NCHAR", Types.CHAR, "java.lang.String", typeOf<String>()),
-    // CLOB falls through to `defaultJdbcTypeToKTypeMapping[Types.CLOB]` (= java.sql.Clob),
-    // regardless of the reported javaClassName.
-    TypeMapping("CLOB", Types.CLOB, "java.lang.String", typeOf<java.sql.Clob>()),
+    TypeMapping("CLOB", Types.CLOB, "java.lang.String", typeOf<String>()),
 )
 
 /** BLOB affinity — declared BLOB storing binary bytes. */
diff --git a/docs/StardustDocs/topics/readSqlTypeMapping_MariaDB.md b/docs/StardustDocs/topics/readSqlTypeMapping_MariaDB.md
index caa60c0f59..d8111151b5 100644
--- a/docs/StardustDocs/topics/readSqlTypeMapping_MariaDB.md
+++ b/docs/StardustDocs/topics/readSqlTypeMapping_MariaDB.md
@@ -71,13 +71,13 @@ Nullable columns produce nullable Kotlin types (`Int?` instead of `Int`).
 
 ## JSON and UUID
 
-| Canonical  | Aliases | DataFrame column type | Notes                                                                                      |
-|------------|---------|-----------------------|--------------------------------------------------------------------------------------------|
-| `JSON`     | *none*  | `String`              | Physically stored as `LONGTEXT` in MariaDB; JDBC reports `LONGVARCHAR` → `String`.         |
-| `UUID`     | *none*  | `String`              | Available in MariaDB 10.7+. Read as text.                                                  |
-| `INET4`    | *none*  | `String`              | Available in MariaDB 10.10+.                                                               |
-| `INET6`    | *none*  | `String`              | Available in MariaDB 10.10+.                                                               |
-| `ROW(...)` | *none*  | *unsupported*         | Anonymous row types are not currently mapped; see [Unsupported types](#unsupported-types). |
+| Canonical  | Aliases | DataFrame column type | Notes                                                                                        |
+|------------|---------|-----------------------|----------------------------------------------------------------------------------------------|
+| `JSON`     | *none*  | `String`              | Physically stored as `LONGTEXT` in MariaDB; JDBC reports `LONGVARCHAR` → `String`.           |
+| `UUID`     | *none*  | `String`              | Available in MariaDB 10.7+. Read as text. Use [`parse`](parse.md) to get `kotlin.uuid.Uuid`. |
+| `INET4`    | *none*  | `String`              | Available in MariaDB 10.10+.                                                                 |
+| `INET6`    | *none*  | `String`              | Available in MariaDB 10.10+.                                                                 |
+| `ROW(...)` | *none*  | *unsupported*         | Anonymous row types are not currently mapped; see [Unsupported types](#unsupported-types).   |
 
 ## Spatial types
 
@@ -115,5 +115,4 @@ All spatial types are read as `ByteArray` (WKB / EWKB binary as reported by the
   as `String`.
 - [`VECTOR`](https://mariadb.com/kb/en/vector-overview/) (MariaDB 11.7+); read as `ByteArray`
   (raw binary storage).
-- Native representations of spatial types; read as raw WKB `ByteArray`. Parse with a
-  client-side geometry library.
+- Native representations of spatial types; read as raw WKB `ByteArray`.
diff --git a/docs/StardustDocs/topics/readSqlTypeMapping_MsSql.md b/docs/StardustDocs/topics/readSqlTypeMapping_MsSql.md
index 5573717368..f7daa63dee 100644
--- a/docs/StardustDocs/topics/readSqlTypeMapping_MsSql.md
+++ b/docs/StardustDocs/topics/readSqlTypeMapping_MsSql.md
@@ -103,8 +103,6 @@ Nullable columns produce nullable Kotlin types (`Int?` instead of `Int`).
 - [`float(n)`](https://learn.microsoft.com/en-us/sql/t-sql/data-types/float-and-real-transact-sql)
   with `n <= 24` returns `Float`; `n >= 25` returns `Double`. `float` alone means `float(53)`
   and returns `Double`. `real` is `float(24)` and returns `Float`.
-- MS SQL Server does not need any DB-specific overrides in DataFrame — the default `DbType`
-  mapping is used as-is (see the "common SQL types" case in `JdbcTypesTest`).
 
 ## Unsupported types
 
diff --git a/docs/StardustDocs/topics/readSqlTypeMapping_MySQL.md b/docs/StardustDocs/topics/readSqlTypeMapping_MySQL.md
index 136e0dba5a..2d709c23e3 100644
--- a/docs/StardustDocs/topics/readSqlTypeMapping_MySQL.md
+++ b/docs/StardustDocs/topics/readSqlTypeMapping_MySQL.md
@@ -79,7 +79,6 @@ Nullable columns produce nullable Kotlin types (`Int?` instead of `Int`).
 ## Spatial types
 
 All spatial types are read as `ByteArray` (WKB / EWKB binary as reported by the driver).
-Parse them with a client-side geometry library.
 
 | Canonical            | Aliases | DataFrame column type | Notes |
 |----------------------|---------|-----------------------|-------|
@@ -106,13 +105,9 @@ Parse them with a client-side geometry library.
 - `TINYINT(1)` is a special case: MySQL Connector/J reports it as `Types.BIT` (→ `Boolean`) by
   default because of the driver's [`tinyInt1isBit`](https://dev.mysql.com/doc/connector-j/en/connector-j-connp-props-datatypes.html)
   property. Set `tinyInt1isBit=false` in the JDBC URL to read it as `Int` instead.
-- MySQL 8.0 does **not** have native `UUID` / `INET4` / `INET6` types (unlike MariaDB); use
-  `CHAR(36)` or `BINARY(16)` and convert client-side — see
-  [MySQL 8.0 Data Types](https://dev.mysql.com/doc/refman/8.0/en/data-types.html).
 
 ## Unsupported types
 
-- Spatial types have no native Kotlin representation — read as raw WKB `ByteArray`. Parse
-  with a client-side geometry library.
+- Spatial types have no native Kotlin representation — read as raw WKB `ByteArray`.
 - [`VECTOR`](https://dev.mysql.com/doc/refman/9.0/en/vector.html) (MySQL 9.0+); the driver
   reports it as a binary type, so DataFrame reads it as `ByteArray`.
diff --git a/docs/StardustDocs/topics/readSqlTypeMapping_PostgreSQL.md b/docs/StardustDocs/topics/readSqlTypeMapping_PostgreSQL.md
index f3fb13f407..7799b2c25f 100644
--- a/docs/StardustDocs/topics/readSqlTypeMapping_PostgreSQL.md
+++ b/docs/StardustDocs/topics/readSqlTypeMapping_PostgreSQL.md
@@ -15,134 +15,134 @@ and driver caveats.
 </link-summary>
 
 The tables below list every PostgreSQL column type ([PostgreSQL Data Types](https://www.postgresql.org/docs/current/datatype.html))
-and the Kotlin type produced when the column is read into a DataFrame. Aliases are
-canonicalized by PostgreSQL at `CREATE TABLE` time, so DataFrame only ever sees the canonical
+and the Kotlin type produced when the column is read into a DataFrame. PostgreSQL 
+canonicalizes aliases at `CREATE TABLE` time, so DataFrame only ever sees the canonical
 type; they are listed in the same row as the canonical type for reference.
 
 Nullable columns produce nullable Kotlin types (`Int?` instead of `Int`).
 
 ## Numeric types
 
-| Canonical           | Aliases            | DataFrame column type          | Notes                                                                                     |
-|---------------------|--------------------|-------------------------|-------------------------------------------------------------------------------------------|
-| `smallint`          | `int2`             | `Int`                   | 2-byte signed integer.                                                                    |
-| `integer`           | `int`, `int4`      | `Int`                   | 4-byte signed integer.                                                                    |
-| `bigint`            | `int8`             | `Long`                  | 8-byte signed integer.                                                                    |
-| `smallserial`       | `serial2`          | `Int`                   | Auto-incrementing `smallint` backed by a sequence.                                        |
-| `serial`            | `serial4`          | `Int`                   | Auto-incrementing `integer`.                                                              |
-| `bigserial`         | `serial8`          | `Long`                  | Auto-incrementing `bigint`.                                                               |
-| `numeric[(p,s)]`    | `decimal[(p,s)]`   | `java.math.BigDecimal`  | Arbitrary-precision decimal.                                                              |
-| `real`              | `float4`           | `Float`                 | 4-byte float.                                                                             |
-| `double precision`  | `float8`           | `Double`                | 8-byte float.                                                                             |
-| `money`             | *none*             | `org.postgresql.util.PGmoney` | PostgreSQL override: read as `PGmoney`.                                             |
+| Canonical          | Aliases          | DataFrame column type         | Notes                                              |
+|--------------------|------------------|-------------------------------|----------------------------------------------------|
+| `smallint`         | `int2`           | `Int`                         | 2-byte signed integer.                             |
+| `integer`          | `int`, `int4`    | `Int`                         | 4-byte signed integer.                             |
+| `bigint`           | `int8`           | `Long`                        | 8-byte signed integer.                             |
+| `smallserial`      | `serial2`        | `Int`                         | Auto-incrementing `smallint` backed by a sequence. |
+| `serial`           | `serial4`        | `Int`                         | Auto-incrementing `integer`.                       |
+| `bigserial`        | `serial8`        | `Long`                        | Auto-incrementing `bigint`.                        |
+| `numeric[(p,s)]`   | `decimal[(p,s)]` | `java.math.BigDecimal`        | Arbitrary-precision decimal.                       |
+| `real`             | `float4`         | `Float`                       | 4-byte float.                                      |
+| `double precision` | `float8`         | `Double`                      | 8-byte float.                                      |
+| `money`            | *none*           | `org.postgresql.util.PGmoney` | PostgreSQL override: read as `PGmoney`.            |
 
 ## Boolean
 
 | Canonical | Aliases | DataFrame column type | Notes |
-|-----------|---------|----------------|-------|
-| `boolean` | `bool`  | `Boolean`      |       |
+|-----------|---------|-----------------------|-------|
+| `boolean` | `bool`  | `Boolean`             |       |
 
 ## Character types
 
-| Canonical            | Aliases                   | DataFrame column type | Notes                          |
-|----------------------|---------------------------|----------------|--------------------------------|
-| `character(n)`       | `char(n)`                 | `String`       | Fixed-length text.             |
-| `character varying(n)` | `varchar(n)`            | `String`       | Variable-length text.          |
-| `text`               | *none*                    | `String`       | Unbounded text.                |
+| Canonical              | Aliases      | DataFrame column type | Notes                 |
+|------------------------|--------------|-----------------------|-----------------------|
+| `character(n)`         | `char(n)`    | `String`              | Fixed-length text.    |
+| `character varying(n)` | `varchar(n)` | `String`              | Variable-length text. |
+| `text`                 | *none*       | `String`              | Unbounded text.       |
 
 ## Binary
 
-| Canonical | Aliases | DataFrame column type | Notes                                                                       |
-|-----------|---------|----------------|-----------------------------------------------------------------------------|
-| `bytea`   | *none*  | `ByteArray`    | Raw binary. Driver reports it as `[B` (`byte[]`).                           |
+| Canonical | Aliases | DataFrame column type | Notes                                             |
+|-----------|---------|-----------------------|---------------------------------------------------|
+| `bytea`   | *none*  | `ByteArray`           | Raw binary. Driver reports it as `[B` (`byte[]`). |
 
 ## Date and time types
 
-| Canonical                             | Aliases          | DataFrame column type              | Notes                                                                     |
-|---------------------------------------|------------------|-----------------------------|---------------------------------------------------------------------------|
-| `date`                                | *none*           | `java.util.Date`            |                                                                           |
-| `time [without time zone] [(p)]`      | *none*           | `java.sql.Time`             | `p` is fractional-second precision (0–6).                                 |
-| `time with time zone [(p)]`           | `timetz`         | `java.time.OffsetTime`      |                                                                           |
-| `timestamp [without time zone] [(p)]` | *none*           | `kotlin.time.Instant`       | Preprocessed from `java.sql.Timestamp`.                                   |
-| `timestamp with time zone [(p)]`      | `timestamptz`    | `java.time.OffsetDateTime`  |                                                                           |
-| `interval [fields] [(p)]`             | *none*           | `org.postgresql.util.PGInterval` | PostgreSQL override.                                                 |
+| Canonical                             | Aliases       | DataFrame column type            | Notes                                     |
+|---------------------------------------|---------------|----------------------------------|-------------------------------------------|
+| `date`                                | *none*        | `java.util.Date`                 |                                           |
+| `time [without time zone] [(p)]`      | *none*        | `java.sql.Time`                  | `p` is fractional-second precision (0–6). |
+| `time with time zone [(p)]`           | `timetz`      | `java.time.OffsetTime`           |                                           |
+| `timestamp [without time zone] [(p)]` | *none*        | `kotlin.time.Instant`            | Preprocessed from `java.sql.Timestamp`.   |
+| `timestamp with time zone [(p)]`      | `timestamptz` | `java.time.OffsetDateTime`       |                                           |
+| `interval [fields] [(p)]`             | *none*        | `org.postgresql.util.PGInterval` | PostgreSQL override.                      |
 
 ## Geometric types (PostgreSQL overrides)
 
 Case-insensitive `sqlTypeName` lookup selects a PostgreSQL-specific PGobject wrapper.
 
-| Canonical | Aliases | DataFrame column type                              | Notes            |
-|-----------|---------|---------------------------------------------|------------------|
-| `box`     | *none*  | `org.postgresql.geometric.PGbox`            | Rectangle        |
-| `circle`  | *none*  | `org.postgresql.geometric.PGcircle`         | Circle           |
-| `line`    | *none*  | `org.postgresql.geometric.PGline`           | Infinite line    |
-| `lseg`    | *none*  | `org.postgresql.geometric.PGlseg`           | Line segment     |
-| `path`    | *none*  | `org.postgresql.geometric.PGpath`           | Open or closed   |
-| `point`   | *none*  | `org.postgresql.geometric.PGpoint`          | 2-D point        |
-| `polygon` | *none*  | `org.postgresql.geometric.PGpolygon`        | Polygon          |
+| Canonical | Aliases | DataFrame column type                | Notes          |
+|-----------|---------|--------------------------------------|----------------|
+| `box`     | *none*  | `org.postgresql.geometric.PGbox`     | Rectangle      |
+| `circle`  | *none*  | `org.postgresql.geometric.PGcircle`  | Circle         |
+| `line`    | *none*  | `org.postgresql.geometric.PGline`    | Infinite line  |
+| `lseg`    | *none*  | `org.postgresql.geometric.PGlseg`    | Line segment   |
+| `path`    | *none*  | `org.postgresql.geometric.PGpath`    | Open or closed |
+| `point`   | *none*  | `org.postgresql.geometric.PGpoint`   | 2-D point      |
+| `polygon` | *none*  | `org.postgresql.geometric.PGpolygon` | Polygon        |
 
 ## Bit strings
 
-| Canonical         | Aliases   | DataFrame column type | Notes                                                                    |
-|-------------------|-----------|----------------|--------------------------------------------------------------------------|
-| `bit(n)`          | *none*    | `String`       | Reported by the driver as `String` — `"0"` and `"1"` characters.         |
-| `bit varying(n)`  | `varbit`  | `String`       |                                                                          |
+| Canonical        | Aliases  | DataFrame column type | Notes                                                            |
+|------------------|----------|-----------------------|------------------------------------------------------------------|
+| `bit(n)`         | *none*   | `String`              | Reported by the driver as `String` — `"0"` and `"1"` characters. |
+| `bit varying(n)` | `varbit` | `String`              |                                                                  |
 
 ## UUID, XML, JSON
 
-| Canonical | Aliases | DataFrame column type | Notes                                                                             |
-|-----------|---------|----------------|-----------------------------------------------------------------------------------|
-| `uuid`    | *none*  | `String`       | Read as text by default. Use a client-side parser to get `kotlin.uuid.Uuid`.      |
-| `xml`     | *none*  | `String`       |                                                                                   |
-| `json`    | *none*  | `String`       | Raw JSON text.                                                                    |
-| `jsonb`   | *none*  | `String`       | Binary-stored JSON, read as text.                                                 |
+| Canonical | Aliases | DataFrame column type | Notes                                                                                 |
+|-----------|---------|-----------------------|---------------------------------------------------------------------------------------|
+| `uuid`    | *none*  | `String`              | Read as text by default (for now). Use [`parse`](parse.md) to get `kotlin.uuid.Uuid`. |
+| `xml`     | *none*  | `String`              |                                                                                       |
+| `json`    | *none*  | `String`              | Raw JSON text.                                                                        |
+| `jsonb`   | *none*  | `String`              | Binary-stored JSON, read as text.                                                     |
 
 ## Network address types
 
-| Canonical    | Aliases | DataFrame column type | Notes                                        |
-|--------------|---------|----------------|----------------------------------------------|
-| `inet`       | *none*  | `String`       | IPv4 or IPv6 host / network.                 |
-| `cidr`       | *none*  | `String`       | IPv4 or IPv6 network.                        |
-| `macaddr`    | *none*  | `String`       | MAC address (6 bytes).                       |
-| `macaddr8`   | *none*  | `String`       | MAC address (8 bytes / EUI-64).              |
+| Canonical  | Aliases | DataFrame column type | Notes                           |
+|------------|---------|-----------------------|---------------------------------|
+| `inet`     | *none*  | `String`              | IPv4 or IPv6 host / network.    |
+| `cidr`     | *none*  | `String`              | IPv4 or IPv6 network.           |
+| `macaddr`  | *none*  | `String`              | MAC address (6 bytes).          |
+| `macaddr8` | *none*  | `String`              | MAC address (8 bytes / EUI-64). |
 
 ## Range types
 
-Range types are read as `String` (their canonical `[lo,hi)` text form). Parse client-side.
+Range types are read as `String` (their canonical `[lo,hi)` text form).
 
-| Canonical      | Aliases | DataFrame column type | Notes                                                             |
-|----------------|---------|----------------|-------------------------------------------------------------------|
-| `int4range`    | *none*  | `String`       |                                                                   |
-| `int8range`    | *none*  | `String`       |                                                                   |
-| `numrange`     | *none*  | `String`       |                                                                   |
-| `tsrange`      | *none*  | `String`       |                                                                   |
-| `tstzrange`    | *none*  | `String`       |                                                                   |
-| `daterange`    | *none*  | `String`       |                                                                   |
-| `int4multirange`, `int8multirange`, `nummultirange`, `tsmultirange`, `tstzmultirange`, `datemultirange` | *none* | `String` | Multi-ranges (PG 14+). Read as text. |
+| Canonical                                                                                               | Aliases | DataFrame column type | Notes                                |
+|---------------------------------------------------------------------------------------------------------|---------|-----------------------|--------------------------------------|
+| `int4range`                                                                                             | *none*  | `String`              |                                      |
+| `int8range`                                                                                             | *none*  | `String`              |                                      |
+| `numrange`                                                                                              | *none*  | `String`              |                                      |
+| `tsrange`                                                                                               | *none*  | `String`              |                                      |
+| `tstzrange`                                                                                             | *none*  | `String`              |                                      |
+| `daterange`                                                                                             | *none*  | `String`              |                                      |
+| `int4multirange`, `int8multirange`, `nummultirange`, `tsmultirange`, `tstzmultirange`, `datemultirange` | *none*  | `String`              | Multi-ranges (PG 14+). Read as text. |
 
 ## Full-text search
 
-| Canonical  | Aliases | DataFrame column type | Notes                          |
-|------------|---------|----------------|--------------------------------|
-| `tsvector` | *none*  | `String`       | Text search document.          |
-| `tsquery`  | *none*  | `String`       | Text search query.             |
+| Canonical  | Aliases | DataFrame column type | Notes                 |
+|------------|---------|-----------------------|-----------------------|
+| `tsvector` | *none*  | `String`              | Text search document. |
+| `tsquery`  | *none*  | `String`              | Text search query.    |
 
 ## Object identifiers
 
-| Canonical          | Aliases | DataFrame column type | Notes                                              |
-|--------------------|---------|----------------|----------------------------------------------------|
-| `oid`              | *none*  | `Long`         | Underlying storage is 32-bit unsigned integer.     |
-| `regclass`         | *none*  | `String`       | Reported as text alias.                            |
-| `regconfig`, `regdictionary`, `regoper`, `regoperator`, `regproc`, `regprocedure`, `regrole`, `regnamespace`, `regtype`, `regcollation`, `regnamespace`, `regcollation` | *none* | `String` | Various OID aliases. |
+| Canonical                                                                                                                                                               | Aliases | DataFrame column type | Notes                                          |
+|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|-----------------------|------------------------------------------------|
+| `oid`                                                                                                                                                                   | *none*  | `Long`                | Underlying storage is 32-bit unsigned integer. |
+| `regclass`                                                                                                                                                              | *none*  | `String`              | Reported as text alias.                        |
+| `regconfig`, `regdictionary`, `regoper`, `regoperator`, `regproc`, `regprocedure`, `regrole`, `regnamespace`, `regtype`, `regcollation`, `regnamespace`, `regcollation` | *none*  | `String`              | Various OID aliases.                           |
 
 ## Other
 
-| Canonical            | Aliases   | DataFrame column type          | Notes                                                                                                               |
-|----------------------|-----------|-------------------------|---------------------------------------------------------------------------------------------------------------------|
-| `pg_lsn`             | *none*    | `String`                | Write-Ahead Log sequence number.                                                                                    |
-| `pg_snapshot`, `txid_snapshot` | *none* | `String`             | Snapshot info.                                                                                                      |
-| user-defined `ENUM`  | *none*    | `String`                | User-declared enum types are read as their string label.                                                            |
-| user-defined `DOMAIN`| *none*    | as the underlying type  | Domains are transparent; the underlying type's mapping applies.                                                     |
+| Canonical                      | Aliases | DataFrame column type  | Notes                                                           |
+|--------------------------------|---------|------------------------|-----------------------------------------------------------------|
+| `pg_lsn`                       | *none*  | `String`               | Write-Ahead Log sequence number.                                |
+| `pg_snapshot`, `txid_snapshot` | *none*  | `String`               | Snapshot info.                                                  |
+| user-defined `ENUM`            | *none*  | `String`               | User-declared enum types are read as their string label.        |
+| user-defined `DOMAIN`          | *none*  | as the underlying type | Domains are transparent; the underlying type's mapping applies. |
 
 ## PostgreSQL specifics
 
@@ -154,23 +154,20 @@ Range types are read as `String` (their canonical `[lo,hi)` text form). Parse cl
   separate JDBC type.
 - Composite / anonymous [`ROW(...)`](https://www.postgresql.org/docs/current/rowtypes.html)
   values come through the driver as a `PGobject` with `Types.OTHER` and fall through to the
-  default handler → column type is `Any`. Cast to text in your query
-  (e.g. `SELECT (row_col)::text`) or supply a [custom converter](readSqlFromCustomDatabase.md).
+  default handler → column type is `Any`.
 
 ## Unsupported types
 
 The following types are not currently mapped to a dedicated Kotlin type; they are read as
-`Any` / `String` or as the driver's raw form. Explicit support may be added later; for now,
-cast in your query (e.g. `SELECT ST_AsText(geom)` / `field::text`) or supply a custom
-converter via [a custom DbType](readSqlFromCustomDatabase.md).
+`Any` / `String` or as the driver's raw form. Explicit support may be added later;
 
-- Composite (`ROW(...)`) and user-defined composite types — driver returns `PGobject`,
+- Composite (`ROW(...)`) and user-defined composite types — a driver returns `PGobject`,
   DataFrame column type is `Any`.
 - Array types (`type[]`) — read as SQL `ARRAY` and post-processed to `Array<*>`; element
   types beyond the primitives listed here are not resolved.
 - [`hstore`](https://www.postgresql.org/docs/current/hstore.html) extension — driver returns
-  a `Map<String, String>` wrapped in `PGobject`; column type is `Any`.
+  a `Map<String, String>` wrapped in `PGobject`; a column type is `Any`.
 - [PostGIS](https://postgis.net/documentation/) types (`geometry`, `geography`, ...) —
-  driver returns `PGobject`; column type is `Any`.
+  a driver returns `PGobject`; a column type is `Any`.
 - Range / multi-range internal representation — read as text.
 - `bit(n)` / `bit varying(n)` — driver returns the string form `"0"`/`"1"`.
diff --git a/docs/StardustDocs/topics/readSqlTypeMapping_SQLite.md b/docs/StardustDocs/topics/readSqlTypeMapping_SQLite.md
index ef4cd2c534..4a0fc7ffaf 100644
--- a/docs/StardustDocs/topics/readSqlTypeMapping_SQLite.md
+++ b/docs/StardustDocs/topics/readSqlTypeMapping_SQLite.md
@@ -27,15 +27,15 @@ column type is used only as a hint via
 | `REAL`, `FLOA`, `DOUB`        | `REAL`     |
 | anything else                 | `NUMERIC`  |
 
-**Unlike the other databases in this documentation, SQLite does NOT canonicalize declared
+**Unlike the other databases supported in Kotlin DataFrame, SQLite does NOT canonicalize declared
 types.** `sqlTypeName` in the driver's metadata is byte-for-byte what you wrote in
 `CREATE TABLE`. So `INT8`, `INTEGER`, `TINYINT`, `MEDIUMINT`, `UNSIGNED BIG INT` all share
-INTEGER affinity but each keeps its literal declared name. There is no separate alias
+INTEGER affinity, but each keeps its literal declared name. There is no separate alias
 table — every declared name is resolved directly via the affinity tables below.
 
 Because SQLite is dynamically typed, the Xerial JDBC driver reports `getColumnClassName`
 based on the **actual stored value in the current row**, not on the declared column type. The
-raw values returned by `rs.getObject(int)` therefore fall into a fixed set — Xerial produces
+raw values returned by `rs.getObject(int)` therefore fall into a fixed set — driver produces
 exactly one of `Integer` / `Long` / `Double` / `String` / `byte[]` / `null`, chosen per row
 from the storage class of that value.
 
@@ -50,12 +50,14 @@ DataFrame's SQLite handler resolves each column in the following order:
    `LocalDate`/`LocalDateTime`/`Instant.parse`; Unix INTEGER → epoch seconds; Julian REAL → date
    via the Julian-day formula). This gives one stable Kotlin type per column even when values
    are stored in mixed forms.
-3. **`BOOLEAN` / `BIT`** — Xerial reports `Types.BOOLEAN` but `rs.getObject` returns Integer
-   (0/1). A preprocessor converts every raw value (Int, Long, Double, or `"true"`/`"1"`/`"y"`
-   String) to a real Kotlin `Boolean`.
+3. **`BOOLEAN` / `BIT`** — the driver reports `Types.BOOLEAN` but `rs.getObject` returns Integer
+   (`0`/`1`). A preprocessor converts every raw value (Int, Long, Double, or `"true"`/`"1"`/`"y"`
+   String) to an actual Kotlin `Boolean`.
 4. **`DECIMAL` / `NUMERIC`** — no canonical numeric type; DataFrame trusts the driver-reported
    class of each column (`Int` / `Long` / `Double` / `ByteArray` / `String`).
-5. **Everything else** falls through to the base `DbType` end-to-end mapping.
+5. **Everything else** falls through to the base `DbType` end-to-end mapping. Note that
+   DataFrame may expect a special type for some SQL type names (for example, `UUID`), while the Xerial driver only provides primitives.
+   Consider using [custom converters](#custom-converters) to handle these cases.
 
 Nullable columns produce nullable Kotlin types (`Int?` instead of `Int`).
 
@@ -63,43 +65,42 @@ Nullable columns produce nullable Kotlin types (`Int?` instead of `Int`).
 
 Declared type contains `INT`.
 
-| Declared type                                     | DataFrame column type | Notes                                                                                     |
-|---------------------------------------------------|----------------|-------------------------------------------------------------------------------------------|
-| `INT`                                             | `Int`          |                                                                                           |
-| `INTEGER`                                         | `Int`          | Also used implicitly for `INTEGER PRIMARY KEY` (rowid alias).                             |
-| `TINYINT`                                         | `Int`          |                                                                                           |
-| `SMALLINT`, `INT2`                                | `Int`          |                                                                                           |
-| `MEDIUMINT`                                       | `Int`          |                                                                                           |
-| `BIGINT`, `INT8`, `UNSIGNED BIG INT`              | `Long`         | Xerial reports `Types.BIGINT`; default map returns `Long`.                                |
+| Declared type                        | DataFrame column type | Notes                                                         |
+|--------------------------------------|-----------------------|---------------------------------------------------------------|
+| `INT`                                | `Int`                 |                                                               |
+| `INTEGER`                            | `Int`                 | Also used implicitly for `INTEGER PRIMARY KEY` (rowid alias). |
+| `TINYINT`                            | `Int`                 |                                                               |
+| `SMALLINT`, `INT2`                   | `Int`                 |                                                               |
+| `MEDIUMINT`                          | `Int`                 |                                                               |
+| `BIGINT`, `INT8`, `UNSIGNED BIG INT` | `Long`                | Xerial reports `Types.BIGINT`; default map returns `Long`.    |
 
 ## REAL affinity
 
 Declared type contains `REAL`, `FLOA`, or `DOUB`.
 
-| Declared type                       | DataFrame column type | Notes                                                                                       |
-|-------------------------------------|----------------|---------------------------------------------------------------------------------------------|
-| `REAL`, `FLOAT`                     | `Double`       | Note: not `Float`. Driver reports `java.lang.Double` for the stored value, which triggers the `Types.REAL/FLOAT if java.lang.Double -> Double` override. |
-| `DOUBLE`, `DOUBLE PRECISION`        | `Double`       |                                                                                             |
+| Declared type                | DataFrame column type | Notes                                                                                                                                                    |
+|------------------------------|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `REAL`, `FLOAT`              | `Double`              | Note: not `Float`. Driver reports `java.lang.Double` for the stored value, which triggers the `Types.REAL/FLOAT if java.lang.Double -> Double` override. |
+| `DOUBLE`, `DOUBLE PRECISION` | `Double`              |                                                                                                                                                          |
 
 ## TEXT affinity
 
 Declared type contains `CHAR`, `CLOB`, or `TEXT`.
 
-| Declared type                       | DataFrame column type   | Notes                                                                                    |
-|-------------------------------------|------------------|------------------------------------------------------------------------------------------|
-| `TEXT`, `VARCHAR(n)`, `NVARCHAR(n)` | `String`         |                                                                                          |
-| `CHAR(n)`, `NCHAR(n)`               | `String`         |                                                                                          |
-| `VARYING CHARACTER(n)`, `NATIVE CHARACTER(n)`, `CHARACTER(n)` | `String` | All fall under TEXT affinity via the `CHAR` substring.                             |
-| `CLOB`                              | `java.sql.Clob`  | Follows the default JDBC mapping; the actual stored value is text.                       |
+| Declared type                                                 | DataFrame column type | Notes |
+|---------------------------------------------------------------|-----------------------|-------|
+| `TEXT`, `VARCHAR(n)`, `NVARCHAR(n)`, `CLOB`                   | `String`              |       |
+| `CHAR(n)`, `NCHAR(n)`                                         | `String`              |       |
+| `VARYING CHARACTER(n)`, `NATIVE CHARACTER(n)`, `CHARACTER(n)` | `String`              |       |
 
 ## BLOB affinity
 
 Declared type contains `BLOB` or the column has no declared type.
 
-| Declared type | DataFrame column type | Notes                                              |
-|---------------|----------------|----------------------------------------------------|
-| `BLOB`        | `ByteArray`    |                                                    |
-| *(none)*      | `ByteArray`    | Column with no declared type falls back to BLOB.   |
+| Declared type | DataFrame column type | Notes                                            |
+|---------------|-----------------------|--------------------------------------------------|
+| `BLOB`        | `ByteArray`           |                                                  |
+| *(none)*      | `ByteArray`           | Column with no declared type falls back to BLOB. |
 
 ## NUMERIC affinity (fallback for everything else)
 
@@ -108,12 +109,12 @@ Declared type contains `BLOB` or the column has no declared type.
 The DataFrame column type is an idiomatic Kotlin date-time type; each row's value is
 converted from its storage class during preprocessing.
 
-| Declared type          | DataFrame column type                       | Storage class → conversion                                                                                    |
-|------------------------|--------------------------------------|---------------------------------------------------------------------------------------------------------------|
-| `DATE`                 | `kotlinx.datetime.LocalDate`         | TEXT (ISO `YYYY-MM-DD`) → `LocalDate.parse`; INTEGER → date at Unix-seconds UTC; REAL → date at Julian day. |
-| `DATETIME`             | `kotlinx.datetime.LocalDateTime`     | TEXT (`YYYY-MM-DD HH:MM:SS` or `YYYY-MM-DDTHH:MM:SS`) → `LocalDateTime.parse`; INTEGER → date-time at Unix-seconds UTC; REAL → date-time at Julian day. |
-| `TIME`                 | `kotlinx.datetime.LocalTime`         | TEXT (`HH:MM:SS` or `HH:MM:SS.SSS`) → `LocalTime.parse`; INTEGER → seconds since midnight; REAL → seconds since midnight (fractional part ignored). |
-| `TIMESTAMP`            | `kotlin.time.Instant`                | TEXT (ISO) → `Instant.parse`; INTEGER → `Instant.fromEpochSeconds` (Unix seconds); REAL → `Instant` at Julian day. |
+| Declared type | DataFrame column type            | Storage class → conversion                                                                                                                              |
+|---------------|----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `DATE`        | `kotlinx.datetime.LocalDate`     | TEXT (ISO `YYYY-MM-DD`) → `LocalDate.parse`; INTEGER → date at Unix-seconds UTC; REAL → date at Julian day.                                             |
+| `DATETIME`    | `kotlinx.datetime.LocalDateTime` | TEXT (`YYYY-MM-DD HH:MM:SS` or `YYYY-MM-DDTHH:MM:SS`) → `LocalDateTime.parse`; INTEGER → date-time at Unix-seconds UTC; REAL → date-time at Julian day. |
+| `TIME`        | `kotlinx.datetime.LocalTime`     | TEXT (`HH:MM:SS` or `HH:MM:SS.SSS`) → `LocalTime.parse`; INTEGER → seconds since midnight; REAL → seconds since midnight (fractional part ignored).     |
+| `TIMESTAMP`   | `kotlin.time.Instant`            | TEXT (ISO) → `Instant.parse`; INTEGER → `Instant.fromEpochSeconds` (Unix seconds); REAL → `Instant` at Julian day.                                      |
 
 **Detection is by declared type name, not `jdbcType`.** Xerial changes the reported `jdbcType`
 based on the actual stored value — e.g. a `DATE` column with a Julian-day REAL value is
@@ -121,24 +122,24 @@ reported as `Types.FLOAT`, and a `TIMESTAMP` column with an INTEGER value is rep
 `Types.INTEGER`. DataFrame's SQLite adapter looks at `sqlTypeName` (substring match: `DATETIME`,
 `TIMESTAMP`, `DATE`, `TIME`) to preserve the intended date-time semantics regardless.
 
-If a value cannot be parsed (e.g. a `DATE` column contains an unexpected format), reading
+If a value cannot be parsed automatically (e.g., a `DATE` column contains an unexpected format), reading
 throws with a clear error message referencing the column name and stored value. Opt out
 of conversion by supplying a [custom converter](#custom-converters), e.g.
 
 ```kotlin
 val sqlite = Sqlite.withCustomConverters {
-    // Pin DATETIME columns to raw String — skip the built-in LocalDateTime conversion.
-    forType<String?>("DATETIME")
+    // Provide custom conversion for DATETIME columns.
+    forType("DATETIME") { raw: String -> Instant.parse(raw, customFormat) }
 }
 ```
 
 ### BOOLEAN — INTEGER 0/1 converted to Boolean
 
-| Declared type    | Storage class     | DataFrame column type | Notes                                                                                                                              |
-|------------------|-------------------|----------------|------------------------------------------------------------------------------------------------------------------------------------|
-| `BOOLEAN`, `BIT` | INTEGER (0/1)     | `Boolean`      | The preprocessor treats non-zero as `true`, zero as `false`.                                                                        |
-| `BOOLEAN`, `BIT` | REAL              | `Boolean`      | Same convention (non-zero → `true`).                                                                                                |
-| `BOOLEAN`, `BIT` | TEXT              | `Boolean`      | Case-insensitively accepts `true`/`1`/`yes`/`y`/`t` → `true` and `false`/`0`/`no`/`n`/`f` → `false`. Unrecognised text throws.        |
+| Declared type    | Storage class | DataFrame column type | Notes                                                                                                                          |
+|------------------|---------------|-----------------------|--------------------------------------------------------------------------------------------------------------------------------|
+| `BOOLEAN`, `BIT` | INTEGER (0/1) | `Boolean`             | The preprocessor treats non-zero as `true`, zero as `false`.                                                                   |
+| `BOOLEAN`, `BIT` | REAL          | `Boolean`             | Same convention (non-zero → `true`).                                                                                           |
+| `BOOLEAN`, `BIT` | TEXT          | `Boolean`             | Case-insensitively accepts `true`/`1`/`yes`/`y`/`t` → `true` and `false`/`0`/`no`/`n`/`f` → `false`. Unrecognised text throws. |
 
 `BOOL`/`BIT` substring in the declared name is also caught (e.g. columns declared `IS_ACTIVE_BOOL`).
 
@@ -147,13 +148,37 @@ val sqlite = Sqlite.withCustomConverters {
 `DECIMAL` and `NUMERIC` columns have no canonical numeric type; DataFrame reads the raw stored
 value as-is (`Int`, `Long`, or `Double` depending on how each row was inserted).
 
-| Declared type    | Storage class | DataFrame column type          | Notes                                            |
-|------------------|---------------|-------------------------|--------------------------------------------------|
-| `NUMERIC`        | INTEGER       | `Int` / `Long`          | Follows the actual value's class.                |
-| `NUMERIC`        | REAL          | `Double`                |                                                  |
-| `DECIMAL(P,S)`   | REAL          | `Double`                |                                                  |
-| `DECIMAL(P,S)`   | INTEGER       | `Int` / `Long`          |                                                  |
-| unrecognised type| any           | depends on stored value | E.g. a text value in a `CUSTOM_TYPE` column is reported as `Types.VARCHAR` and read as `String`. Use a [custom converter](#custom-converters) to pin a specific type. |
+| Declared type     | Storage class | DataFrame column type   | Notes                                                                                                                                                                 |
+|-------------------|---------------|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `NUMERIC`         | INTEGER       | `Int` / `Long`          | Follows the actual value's class. May fail for columns mixed `Int` /  `Long` values. Consider using [custom converter](#custom-converters)                            |
+| `NUMERIC`         | REAL          | `Double`                |                                                                                                                                                                       |
+| `DECIMAL(P,S)`    | REAL          | `Double`                |                                                                                                                                                                       |
+| `DECIMAL(P,S)`    | INTEGER       | `Int` / `Long`          |                                                                                                                                                                       |
+| unrecognised type | any           | depends on stored value | E.g. a text value in a `CUSTOM_TYPE` column is reported as `Types.VARCHAR` and read as `String`. Use a [custom converter](#custom-converters) to pin a specific type. |
+
+Sometimes, a driver may return mixed `Int` and `Long` values for the same column,
+which can break column type detection.
+Consider using a [custom converter](#custom-converters) to specify the expected column type
+and, optionally, provide a converter.
+
+Assume we have a nullable `"mixed_values"` column for which the Xerial driver returns both
+`Int` and `Long` values.
+
+You can specify the expected column type (`Number`) explicitly:
+
+```kotlin
+val sqlite = Sqlite.withCustomConverters {
+    forColumn<Number?>("mixed_values")
+}
+```
+
+Or you can provide a converter to convert the values to the desired type:
+
+```kotlin
+val sqlite = Sqlite.withCustomConverters {
+    forColumn("mixed_values") { raw: Number? -> raw?.toLong() }
+}
+```
 
 ## STRICT tables
 
@@ -207,15 +232,14 @@ val df = DataFrame.readSqlTable(connection, "events", dbType = sqlite)
 
 ## SQLite specifics
 
-- **No canonicalisation** — the [Xerial JDBC driver](https://github.com/xerial/sqlite-jdbc)
-  preserves the declared type verbatim in `sqlTypeName`. Two columns declared `INTEGER` and
+- **No canonicalization** — the [Xerial JDBC driver](https://github.com/xerial/sqlite-jdbc)
+  preserves the declared type verbatim in `sqlTypeName`. Two columns declared `INT` and
   `TINYINT` both have INTEGER affinity but distinct `sqlTypeName` values in metadata.
 - **`rs.getObject(int)` returns exactly one of `Integer` / `Long` / `Double` / `String` /
   `byte[]` / `null`.** No `Timestamp` / `LocalDate` / `Boolean` / `Blob` ever reaches
-  DataFrame from a SQLite driver — hence the SQLite adapter needs to translate. See
-  Xerial's [datatype mapping](https://github.com/xerial/sqlite-jdbc/wiki#datatype-mapping).
+  DataFrame from a SQLite driver — hence the SQLite adapter needs to translate.
 - **`DATE` / `DATETIME` / `TIME` / `TIMESTAMP` are converted from storage class to an idiomatic
-  Kotlin date-time type.** ISO strings, Unix epoch integers, and Julian days are all normalised
+  Kotlin date-time type.** ISO strings, Unix epoch integers, and Julian days are all normalized
   to `kotlinx.datetime.LocalDate` / `LocalDateTime` / `LocalTime` / `kotlin.time.Instant` in
   preprocessing. This keeps the schema stable across rows even when values are stored in
   different formats. Unsupported inputs throw with a message pointing at the column and stored
@@ -227,9 +251,3 @@ val df = DataFrame.readSqlTable(connection, "events", dbType = sqlite)
   double value becomes `Double`; with a stored integer value it becomes `Int` / `Long`.
 - **Custom overrides** are registered via `Sqlite.withCustomConverters { ... }`. See the
   [Custom converters](#custom-converters) section above.
-
-## Unsupported types
-
-- SQLite JSON values are simply TEXT — read as `String`. Use client-side parsing.
-- Client-defined types via SQLite's JSON1 or R*Tree extensions are read as their storage class.
-  Use a [custom converter](#custom-converters) to translate to a domain type.

From becda76f8d286cd01cb84a3686c9b4c52d545db4 Mon Sep 17 00:00:00 2001
From: "andrei.kislitsyn" <kisandy@yandex.ru>
Date: Wed, 19 Aug 2026 18:10:49 +0400
Subject: [PATCH 10/10] Clarify and refine DuckDB type mapping documentation:
 update links for `STRUCT` type details.

---
 docs/StardustDocs/topics/readSqlTypeMapping_DuckDB.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/StardustDocs/topics/readSqlTypeMapping_DuckDB.md b/docs/StardustDocs/topics/readSqlTypeMapping_DuckDB.md
index ed85abfeb7..a15e1878c0 100644
--- a/docs/StardustDocs/topics/readSqlTypeMapping_DuckDB.md
+++ b/docs/StardustDocs/topics/readSqlTypeMapping_DuckDB.md
@@ -108,8 +108,8 @@ DuckDB supports nested / composite types, which the DataFrame converter resolves
 - [Nested types](https://duckdb.org/docs/sql/data_types/overview#nested--composite-types)
   (`LIST`, `ARRAY`, `MAP`, `STRUCT`) are resolved recursively: `INTEGER[]` becomes
   `List<Int>`, `MAP(VARCHAR, INTEGER)` becomes `Map<String, Int>`, and so on.
-- [`STRUCT(...)`](https://duckdb.org/docs/sql/data_types/struct) becomes a **column group**
-  (`DataRow`); arrays of `STRUCT` become **frame columns** (`DataFrame`).
+- [`STRUCT(...)`](https://duckdb.org/docs/sql/data_types/struct) becomes a [**column group**](DataColumn.md#columngroup)
+  (`DataRow`); arrays of `STRUCT` become [**frame columns**](DataColumn.md#framecolumn) (`DataFrame`).
 - Reading a DuckDB [`JSON`](https://duckdb.org/docs/data/json/overview) column
   [parses](parse.md) the JSON text:
   - JSON array is read as `DataFrame` into the [frame column](DataColumn.md#framecolumn);