executeReturning

Executes the INSERT statement and returns the value of a single column from the newly inserted row.

This is particularly useful for retrieving auto-generated keys (e.g., AUTOINCREMENT primary keys) or columns with DEFAULT values after an insertion. This functionality relies on the RETURNING clause in SQLite.

The statement is executed when this function is called.

Example: Get the auto-generated ID of a new row

// Assume 'artistId' is an INTEGER PRIMARY KEY AUTOINCREMENT
val newId = Artists.insert(Artists.artistName).use {
    it.values("A New Band").executeReturning(Artists.artistId)
}
// 'newId' now holds the integer ID of the newly inserted artist.

Parameters

Type Parameters

Throws

Executes the INSERT statement and returns a KQLiteCursor containing the data from the newly inserted row for the specified columns.

This function uses the RETURNING clause in SQLite to retrieve values from the row that was just inserted. It's highly useful for getting multiple values at once, such as an auto-generated ID along with columns that have DEFAULT values.

The returned KQLiteCursor will contain a single row. You are responsible for closing the cursor when you are done with it, for example, by using a use block.

Example: Get the ID and default creation date of a new row

// Assume 'artistId' is an auto-incrementing PK and 'createdAt' has a DEFAULT value
Artists.insert(Artists.artistName).use { statement ->
        statement
            .values("A New Band")
            .executeReturning(Artists.artistId, Artists.createdAt)
            .use { cursor ->
                val newId = cursor[Artists.artistId]
                val time = cursor[Artists.createdAt]
                println("Inserted artist with ID $newId at $time")
            }
    }

Parameters

See also

Throws