Date and time types

Exposed provides comprehensive support for date and time operations through dedicated modules. Each module is based on a different date-time library, offering different features and type support.

Modules

Module	Based on	Use
`exposed-kotlin-datetime`	`kotlinx-datetime`	Modern Kotlin-first approach, recommended for new projects.
`exposed-java-time`	Java 8 Time	Good choice when integrating with Java code or when you need Java 8 Time API compatibility.
`exposed-jodatime`	Joda-Time	Legacy support. Consider using newer modules for new projects.

Add a dependency

Before using date and time column types or functions, add your chosen date-time module to your build file:

                dependencies {
                    implementation("org.jetbrains.exposed:exposed-kotlin-datetime:1.4.0")
                }
                

                <dependencies>
                    <dependency>
                        <groupId>org.jetbrains.exposed</groupId>
                        <artifactId>exposed-kotlin-datetime</artifactId>
                        <version>1.4.0</version>
                    </dependency>
                </dependencies>
                

                dependencies {
                    implementation "org.jetbrains.exposed:exposed-kotlin-datetime:1.4.0"
                }
                

                dependencies {
                    implementation("org.jetbrains.exposed:exposed-java-time:1.4.0")
                }
                

                <dependencies>
                    <dependency>
                        <groupId>org.jetbrains.exposed</groupId>
                        <artifactId>exposed-java-time</artifactId>
                        <version>1.4.0</version>
                    </dependency>
                </dependencies>
                

                dependencies {
                    implementation "org.jetbrains.exposed:exposed-java-time:1.4.0"
                }
                

                dependencies {
                    implementation("org.jetbrains.exposed:exposed-jodatime:1.4.0")
                }
                

                <dependencies>
                    <dependency>
                        <groupId>org.jetbrains.exposed</groupId>
                        <artifactId>exposed-jodatime</artifactId>
                        <version>1.4.0</version>
                    </dependency>
                </dependencies>
                

                dependencies {
                    implementation "org.jetbrains.exposed:exposed-jodatime:1.4.0"
                }
                

Basic usage

To define date and time columns, use the column functions provided by your selected date-time module. The following examples define columns for common date and time types:

import org.jetbrains.exposed.v1.core.Table
import org.jetbrains.exposed.v1.datetime.*

object Events : Table() {
    val id = integer("id").autoIncrement()
    val name = varchar("name", 50)
    val startDate = date("start_date")
    val startTime = time("start_time")
    val createdAt = datetime("created_at")
        .defaultExpression(CurrentDateTime)
    val lastModified = timestamp("last_modified")
    val scheduledAt = timestampWithTimeZone("scheduled_at")
    val period = duration("period")

    override val primaryKey = PrimaryKey(id)
}

import org.jetbrains.exposed.v1.core.Table
import org.jetbrains.exposed.v1.javatime.*

object Events : Table() {
    val id = integer("id").autoIncrement()
    val name = varchar("name", 50)
    val startDate = date("start_date")
    val startTime = time("start_time")
    val createdAt = datetime("created_at")
        .defaultExpression(CurrentDateTime)
    val lastModified = timestamp("last_modified")
    val scheduledAt = timestampWithTimeZone("scheduled_at")
    val period = duration("period")

    override val primaryKey = PrimaryKey(id)
}

import org.jetbrains.exposed.v1.core.Table
import org.jetbrains.exposed.v1.jodatime.*

object Events : Table() {
    val id = integer("id").autoIncrement()
    val name = varchar("name", 50)
    val startDate = date("start_date")
    val startTime = time("start_time")
    val createdAt = datetime("created_at")
        .defaultExpression(CurrentDateTime)
    val scheduledAt = timestampWithTimeZone("scheduled_at")

    override val primaryKey = PrimaryKey(id)
}

Supported types

Each date-time module provides its own set of types. Select a module to see its supported types and API links:

Column type	Database type	Kotlin type	API
`date()`	`DATE`	`kotlinx.datetime.LocalDate`	`date()`
`time()`	`TIME`	`kotlinx.datetime.LocalTime`	`time()`
`datetime()`	`DATETIME`	`kotlinx.datetime.LocalDateTime`	`datetime()`
`timestamp()`	`TIMESTAMP`	`kotlin.time.Instant`	`timestamp()`
`timestampWithTimeZone()`	`TIMESTAMP WITH TIME ZONE`	`java.time.OffsetDateTime`	`timestampWithTimeZone()`
`duration()`	`BIGINT`	`kotlin.time.Duration`	`duration()`

Column type	Database type	Java type	API
`date()`	`DATE`	`java.time.LocalDate`	`date()`
`time()`	`TIME`	`java.time.LocalTime`	`time()`
`datetime()`	`DATETIME`	`java.time.LocalDateTime`	`datetime()`
`timestamp()`	`TIMESTAMP`	`java.time.Instant`	`timestamp()`
`timestampWithTimeZone()`	`TIMESTAMP WITH TIME ZONE`	`java.time.OffsetDateTime`	`timestampWithTimeZone()`
`duration()`	`BIGINT`	`java.time.Duration`	`duration()`

Column type	Database type	Joda-Time type	API
`date()`	`DATE`	`org.joda.time.DateTime`	`date()`
`time()`	`TIME`	`org.joda.time.LocalTime`	`time()`
`datetime()`	`DATETIME`	`org.joda.time.DateTime`	`datetime()`
`timestampWithTimeZone()`	`TIMESTAMP WITH TIME ZONE`	`org.joda.time.DateTime`	`timestampWithTimeZone()`

`date()`

The date() column type maps to the database DATE type. It is used for storing date values without a time component:

val startDate = date("start_date")

import kotlinx.datetime.LocalDate

Events.insert {
    it[startDate] = LocalDate(1990, 1, 1)
}

import java.time.LocalDate

Events.insert {
    it[startDate] = LocalDate.of(1990, 1, 1)
}

import org.joda.time.DateTime

Events.insert {
    it[startDate] = DateTime(1990, 1, 1, 0, 0, 0)
}

`time()`

The time() column type maps to the database TIME type. It is used for storing time values without a date component.

val startTime = time("start_time")

import kotlinx.datetime.LocalTime

Events.insert {
    it[startTime] = LocalTime(9, 0) // 09:00
}

import java.time.LocalTime

Events.insert {
    it[startTime] = LocalTime.of(9, 0) // 09:00
}

import org.joda.time.LocalTime

Events.insert {
    it[startTime] = LocalTime(9, 0) // 09:00
}

`datetime()`

The datetime() column type maps to the database DATETIME type. It is used for storing both date and time values.

The following example sets the current date/time when inserting new records:

val createdAt = datetime("created_at").defaultExpression(CurrentDateTime)

import kotlinx.datetime.toLocalDateTime
import kotlinx.datetime.TimeZone
import kotlin.time.Clock

Events.insert {
    it[createdAt] = Clock.System.now().toLocalDateTime(TimeZone.UTC)
}

import java.time.LocalDateTime

Events.insert {
    it[createdAt] = LocalDateTime.now()
}

import org.joda.time.DateTime

Events.insert {
    it[createdAt] = DateTime.now()
}

`timestamp()`

The timestamp() column type maps to the database TIMESTAMP type. It is used for storing both date and time values.

val lastModified = timestamp("last_modified")

import kotlin.time.Clock

Events.insert {
    it[lastModified] = Clock.System.now()
}

import java.time.Instant

Events.insert {
    it[lastModified] = Instant.now()
}

`timestampWithTimeZone()`

The timestampWithTimeZone() column type maps to the database TIMESTAMP WITH TIME ZONE type. It is used for storing both date and time values while preserving timezone information.

val scheduledAt = timestampWithTimeZone("scheduled_at")

import kotlin.time.Clock
import kotlin.time.toJavaInstant
import java.time.ZoneOffset

Events.insert {
    it[scheduledAt] = Clock.System.now().toJavaInstant().atOffset(ZoneOffset.UTC)
}

import java.time.OffsetDateTime
import java.time.ZoneOffset

Events.insert {
    it[scheduledAt] = OffsetDateTime.now(ZoneOffset.UTC)
}

import org.joda.time.DateTime
import org.joda.time.DateTimeZone

Events.insert {
    it[scheduledAt] = DateTime.now().withZone(DateTimeZone.UTC)
}

`duration()`

The duration() column type maps to the database BIGINT type. It is used for storing the length of time between one instant and another.

val period = duration("period")

import kotlin.time.Duration.Companion.hours

Events.insert {
    it[period] = 4.hours
}

import java.time.Duration

Events.insert {
    it[period] = Duration.ofHours(4)
}

Working with date and time expressions

Extracting date and time components

Exposed provides extension functions for extracting individual components from date and time expressions. These functions return SQL expressions that can be used in queries, including SELECT, WHERE, GROUP BY, and ORDER BY clauses.

The following functions are available for the date and time types supported by each Exposed date-time module:

.year(): Returns the year as an Int.
.month(): Returns the month of the year (1–12).
.day(): Returns the day of the month (1–31).
.hour(): Returns the hour of the day (0–23).
.minute(): Returns the minute of the hour (0–59).
.second(): Returns the second of the minute (0–59).

.year(): Returns the year as an Int.
.month(): Returns the month of the year (1–12).
.day(): Returns the day of the month (1–31).
.hour(): Returns the hour of the day (0–23).
.minute(): Returns the minute of the hour (0–59).
.second(): Returns the second of the minute (0–59).

.year(): Returns the year as an Int.
.month(): Returns the month of the year (1–12).
.day(): Returns the day of the month (1–31).
.hour(): Returns the hour of the day (0–23).
.minute(): Returns the minute of the hour (0–59).
.second(): Returns the second of the minute (0–59).

For example, the following query selects all events that start in June:

import org.jetbrains.exposed.v1.datetime.month

Events.selectAll().where { Events.startDate.month() eq 6 }

import org.jetbrains.exposed.v1.javatime.month

Events.selectAll().where { Events.startDate.month() eq 6 }

import org.jetbrains.exposed.v1.jodatime.month

Events.selectAll().where { Events.startDate.month() eq 6 }

Using the current date and time

Exposed provides the following expressions for retrieving the current date and time from the database server:

CurrentDate: Returns the current date as kotlinx.datetime.LocalDate.
CurrentDateTime: Returns the current date and time as kotlinx.datetime.LocalDateTime.
CurrentTimestamp: Returns the current date and time as kotlin.time.Instant.
CurrentTimestampWithTimeZone: Returns the current date and time with timezone as java.time.OffsetDateTime.

CurrentDate: Returns the current date as java.time.LocalDate.
CurrentDateTime: Returns the current date and time as java.time.LocalDateTime.
CurrentTimestamp: Returns the current date and time as java.time.Instant.
CurrentTimestampWithTimeZone: Returns the current date and time with timezone as java.time.OffsetDateTime.

CurrentDate: Returns the current date as org.joda.time.DateTime.
CurrentDateTime: Returns the current date and time as org.joda.time.DateTime.

For example, these expressions can be used as default expressions when defining table columns:

import org.jetbrains.exposed.v1.datetime.CurrentDate

object Events : Table() {
    val startDate = date("start_date")
        .defaultExpression(CurrentDate)
}

import org.jetbrains.exposed.v1.javatime.CurrentDate

object Events : Table() {
    val startDate = date("start_date")
        .defaultExpression(CurrentDate)
}

import org.jetbrains.exposed.v1.jodatime.CurrentDate

object Events : Table() {
    val startDate = date("start_date")
        .defaultExpression(CurrentDate)
}

The object CurrentDate defines the SQL function CURRENT_DATE as the column default on table creation. The exact date function used may differ for specific database dialects.

The database evaluates these expressions when the SQL statement is executed. As a result, the returned values reflect the database server's current date and time.

05 August 2026