# SQL to DataFrame column type mapping

> For the complete documentation index, see [llms.txt](https://kotlin.github.io/dataframe/llms.txt).

When reading from a JDBC database, DataFrame determines the Kotlin type of each column in two steps using `DbType` — a class responsible for handling column metadata and creating [DataFrame](dataframe.html) columns based on it:

API reference: [DbType](https://kotlin.github.io/dataframe/api-docs/dataframe-jdbc/org.jetbrains.kotlinx.dataframe.io.db/-db-type/index.html)

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`.

Column nullability is determined from the metadata provided by the JDBC driver. If the driver does not explicitly report a column as non-nullable, it is mapped to a nullable Kotlin type (`Int?` instead of `Int`).

For some databases (such as [DuckDB](readsqltypemapping-duckdb.html) and [SQLite](readsqltypemapping-sqlite.html)), this logic is overridden with custom dialect-specific converters based on column metadata — `JdbcToDataFrameConverter`. See [AdvancedDbType](readsqlfromcustomdatabase.html#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 — 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.

SQLite is the exception — it preserves the declared type verbatim in metadata and applies "type affinity" instead. See the [SQLite page](readsqltypemapping-sqlite.html) for how this works.

## Per-database type mapping pages

Here is a list of links for each database supported in Kotlin DataFrame:

| Database | How it uses `DbType` |
| --- | --- |
| [MariaDB](readsqltypemapping-mariadb.html) | Default `DbType` + overrides for unsigned integer types. |
| [MySQL](readsqltypemapping-mysql.html) | Default `DbType` + overrides for unsigned integer types. |
| [PostgreSQL](readsqltypemapping-postgresql.html) | Default `DbType` + `PGobject` overrides (`box`, `point`, `money`, ...). |
| [MS SQL Server](readsqltypemapping-mssql.html) | Default `DbType`, no overrides. |
| [H2](readsqltypemapping-h2.html) | Default `DbType` in `Regular` mode; other modes delegate to another dialect. |
| [SQLite](readsqltypemapping-sqlite.html) | `AdvancedDbType` with custom converters for boolean, date-time and numeric types. Accepts user-provided converters. |
| [DuckDB](readsqltypemapping-duckdb.html) | `AdvancedDbType` with its own converters. |

## 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.html).

