KQLiteCursor

Provides a read-only, forward-only, type-safe cursor as Iterator over the result set of underlying database cursor. Helpful to use with Kotlin forEach.

• This operator allows for convenient, array-like access to column data using a KQLiteColumn instance. The return type T is inferred from the column definition, ensuring type safety at compile time.

• Each iteration step advances the underlying cursor and exposes the current row through the same instance.

• If any value is read from the cursor without any iteration or loops, cursor reads from the first row of the result. Hence, cursor.getString(3) without the loop will read the 4th column of the first row if the cursor is not empty.

• For nullable columns, the return type T will be nullable (e.g., String?). For columns defined as notNull() or as a primaryKey(), the return type will be non-nullable (e.g., String, Int).

• It provides getXXX or null operation for nullable columns, a convenience method over if(isNull(XXX)) ... else getXXX. For compatibility, index based data access is also possible. For example: cursor.getInt(0)

• As this interface extends AutoCloseable, it is recommended to use it within a use block to ensure that the underlying resources are properly released.

• For SELECT queries, the cursor is closed automatically after the last row is processed. Use kotlin.sequences.asSequence to convert the cursor into a Sequence to for advanced use-cases like kotlin.sequences.map cursor results to other types.

Example (Type-safe data access)

// SELECT * FROM employee_table;
val cursor = Employee.select().execute()
cursor.forEach {
    // returns non-nullable id due to primaryKey() constraint
    val id = it[Employee.id]

    // returns non-nullable `String` name due to notNull() constraint
    val name = it[Employee.name]

    // returns nullable `String?` jobTitle
    val jobTitle = it[Employee.jobTitle]

    // Reading data by index
    val value = it.getDouble(3)
}
// here cursor is closed automatically

Example (Cursor results mapping)

// Mapping results to other types
val pairs = cursor
            .asSequence()
            .map {
                it[Employee.id] to it[Employee.name]
            }.toList()

Example (Cursor object mapping)

val empList = Employee.quickSelect().mapToList(Employee::mapper)

Example (Cursor mapping as Flow)

val flow = Employee.quickSelect().asCallbackFlow().mapToList(mapper = Employee::mapper)

Example (Read first row)

// Reading from the first row immediately (unsafe)
val empName: String = Employee.select().execute().use { it[Employee.name] }

See also