PostgreSQL type mapping
The tables below list every PostgreSQL column type (PostgreSQL Data Types) 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.
API reference: PostgreSQL
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).
Numeric types
Canonical | Aliases | DataFrame column type | Notes |
|---|---|---|---|
|
|
| 2-byte signed integer. |
|
|
| 4-byte signed integer. |
|
|
| 8-byte signed integer. |
|
|
| Auto-incrementing |
|
|
| Auto-incrementing |
|
|
| Auto-incrementing |
|
|
| Arbitrary-precision decimal. |
|
|
| 4-byte float. |
|
|
| 8-byte float. |
| none |
| PostgreSQL override: read as |
Boolean
Canonical | Aliases | DataFrame column type | Notes |
|---|---|---|---|
|
|
|
Character types
Canonical | Aliases | DataFrame column type | Notes |
|---|---|---|---|
|
|
| Fixed-length text. |
|
|
| Variable-length text. |
| none |
| Unbounded text. |
Binary
Canonical | Aliases | DataFrame column type | Notes |
|---|---|---|---|
| none |
| Raw binary. Driver reports it as |
Date and time types
Canonical | Aliases | DataFrame column type | Notes |
|---|---|---|---|
| none |
| |
| none |
|
|
|
|
| The offset is not kept — the driver reports the column as plain |
| none |
| Preprocessed from |
|
|
| Also preprocessed from |
| none |
| PostgreSQL override. |
Neither of the two time-zone-aware types keeps the UTC offset that was stored. A timetz value loses it outright, because the driver reports the column as a plain time; a timestamptz value keeps the instant it denotes but not the offset it was written with, because a kotlin.time.Instant is a point in time. Read the offset as a separate column if it matters — for example SELECT timestamptzCol, to_char(timestamptzCol, 'OF') AS offset.
Geometric types (PostgreSQL overrides)
Case-insensitive sqlTypeName lookup selects a PostgreSQL-specific PGobject wrapper.
Canonical | Aliases | DataFrame column type | Notes |
|---|---|---|---|
| none |
| Rectangle |
| none |
| Circle |
| none |
| Infinite line |
| none |
| Line segment |
| none |
| Open or closed |
| none |
| 2-D point |
| none |
| Polygon |
Bit strings
Canonical | Aliases | DataFrame column type | Notes |
|---|---|---|---|
| none |
| A single-bit column is the one case the driver really returns a |
| none |
| The bit string, as |
|
|
| Read as the driver's |
UUID, XML, JSON
Canonical | Aliases | DataFrame column type | Notes |
|---|---|---|---|
| none |
| The value is a |
| none |
| The value is the driver's |
| none |
| The value is an |
| none |
| The value is an |
Unlike H2 and DuckDB, which read a UUID column as kotlin.uuid.Uuid, PostgreSQL leaves it typed Any. To get the same type here, convert the column after reading it: convert { uuidCol }.with { Uuid.parse(it.toString()) }.
Network address types
All four are read as Any, holding an org.postgresql.util.PGobject; call toString() for the text form.
Canonical | Aliases | DataFrame column type | Notes |
|---|---|---|---|
| none |
| IPv4 or IPv6 host / network. |
| none |
| IPv4 or IPv6 network. |
| none |
| MAC address (6 bytes). |
| none |
| MAC address (8 bytes / EUI-64). |
Range types
Range types are read as Any, holding an org.postgresql.util.PGobject; toString() gives the canonical [lo,hi) text form.
Canonical | Aliases | DataFrame column type | Notes |
|---|---|---|---|
| none |
| |
| none |
| |
| none |
| |
| none |
| |
| none |
| |
| none |
| |
| none |
| Multi-ranges (PG 14+). |
Full-text search
Canonical | Aliases | DataFrame column type | Notes |
|---|---|---|---|
| none |
| Text search document. |
| none |
| Text search query. |
Object identifiers
Canonical | Aliases | DataFrame column type | Notes |
|---|---|---|---|
| none |
| Underlying storage is 32-bit unsigned integer. |
| none |
| Reported as text alias. |
| none |
| Various OID aliases. |
Other
Canonical | Aliases | DataFrame column type | Notes |
|---|---|---|---|
| none |
| Write-Ahead Log sequence number. |
| none |
| Snapshot info. |
user-defined | none |
| User-declared enum types are read as their string label. |
user-defined | 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.User-defined
DOMAINtypes are transparent at the JDBC layer — the underlying primitive's mapping applies.Auto-incrementing
SERIALvariants areINTEGER/BIGINTin the metadata — the sequence is a server-side default, not a separate JDBC type.Composite / anonymous
ROW(...)values come through the driver as aPGobjectwithTypes.OTHERand fall through to the default handler → column type isAny.
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;
Composite (
ROW(...)) and user-defined composite types — a driver returnsPGobject, DataFrame column type isAny.Array types (
type[]) — read as SQLARRAYand post-processed toArray<*>; element types beyond the primitives listed here are not resolved.hstoreextension — driver returns aMap<String, String>wrapped inPGobject; a column type isAny.PostGIS types (
geometry,geography, ...) — a driver returnsPGobject; a column type isAny.Range / multi-range internal representation — read as text.
bit(n)/bit varying(n)— driver returns the string form"0"/"1".