Kotlin: Insert data

from(table).insert(columns) writes the row into the local database and queues one outbox mutation for the next sync run, minting a uuid primary key when the table is keyed by id and columns carry none. apply(table, pk, op, ...) is the same write at the low level, for a call site that already has its own primary key or needs mutationId.

Examples#

Basic#

// app/src/main/kotlin/com/example/todo/TodoScreen.kt (excerpt)
kizunasync.from("todos").insert(
    mapOf("title" to "works on a plane", "done" to false),
)

With your own primary key#

// app/src/main/kotlin/com/example/todo/TodoScreen.kt (excerpt)
import java.util.UUID

kizunasync.from("todos").insert(
    mapOf(
        "id" to UUID.randomUUID().toString(),
        "title" to "works on a plane",
        "done" to false,
    ),
)

Low-level: apply#

// app/src/main/kotlin/com/example/todo/TodoScreen.kt (excerpt)
import com.kizunasync.kizunasync.KizunaSyncOp
import java.util.UUID

val mutationId = UUID.randomUUID().toString()
kizunasync.apply(
    table = "todos",
    pk = todoId,
    op = KizunaSyncOp.Insert,
    columns = mapOf("title" to "works on a plane", "done" to false),
    mutationId = mutationId,
)

The id you pass as mutationId is the one the server's verdict and any journal entry carry, so a screen can match a rejection back to the write that caused it. from(table).insert(columns) has no mutationId parameter; use apply when you need to pass one.

Read the inserted row back#

// app/src/main/kotlin/com/example/todo/TodoScreen.kt (excerpt)
import java.util.UUID

val todoId = UUID.randomUUID().toString()
kizunasync.from("todos").insert(mapOf("id" to todoId, "title" to "works on a plane", "done" to false))
val todo = kizunasync.from("todos").select("id, title").eq("id", todoId).single()

insert(columns) writes the row at once and answers nothing. Pass the id, then read the row back by it, with any column the engine filled.

Parameters#

from(table).insert(columns)#

apply(table, pk, op, columns, mutationId, transforms, precondition)#

Returns#

Unit. Both functions suspend on Dispatchers.IO, so neither ever blocks the Android main thread.

Errors#

apply throws KizunaSyncError.Engine("LOCAL_UNSUPPORTED", "apply requires table and pk") inside the client when table or pk is empty, before the engine is reached. A value org.json refuses never reaches the engine: the client raises a JSONException while encoding, so it surfaces as that exception rather than an engine code.

Notes#

Supabase documents the column payload and its parameters on insert(); this page adds only what local-first changes. The write lands in local SQLite first and its verdict arrives with a later Sync, which is the path Offline writes walks through. A successful insert raises LOCAL_CHANGED and then QUEUE_DEPTH on Subscribe to events, so a list can refresh itself without polling. Until a run delivers it, the row is counted by Outbox depth. The Host scheduler wakes on that QUEUE_DEPTH event, so the write goes out without waiting for its timer.

On a table whose bucket is KizunaSyncBucket.ByOwner(column), an insert that leaves that column out is written with the owner's id: the user the first session token named, at create or through Set access token, which the local database keeps across launches. The outbox entry carries the filled column too. An insert that names the column keeps its value, null included, and an update or a delete is never filled. Before any token has named an owner, the insert keeps only the columns you passed.

Row Level Security judges the insert when the push reaches the server, not when this function returns. When a policy refuses the row, the engine reverts it after the fact and journals the rejection. Supabase describes the policy side under Row Level Security.

Related reference#

• Fetch data
• Update data
• Delete data
• Using transforms
• Sync
• Swift: Insert data
• JavaScript: Insert data