v0.2.6-alpha.3

Kotlin: Vacuum attachments

vacuum() walks the attachment rows marked orphaned or evicted, removes each orphaned object from Storage when it can, deletes its sandbox file when no other live row shares it, and drops or updates the queue row depending on the outcome. Nothing that is referenced by a row is touched. The call does nothing without a session or on a soft-blocked store, and it deletes a local file only when it lies under the configured attachment root.

Examples#

Basic#

// app/src/main/kotlin/com/example/todo/TodoScreen.kt (excerpt)
kizunasync.vacuum()

After clearing out finished todos#

// app/src/main/kotlin/com/example/todo/TodoScreen.kt (excerpt)
import com.kizunasync.kizunasync.KizunaSyncOp
import com.kizunasync.kizunasync.KizunaSyncQuery
import org.json.JSONArray

val removed = kizunasync.applyWhere(
    table = "todos",
    op = KizunaSyncOp.Delete,
    filters = JSONArray().put(KizunaSyncQuery.eq("done", true)),
)
kizunasync.sync()
kizunasync.vacuum()

Parameters#

Name	Type	Required	Description
`(none)`	—	—	This function takes no arguments. It works from the rows already marked orphaned or evicted.

Returns#

Unit. A successful removal drops the row entirely, after deleting its sandbox file. A removal refused with 401 or 403, or one that keeps failing once the attachment budget is spent, ends the row evicted instead: the local bytes are deleted, but the row and its hash stay, and the object is left in Storage. Any other failure keeps the row orphaned, with the attempt counted and the error recorded, so the next call tries it again instead of leaking the bytes silently.

Errors#

Code	Condition
`STORE`, `JSON`	The attachment queue could not be read or updated.
`ENGINE_UNAVAILABLE`	The client has no engine because Initializing has not run.

Notes#

A row is orphaned only on server evidence: a pull that brings a tombstone for the row or a server row naming a different reference, or a push verdict confirming this device's own delete or a replacing write, once no local row and no queued write still names the reference, and the reference's owner segment matches the signed-in user. A local delete or update alone marks nothing until the push settles. A reference this device drops without that evidence is evicted instead, for example a rehydration, a scope change, an import whose column update failed, or a reference owned by another user: this call only deletes its local bytes, and Storage is never asked. Age alone never marks a reference orphaned or evicted, so this call is safe at any point. Run it after a batch of deletes syncs.

The sandbox is content addressed, so two references that hold identical bytes share one file. The shared-file check is what keeps a vacuum from deleting bytes another live row points at. Supabase documents the object removal side under Storage error codes, and Media and attachments puts the queue in context.

Reset is the other way bytes leave the device. It wipes the queue rather than walking it, so it hands the paths back for the caller to delete.

← Remove an attachment Host scheduler →

Found a problem? Edit this page on GitHub