Alpha · on npm, Swift Package Manager, and Maven Central
AlphaSupabase sync Alpha for
sqlite
writes locally
internet
syncing
your supabase
source of truth
Synchronizes rows and attachment references. Buckets select; Postgres grants and RLS authorize.
| Capability | Kizuna |
|---|---|
| License | Engine, drivers, CLI & panel: Apache-2.0; server SQL pack: PolyForm-Shield |
| Distribution | npm kizunasync with its five @kizunasync/<platform> binary packages, Swift package kizunasync/kizunasync-swift, Maven com.kizunasync:kizunasync, published by the release workflows on a tag matching the workspace version (X.Y.Z with an optional prerelease identifier) |
| Kizuna-operated data plane | None; clients call SQL and Storage in your Supabase project |
| Data + media sync | Rows plus attachment references; standard upload through 6 MiB, then TUS |
| Conflict handling | Column LWW by server arrival by default; optional clamped-HLC mode |
| Query API | Documented supabase-js-like subset over local SQLite; unsupported operations throw |
| Deletes | Retained tombstones plus CHECKPOINT_EXPIRED rehydration beyond the horizon |
| Status | Alpha; published on npm, Swift Package Manager, and Maven Central |
How it works
Alpha01 · Provision
Init
A connected kizunasync init can inspect policies and propose simple owner buckets. Dry-run changes nothing; an applied run writes the pack and project config. kizunasync deprovision removes understood ledgered objects, not every base-pack object.
$ npx kizunasync init --dry-run▍02 · Configure
The everyday API
A documented supabase-js-like subset reads local SQLite while offline. Unsupported constructs throw LOCAL_UNSUPPORTED according to the compatibility matrix; there is no silent network fallback.
import { useMutation, useQuery } from 'kizunasync/react'
export function Todos() {
const { data: todos, isLoading } = useQuery((kizunasync) =>
kizunasync.from('todos').select().eq('done', false).order('created_at'),
)
const { mutate } = useMutation()
const addTodo = (title: string) =>
mutate((kizunasync) =>
kizunasync.from('todos').insert({
id: crypto.randomUUID(), title, done: false,
}),
)
const toggleTodo = (id: string, done: boolean) =>
mutate((kizunasync) => kizunasync.from('todos').update({ done }).eq('id', id))
if (isLoading) {
return <p>Loading…</p>
}
return <TodoList todos={todos} onAdd={addTodo} onToggle={toggleTodo} />
}<script setup lang="ts">
import { useMutation, useQuery } from 'kizunasync/vue'
const { data: todos, isLoading } = useQuery((kizunasync) =>
kizunasync.from('todos').select().eq('done', false).order('created_at'),
)
const { mutate } = useMutation()
const addTodo = (title: string) =>
void mutate((kizunasync) =>
kizunasync.from('todos').insert({
id: crypto.randomUUID(), title, done: false,
}),
)
const toggleTodo = (id: string, done: boolean) =>
void mutate((kizunasync) => kizunasync.from('todos').update({ done }).eq('id', id))
</script>
<template>
<p v-if="isLoading">Loading…</p>
<TodoList v-else :todos="todos" @add="addTodo" @toggle="toggleTodo" />
</template>import { useCallback } from 'react'
import { FlatList, Pressable, Text } from 'react-native'
import { randomUUID } from 'expo-crypto'
import { useMutation, useQuery } from 'kizunasync/react'
import type { IKizunaSync } from 'kizunasync'
export default function TodosScreen() {
const buildTodos = useCallback(
(kizunasync: IKizunaSync) =>
kizunasync.from('todos').select().eq('done', false).order('created_at'),
[],
)
const { data: todos } = useQuery(buildTodos)
const { mutate } = useMutation()
const addTodo = () =>
mutate((kizunasync) =>
kizunasync.from('todos').insert({
id: randomUUID(), title: 'Offline todo', done: false,
}),
)
return <FlatList data={todos} renderItem={({ item }) => <Text>{item.title}</Text>}
ListFooterComponent={<Pressable onPress={addTodo}><Text>Add todo</Text></Pressable>} />
}import Foundation
import KizunaSync
let rows = try await client.query(table: "todos")
try await client.apply(
table: "todos",
pk: UUID().uuidString,
op: .insert,
columns: ["title": "Offline todo", "done": false]
)
try await client.apply(
table: "todos",
pk: todoId,
op: .update,
columns: ["done": true]
)import com.kizunasync.kizunasync.KizunaSyncClient
import com.kizunasync.kizunasync.KizunaSyncOp
import java.util.UUID
suspend fun writeTodos(client: KizunaSyncClient, todoId: String) {
val rows = client.query(table = "todos")
client.apply(
table = "todos",
pk = UUID.randomUUID().toString(),
op = KizunaSyncOp.Insert,
columns = mapOf("title" to "Offline todo", "done" to false),
)
client.apply(
table = "todos",
pk = todoId,
op = KizunaSyncOp.Update,
columns = mapOf("done" to true),
)
}const { data: todos } = await kizunasync.from('todos').select().eq('done', false).order('created_at')
await kizunasync.from('todos').insert({
id: crypto.randomUUID(), title: 'Offline todo', done: false,
})
await kizunasync.from('todos').update({ done: true }).eq('id', todoId)03 · Wire client
Quickstart
Each tab trims a working guide composition: a platform driver, your config and Supabase client, plus attachment ports where that example configures media.
// src/kizunasync.ts
import { byOwner, defineConfig } from 'kizunasync'
import { createSupabaseKizunaSync } from 'kizunasync/supabase'
import { createWebWorkerDriver } from 'kizunasync/web'
import { supabase } from './supabase-client'
const config = defineConfig({
tables: { todos: { sync: 'read-write', bucket: byOwner('user_id') } },
})
export const kizunasync = createSupabaseKizunaSync({
supabase,
driver: createWebWorkerDriver('todos.db'),
config,
})
// src/main.tsx
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { KizunaSyncProvider } from 'kizunasync/react'
import { TodoList } from './components/todo-list'
import { kizunasync } from './kizunasync'
createRoot(document.getElementById('root')!).render(
<StrictMode>
<KizunaSyncProvider client={kizunasync}>
<TodoList />
</KizunaSyncProvider>
</StrictMode>,
)// src/kizunasync.ts
import { byOwner, defineConfig } from 'kizunasync'
import { createSupabaseKizunaSync } from 'kizunasync/supabase'
import { createWebWorkerDriver } from 'kizunasync/web'
import { supabase } from './supabase-client'
const config = defineConfig({
tables: { todos: { sync: 'read-write', bucket: byOwner('user_id') } },
})
export const kizunasync = createSupabaseKizunaSync({
supabase,
driver: createWebWorkerDriver('todos.db'),
config,
})
// src/main.ts
import { createApp } from 'vue'
import { createKizunaSyncPlugin } from 'kizunasync/vue'
import App from './App.vue'
import { kizunasync } from './kizunasync'
createApp(App).use(createKizunaSyncPlugin(kizunasync)).mount('#app')// src/kizunasync.ts
import { byOwner, defineConfig } from 'kizunasync'
import { openExpoDriver } from 'kizunasync/expo'
import { createSupabaseKizunaSync } from 'kizunasync/supabase'
import { supabase } from './supabase-client'
const config = defineConfig({
tables: { todos: { sync: 'read-write', bucket: byOwner('user_id') } },
})
export const kizunasync = createSupabaseKizunaSync({
supabase,
driver: openExpoDriver('todos.db'),
config,
})
// src/app/_layout.tsx
import { Stack } from 'expo-router'
import { KizunaSyncProvider } from 'kizunasync/react'
import { kizunasync } from '../kizunasync'
export default function RootLayout() {
return (
<KizunaSyncProvider client={kizunasync}>
<Stack />
</KizunaSyncProvider>
)
}// TodoApp/TodoSync.swift
import Foundation
import KizunaSync
import Supabase
let kizunasync = KizunaSyncClient()
let syncScheduler = KizunaSyncScheduler(
client: kizunasync,
refreshSession: {
guard let session = try? await supabase.auth.session else { return false }
try? await kizunasync.setAccessToken(session.accessToken)
return true
},
needsReset: { (try? await kizunasync.checkpoint().softBlocked) ?? false }
)
let kizunasyncReady = Task { @MainActor in
let databaseURL = try FileManager.default
.url(for: .applicationSupportDirectory, in: .userDomainMask, appropriateFor: nil, create: true)
.appendingPathComponent("kizunasync.sqlite")
try await kizunasync.create(KizunaSyncClientConfig(
tables: ["todos": KizunaSyncTableConfig(bucket: .byOwner("user_id"))],
databasePath: databaseURL.path,
remote: KizunaSyncRemoteConfig(url: supabaseURL.absoluteString, publishableKey: supabasePublishableKey)
))
syncScheduler.start()
}// app/src/main/kotlin/com/example/todo/TodoSync.kt
import android.content.Context
import com.kizunasync.kizunasync.KizunaSyncBucket
import com.kizunasync.kizunasync.KizunaSyncClient
import com.kizunasync.kizunasync.KizunaSyncClientConfig
import com.kizunasync.kizunasync.KizunaSyncConnectivityPathMonitor
import com.kizunasync.kizunasync.KizunaSyncProcessForegroundSource
import com.kizunasync.kizunasync.KizunaSyncRemoteConfig
import com.kizunasync.kizunasync.KizunaSyncScheduler
import com.kizunasync.kizunasync.KizunaSyncTableConfig
import io.github.jan.supabase.auth.auth
import java.io.File
import kotlinx.coroutines.sync.Mutex
import kotlinx.coroutines.sync.withLock
val kizunasync = KizunaSyncClient()
lateinit var syncScheduler: KizunaSyncScheduler
private set
private val openLock = Mutex()
private var isOpen = false
suspend fun openKizunaSync(context: Context) {
openLock.withLock {
if (!isOpen) {
kizunasync.create(
KizunaSyncClientConfig(
tables = mapOf("todos" to KizunaSyncTableConfig(bucket = KizunaSyncBucket.ByOwner("user_id"))),
databasePath = File(context.filesDir, "kizunasync.sqlite").absolutePath,
remote = KizunaSyncRemoteConfig(url = SUPABASE_URL, publishableKey = SUPABASE_PUBLISHABLE_KEY),
),
)
syncScheduler = startSyncScheduler(context.applicationContext)
isOpen = true
}
}
}
private fun startSyncScheduler(context: Context): KizunaSyncScheduler {
val scheduler = KizunaSyncScheduler(
client = kizunasync,
refreshSession = {
supabase.auth.awaitInitialization()
val token = supabase.auth.currentSessionOrNull()?.accessToken
if (token != null) {
kizunasync.setAccessToken(token)
}
token != null
},
pathMonitor = KizunaSyncConnectivityPathMonitor(context),
foregroundSource = KizunaSyncProcessForegroundSource(),
needsResetSource = { runCatching { kizunasync.checkpoint().softBlocked }.getOrDefault(false) },
)
scheduler.start()
return scheduler
}// src/kizunasync.ts
import { byOwner, defineConfig } from 'kizunasync'
import { createSupabaseKizunaSync } from 'kizunasync/supabase'
import { createWebWorkerDriver } from 'kizunasync/web'
import { supabase } from './supabase-client'
const config = defineConfig({
tables: { todos: { sync: 'read-write', bucket: byOwner('user_id') } },
})
export const kizunasync = createSupabaseKizunaSync({
supabase,
driver: createWebWorkerDriver('todos.db'),
config,
})
// src/main.ts
import { mountTodoList } from './todo-list'
mountTodoList(document.querySelector<HTMLDivElement>('#app')!)The engine
The current Alpha covers local writes, pull and push, schema gates, retained deletes, attachments, framework bindings, provisioning, and inspection. It does not turn unit coverage into crash, scale, device, or uptime promises.
The local row and its outbox entry commit in one SQLite transaction. Durability across abrupt termination still depends on the driver, journal mode, filesystem, and platform; the repository has no complete kill-test matrix.
Mutation IDs make a committed remote effect replay-safe. Only explicitly permanent failures count toward the five-attempt dead-letter budget; retryable failures remain queued.
attachments.fromFile imports a file into the platform sandbox, computes its sha256, and returns the reference stored in the row; bytes travel through separate file-store and transfer ports.
Uploads through 6 MiB use standard Supabase Storage; larger uploads use resumable TUS with 6 MiB chunks. Downloads verify sha256 whenever a hash is known on either side; with none known on either, the transfer fails closed with ATTACHMENT_UNVERIFIED instead of accepting unverified bytes. Normal unit tests do not prove a hosted or physical-device transfer.
The five public RPCs use SECURITY DEFINER to reach private bookkeeping. User-row reads and writes are delegated through helpers owned by a non-BYPASSRLS role under the caller JWT.
Buckets select candidate rows; grants and RLS authorize them. A denied mutation returns a typed rejection that the client journals and reconciles.
A hard delete leaves a tombstone for the configured retention period and rejects a later mutation with DELETE_WINS while that tombstone exists.
When a client cursor predates retained history, the server returns CHECKPOINT_EXPIRED and the client rehydrates instead of replaying the expired cursor.
Engine events invalidate matching in-process subscriptions, so React hooks and Vue composables can refresh reads from local SQLite.
defineConfig<Database> can reuse generated Supabase table and row types. The Kizuna config still declares which tables synchronize, their modes, buckets, and attachment columns.
The local query builder deliberately implements a documented subset; unsupported PostgREST constructs throw LOCAL_UNSUPPORTED.
The product CLI is the Rust kizunasync binary. Invoke it with npx kizunasync, pnpm dlx kizunasync, yarn dlx kizunasync, or bunx kizunasync, then preview init before applying with --yes.
deprovision removes understood ledgered objects and by default leaves the schema, bookkeeping tables, indexes, and sequence in place; --purge continues into the schema itself. Your application tables and their data are never dropped, on either path.
Its SQL runs in your Supabase project and clients call that project directly, so Kizuna adds no separate operated sync service.
Availability still depends on Supabase, PostgREST, Storage, Realtime wake-ups, pg_cron retention, the network, and the local driver.
IStoreLocator is exported but remains Alpha. A driver names the database file the Rust kernel opens, or hands over an engine it already runs. The repository implements the browser worker driver and the Expo SQLite driver, plus an opt-in op-sqlite adapter.
Browsers run Rust as WebAssembly in the driver's worker; Node/Bun and React Native select Rust when the matching binding and database path are available. No Capacitor driver or standalone published TCK exists.
apps/sync-inspector implements a read-only view over explicitly configured server-side credentials for a development stack.
The code is present; hosting and an active deployment workflow remain open decisions. The repository does not ship a hosted management panel.
0
extra Kizuna data-plane services
5
authenticated public RPCs
5
in-repository example apps
50
protocol corpus cases
Kizuna places no Kizuna-operated service between a client and its Supabase project. The trade-off is explicit: you keep the SQL, credentials, quotas, upgrades, retention, and operational evidence in your own environment. This architecture avoids adding a Kizuna-operated hop; it does not promise zero downtime.
"In local-first software, the availability of another computer should never prevent you from working."Kleppmann, Wiggins, van Hardenberg & McGranaghan, "Local-first software" (2019)
Kizuna's protocol is scoped on purpose: it draws on Bayou's tentative writes and server arbitration (1995), session guarantees (1994), and causal+ consistency to checkpoints (COPS, 2011). The default is column-LWW by accepted server arrival; an optional mode uses clamped HLC ordering. Both remain subject to RLS, grants, constraints, preconditions, tombstone retention, and successful checkpoints.
Sources: Local-first software · Bayou (SOSP 1995) · COPS (SOSP 2011)
Radical honesty
These are the current wrong-tool boundaries, with the relevant alternative class named.
Trusting a sync engine requires being able to read it. Kizuna's answer is readable SQL provisioned into your own project, a public wire protocol, and a conformance corpus, so the inspector and the transcripts let you verify every claim on this page yourself.
Concurrent collaborative text or canvas co-editing
Use a CRDT engine. Yjs, Automerge, Loro. Different problem class.
Strict cross-user invariants: ledgers, bookings, inventory holds
Keep those flows online-only and transactional. Offline writes are the wrong model regardless of engine.
Arbitrary RLS-predicate partial sync at enterprise scale
Evaluate a dedicated server-side sync service. Kizuna supports declared equality buckets, with RLS as authorization.
Multi-terminal mesh sync while offline (full POS, kiosk fleets)
Use a system designed and tested for peer or edge mesh replication. Kizuna synchronizes through one authoritative Supabase project.
Its queued writes wait for as long as it takes, and the device catches up when it reconnects, rebuilding its local copy if it fell behind the server's retention. When the network returns, the app client pushes the outbox first, in the order you made the writes, then pulls from its saved cursor. A device whose cursor predates the delete history the server still keeps (tombstone_ttl_days, 30 days by default) receives CHECKPOINT_EXPIRED, pulls its data again from the start, replaces its local copy, and replays the writes still pending on top. A queued update to a row someone deleted meanwhile is rejected instead of bringing the row back. The rejection reads DELETE_WINS while the delete history is kept and the user had already pulled a live row from that row's bucket, and RLS_DENIED otherwise.
On tables with client registration turned on, a registration silent for client_ttl_days, 90 by default, is pruned, and the device registers again on its next pull or push. An app build below a table's min_schema_version receives RESET_REQUIRED and stops syncing until an update ships and the app calls reset(), which discards the writes still queued. Offline writes explains the queue, and Fencing and horizons explains the cursor.
It works with it. createSupabaseKizunaSync takes your app's supabase-js client and uses its session for every pull and push, its Realtime connection for the wake-up hint, and its Storage for attachments. Your screens read and write synced tables through kizunasync.from(...), which answers from the local database, while your app keeps supabase-js for sign-in, Edge Functions, server RPCs, and the tables it does not sync (rpc and schema on the app client throw LOCAL_UNSUPPORTED rather than reach the network). Swift and Kotlin apps keep supabase-swift and supabase-kt for sign-in and hand the session token to the app client.
A write that goes to a synced table through supabase-js or SQL still reaches the devices that pull that row, because the triggers Kizuna installs record it. In the default arrival mode, though, a device that still has a queued write to the same column replaces that value when it pushes. A table you write only through supabase-js can sync pull-only instead, which makes its local copy read-only and leaves every write on your supabase-js path. How Kizuna works shows where each piece sits.
Through an attachment queue that uploads each file after its row reaches the server, resumably and in 6 MiB chunks once the file is larger than 6 MiB. The row holds a short reference string, and fromFile copies the file into a local sandbox, computes its SHA-256 digest, and queues the upload, which runs only once the outbox has pushed the row. A file of at most 6 MiB takes one standard Storage upload, and a larger one takes a resumable TUS upload whose session URL is saved before the first chunk, so a later attempt continues from the offset the server reports. Another device downloads the file when a view first asks for it and checks the bytes against the SHA-256 digest, and a transfer that keeps failing stops after five attempts by default until your app calls retry. Kizuna caps neither the size nor the type of a file, so set the Storage bucket's file_size_limit. The adapter also reads the whole file into memory to move it in either direction, which means resumable uploads do not make a very large file cheap in memory. Media attachments wires the queue end to end.
Kizuna runs its sync logic inside your own Supabase project, while PowerSync, Electric, and Zero run a sync service beside your database and Firestore keeps your data in its own backend. Kizuna's SQL functions apply your Row Level Security to every pull and push and answer each write with a typed verdict, files sync with their rows through Supabase Storage, and the JavaScript, Swift, and Kotlin clients all run the same Rust engine. Comparison with alternatives covers each product and when to choose it, and the capability matrix puts them side by side.
Per column, in your Postgres database. In the default arrival mode, two writes that name different columns of a row both keep their values. When two accepted writes touch the same column, the one the server receives later holds it, and device clocks play no part. A table set to hlc mode compares each column's origin Hybrid Logical Clock instead, after the server clamps a device clock running ahead by more than hlc_max_skew_ms, five seconds by default. Row Level Security, constraints, preconditions, and delete history can still reject a single write, which comes back as a typed verdict, while the push policy (a maximum batch size or required atomic batches) refuses the whole request with an error. Kizuna's guarantees (causal+ consistency to checkpoints and the four session guarantees) hold for successful checkpoints, the buckets a device pulls, and devices that sync within retention. Conflict resolution walks through both modes.
Kizuna adds no bill of its own, because no service that Kizuna operates or charges for sits between your devices and your Supabase project. The engine, drivers, bindings, CLI, inspector, and protocol sources are Apache-2.0, and the server SQL pack is PolyForm Shield 1.0.0. You still pay for and operate the Supabase, hosting, storage, egress, build, and support resources your application uses, and pulls, pushes, and attachment transfers are requests to your own project. Governance records the licensing commitments.