SQL pack

The installable SQL pack is one migration, packages/supabase-pack/supabase/migrations/0001_kizuna_init.sql. It creates the kizunasync schema, one database role, fourteen tables, one sequence, twelve secondary indexes, seventy-six functions, two triggers on its own tables, a statement trigger on _change_pending and a deferred constraint trigger on _stamp_marker, four Row Level Security policies, three guarded pg_cron jobs, and a ledger of what a teardown may remove. Everything it installs lives in the Supabase project that runs it.

Tables gives every column of the bookkeeping tables. Functions gives the signature, the return shape, and the errors of each public RPC and each maintenance function. Triggers and Scheduled jobs cover what the pack runs without a caller. Grants and security and Local ports say who may call what, and Pack vs demo and Realtime doorbell mark the edges of what the migration installs.

The base file never alters an application table. Per-table triggers and _config rows come from the separate config migration that kizunasync init and kizunasync sync generate from the tables the CLI proposed. kizunasync deprovision acts on ledgered rows only, so the schema, the bookkeeping tables, their indexes, and the sequence stay behind.

Tables#

All fourteen tables live in kizunasync. Column defaults, nullability, and constraints below are the ones the migration declares; the base pack modifies no table in public.

kizunasync._provisions#

Ledger used for idempotency and teardown. It is not a complete inventory of every base-pack object: the pack seeds function, policy, cron, and role rows; generated per-table migrations add trigger and config rows; the CLI adds pack-file rows. kizunasync deprovision acts only on these rows, which is why Remove reports leftovers as expected rather than as an error.

Indexes and constraints: primary key id; unique (object_kind, object_name).

The migration seeds 81 rows: 76 functions, the kizunasync wakeup receive policy on realtime.messages, the three cron jobs, and the kizunasync_rls role. On a conflict with a row the ledger already holds, the seed refreshes object_args and pack_version from the migration.

kizunasync._change_seq#

-- packages/supabase-pack/supabase/migrations/0001_kizuna_init.sql (excerpt)
create sequence if not exists kizunasync._change_seq as bigint cache 1;

One global sequence across all synced tables. Per-table sequences would forfeit cross-table writes-follow-reads ordering, which Consistency model states as a session guarantee. Only _stamp_transaction(), as the writing transaction commits, and _seed_changelog, under the same advisory lock held to commit, draw from it. The sequence keeps cache 1, because a cached block of numbers would let a later draw hand out a value below one that is already visible.

kizunasync._config#

Per-project table configuration, empty in the pack itself. kizunasync init upserts one row per synced table it proposed, and kizunasync sync adds and removes rows afterwards. These rows are the configuration record the CLI reads back on every later run.

Indexes and constraints: primary key table_name; check on sync_mode; check on conflict_mode; check that key_columns names at least one column. The create table statement declares conflict_journal itself, and no later add column adds it. A re-apply over an install whose _config has no key_columns column adds it last, and every existing row takes '{id}'.

kizunasync._clients#

_clients is an optional client registry, and it tracks cursor progress, last mutation, schema version, and staleness. pull and push write it through the SECURITY DEFINER helper _register_client. They write it only when the response carries no signal, a requested table has register_clients = true, and the request carries a client_id or the JWT a session_id claim. The table is the retention floor for compact_changelog() and the deletion source for prune_clients(). Exactly-once mutation replay comes from _verdicts, not from this table.

Indexes and constraints: primary key client_id; indexes (user_id) and (last_seen). _register_client rejects a registration whose user is not auth.uid(), and one whose session is not the JWT session_id. Both come back with SQLSTATE 42501. The table has no Row Level Security and grants clients nothing, so the DEFINER helper that writes it checks the caller itself. The helper refuses a caller-supplied client_id that already belongs to another user the same way, and it never reassigns that id silently, so a client that resets its local store registers under a new client_id rather than the one the previous user owns. A user keeps at most 100 registrations: each registration deletes that user's least recently seen rows beyond the 100 most recent, never the row it wrote.

kizunasync._changelog#

_changelog is zero-ALTER change tracking: one row per committed (table, pk) write, stamped with the writing transaction id. The track_change() trigger queues the write, and _stamp_transaction() numbers it and writes the row as the writing transaction commits. Each row carries the bucket value of the row it wrote, so a pull of a bucketed table reads only the rows labeled with a value it requests, through the (table_name, bucket_value, seq) index, and never scans another tenant's changes.

Indexes and constraints: primary key (table_name, pk, seq); index (seq); index (table_name, bucket_value, seq).

kizunasync._tombstones#

_tombstones holds one removal marker per application row and bucket value the row left. track_delete queues a delete, and track_change queues one for the old value when a write moves a row to another bucket value. _stamp_transaction upserts here as the writing transaction commits; when one transaction deletes the same row from the same bucket value more than once, the marker takes the last delete's number. A pull of a bucketed table reads only the markers of the values it requests, through the (table_name, bucket_value, seq) index, and never scans another tenant's deletes. On conflict, _stamp_transaction refreshes seq, deleted_at, xid, and bucket_snapshot, so the fencing horizon sees a re-delete. Because the bucket value is part of the key, a move-out and a later delete of the same row keep one marker each. An application soft-delete column stays ordinary row data and produces no tombstone.

Indexes and constraints: primary key (table_name, pk, bucket_value); index (seq); index (table_name, bucket_value, seq).

kizunasync._bucket_grants#

_bucket_grants records which bucket values each user has received live rows from. Every pull page grants its caller the (table, bucket value) pair of each row it carries, '' on an unbucketed table, through the SECURITY DEFINER helper _record_bucket_grants; a pair already granted keeps its first time. A tombstone reaches a caller only for a pair that caller holds, and a committed tombstone answers DELETE_WINS only to such a caller, as Tombstone visibility describes. A caller with no auth.uid() holds no grant. Grants never expire by age: one older than the tombstone TTL cannot be proven unneeded, because the reap horizon moves only when a tombstone is reaped. prune_clients() deletes the grants of users auth.users no longer holds. Only service_role holds SELECT.

Indexes and constraints: primary key (user_id, table_name, bucket_value).

kizunasync._change_pending#

_change_pending holds the changes a writing transaction has made and not yet numbered. track_change() and track_delete() insert one row per change, and _stamp_transaction() numbers every row as the transaction commits, writes it to _changelog or _tombstones, and deletes it. Outside an open transaction the table is therefore empty. It is UNLOGGED because no row outlives its transaction, so a crash loses only uncommitted work.

Indexes and constraints: primary key id; index (table_name, pk); check on op. The statement trigger kizunasync_arm_stamp fires once per inserting statement and arms the stamp for the transaction. authenticated, anon, and service_role hold no privilege on the table.

kizunasync._stamp_marker#

_stamp_marker holds one row per open transaction that has queued a change. _arm_stamp() inserts it at the transaction's first statement that writes _change_pending, and the row's deferred constraint trigger runs _stamp_transaction() at commit, which deletes every marker row it can see: its own, and any a disabled stamp trigger left committed. A transaction therefore holds one pending trigger event however many changes it queues. Outside an open transaction the table is empty, and it is UNLOGGED for the same reason as _change_pending.

Indexes and constraints: primary key xid. The deferred constraint trigger kizunasync_stamp_transaction fires on its insert. authenticated, anon, and service_role hold no privilege on the table.

kizunasync._row_hlc#

Per-row, per-column last-writer-wins state for tables with conflict_mode = 'hlc', which HLC mode explains. push writes it through _apply_hlc. track_delete() deletes a row's entry when the row is deleted, through push or straight from SQL.

Indexes and constraints: primary key (table_name, pk).

kizunasync._conflict_journal#

_conflict_journal holds opt-in audit rows on the server for values that an arrival-mode or HLC-mode write overwrote. Conflict history describes it for readers. The pack writes it only when the table's _config.conflict_journal is true. It draws no value from _change_seq, because it is not a change-capture stream. The journal records no increment or array transform, because those values do not travel in the columns map it reads. It also skips first writes, columns absent from the pre-image, the key columns, unchanged values (compared through the column's type, so a value written in another rendering is unchanged), values whose prior value was null, losing HLC columns, deletes, and rejected mutations. compact_changelog() deletes an entry once its winning changelog row is gone, because pull attaches an entry only beside that row.

Indexes and constraints: primary key id; index (table_name, pk, recorded_at desc); index (winner_seq); partial index (pending_id) where pending_id is not null; check on conflict_mode. Only service_role holds SELECT. Authenticated callers see a journal row only when pull attaches it to a page that already carries the winning row.

kizunasync._verdicts#

Per-mutation replay map that turns at-least-once delivery into an exactly-once apply effect. push writes it through _process_mutation, which answers a repeated mutation id from this table rather than applying the write again. A mutation id is not a secret, since a pulled conflict names the winning write's, so a replay is answered only for the user who pushed it. Any other caller gets RLS_DENIED with a null server_row, and nothing is recorded. The owner gets the recorded kind and reason, and a server_row the verdict carried is rendered again for the recorded row under the owner's current policies, because the ledger keeps no row copy. When the owner cannot read the row at the replay, or its table has no _config row at that point, a rejection carries a null server_row and an applied verdict leaves server_row out. prune_clients() deletes entries older than _settings.client_ttl_days, and a mutation replayed after that is decided again.

Indexes and constraints: primary key mutation_id; index (recorded_at).

kizunasync._reap_state#

Singleton watermark holding the highest tombstone seq that reap_tombstones() has removed. A checkpoint cursor below reaped_seq, or a continuation cursor whose start is below it, earns CHECKPOINT_EXPIRED on the next pull. The bootstrap cursor '0' never does.

Indexes and constraints: primary key id; check _reap_state_singleton requires id to be true. The migration seeds the single row.

kizunasync._settings#

Single-row server deployment configuration, not protocol: the push policy, the pull scan cap, and the retention knobs and job schedules every scheduled job reads. The pack seeds the push policy permissive and the retention columns at the pack's own defaults. kizunasync init writes every knob its flags or its wizard answered; kizunasync sync writes only the columns whose answer differs from what the project already carries. Configuration covers which flag writes which column.

Indexes and constraints: primary key id; check id; check max_batch_size is null or max_batch_size >= 1; check client_ttl_days >= 1; check hlc_max_skew_ms >= 0; check tombstone_ttl_days >= 1; check max_pull_scan >= 1; each schedule column checks kizunasync._is_cron_schedule(<column>), described under Scheduled jobs. The migration seeds (true, 500, false) plus the defaults above, and a re-applied pack keeps an existing row.

kizunasync.attachments#

Metadata for uploaded files. Bytes live in Supabase Storage and the row carries the reference, which is the split Media and attachments describes. attachment_confirm and attachment_vacuum write it, and the Supabase transfer adapter calls both. The owner reads it directly through RLS, and a peer reads it through attachment_metadata, which reaches a row only through the synced table the confirm recorded. A row has no lifecycle column: it exists only once attachment_confirm has run, and attachment_vacuum deletes it outright rather than marking it gone.

Indexes and constraints: primary key id; unique index (bucket_id, object_path), which is the confirm idempotency key. The pack enables Row Level Security on the table, and three owner-scoped policies limit SELECT, INSERT, and UPDATE to the row's created_by. authenticated holds only SELECT on the table, so the INSERT and UPDATE policies decide nothing unless an operator grants those privileges, and attachment_confirm and attachment_vacuum are the writers. Grants and security lists the policies. attachment_metadata is the one path that reads a row on a peer's behalf.

Functions#

Authenticated callers may execute exactly five functions: pull, push, attachment_confirm, attachment_metadata, and attachment_vacuum. All five are SECURITY DEFINER so a client needs no privilege on private bookkeeping; Kizuna adds a second owner for the application-row helpers, so the caller's own policies decide every row regardless. reap_tombstones, compact_changelog, prune_clients, and _schedule_jobs are maintenance functions granted to service_role only, callable by hand through kizunasync jobs run or kizunasync jobs schedule; jobs_status is a fifth service_role function beside them, an operator read rather than a maintenance action. The remaining 54 functions are internal helpers, including the three trigger functions also listed under Triggers.

kizunasync.pull#

-- packages/supabase-pack/supabase/migrations/0001_kizuna_init.sql (excerpt)
kizunasync.pull(
  buckets        jsonb,
  cursor         text,
  schema_version integer,
  "limit"        integer  default 500,
  client_id      uuid     default null
) returns jsonb

Returns

jsonb:

Real response, from packages/protocol/transcripts/pull/002-keyset-pagination.json (first page, limit: 2, has_more: true):

{
  "cursor": "0:2",
  "has_more": true,
  "rows": [
    { "pk": "00000000-0000-4000-8000-e10000000001", "row": { "done": false, "owner_id": "00000000-0000-4000-8000-a10000000001", "title": "row one" }, "seq": "1", "table": "todos" },
    { "pk": "00000000-0000-4000-8000-e10000000002", "row": { "done": false, "owner_id": "00000000-0000-4000-8000-a10000000001", "title": "row two" }, "seq": "2", "table": "todos" }
  ],
  "signal": null,
  "tombstones": []
}

A page is a prefix of one stream: the deliverable rows and tombstones together, ordered by (seq, table, pk). limit caps the entries a page holds, rows and tombstones counted together. Each list keeps the stream order. When the remaining stream holds limit entries or fewer, the page carries all of them, returns the horizon cursor described below, and sets has_more to false. An exact fit therefore closes the checkpoint in one page. Otherwise the page carries the first limit entries and sets has_more to true. Its cursor is a continuation token, <start>:<seq>: the seq of its last entry, after the checkpoint the transfer started from, 0 for a bootstrap. A tombstone travels on the page its seq falls in, like a row.

A page also stops once it has examined _settings.max_pull_scan candidates, default 5000, counting the rows it withholds because the caller's policies hide them or no bucket entry matches together with the entries it delivers. Such a page sets has_more to true even when it holds fewer than limit entries, or none, and its continuation token carries the seq of the last candidate it examined, so the next page starts after the rows it already read. A stream that ends exactly at the cap closes the checkpoint like an exact fit. A pull names at most 64 bucket entries, and a bucketed table contributes only the changelog rows labeled with a requested value, so the rows of other bucket values never count against the cap.

The pack assigns every change's sequence number when the writing transaction commits. track_change() and track_delete() queue the change in _change_pending, and a deferred constraint trigger, _stamp_transaction(), numbers every change the transaction queued at commit while it holds one transaction-scoped advisory lock. PostgreSQL makes a committing transaction visible before it releases its locks, so the numbers a snapshot sees form a gapless prefix, apart from numbers an aborted commit consumed.

A pull takes one snapshot and advances the horizon to the largest sequence number visible in it, never below the incoming high-water. No later commit can land below that number, so it is a safe place to resume. An open transaction has no sequence number yet, so it never holds back other commits. A change is deliverable as soon as its transaction's commit is visible. The page that closes the checkpoint returns a flat cursor. The pack still honors the composite form <high_water>~<hole1>.<hole2> and delivers the holes that token names. The live SQL horizon explains the same rule from the sync side.

The cost falls on writes. Transactions that change synced tables run their commit step one at a time, including the write-ahead log flush, so synced-write commits per second have a ceiling that depends on the disk's flush latency. Transactions that touch no synced table never take the lock and are unaffected. What commit-time numbering costs lists the other edges of holding that lock.

Errors and signals

A signal response echoes the incoming cursor and carries empty rows and tombstones with has_more: false. pull omits the rows the caller's policies hide, and it raises no error for them. has_more: true with signal: null means a further page exists, continued from the cursor by keyset rather than by offset. The pull wrapper also registers the caller in _clients when a requested table sets register_clients and the request carries a client_id or the JWT a session_id. It keys that registration on the request's client_id when the request carries one. A page that carries a signal registers nothing.

pull also raises one policy error rather than returning it as a signal, checked after the RESET_REQUIRED gate and before CHECKPOINT_EXPIRED:

Before any gate runs, pull refuses a limit below 1 with SQLSTATE 22023 (invalid_parameter_value) and the message kizunasync.pull(): limit must be at least 1, and a buckets array of more than 64 entries with the same SQLSTATE and the message kizunasync.pull(): a pull names at most 64 bucket entries.

Example

createRpcRemote makes this call for the app client. To make it by hand for inspection, reach the kizunasync schema through your supabase-js client. The Database type that supabase gen types writes describes public by default, so the module widens the client to the untyped SupabaseClient before it names the schema, as createRpcRemote does:

// src/kizunasync-rpc.ts
import type { SupabaseClient } from '@supabase/supabase-js'
import { supabase } from './supabase-client'

export const kizunasyncRpc = (supabase as SupabaseClient).schema('kizunasync')

The first page of a bootstrap for one user's todos bucket:

// src/inspect-sync.ts
import { kizunasyncRpc } from './kizunasync-rpc'

export async function pullFirstPage(userId: string): Promise<unknown> {
  const { data, error } = await kizunasyncRpc.rpc('pull', {
    buckets: [{ table: 'todos', params: { user_id: userId } }],
    cursor: '0',
    schema_version: 1,
    limit: 500,
  })

  if (error !== null) {
    throw error
  }

  return data
}

kizunasync.push#

-- packages/supabase-pack/supabase/migrations/0001_kizuna_init.sql (excerpt)
kizunasync.push(
  batch            jsonb,
  last_mutation_id uuid,
  schema_version   integer,
  client_id        uuid    default null
) returns jsonb

Mutation shape

Each element of batch.mutations:

Returns

jsonb, in one of three shapes. Two of them depend on atomic, and the third reports the schema gate that runs before any mutation.

Non-atomic (atomic: false, the default). Real response, push/002-rls-denied-not-a-wedge.json:

{
  "verdicts": [
    { "mutation_id": "00000000-0000-4000-8000-f10000000002", "reason": "RLS_DENIED", "server_row": null, "verdict": "rejected" },
    { "mutation_id": "00000000-0000-4000-8000-f10000000003", "verdict": "applied" }
  ]
}

Atomic (atomic: true), batch aborted. Real response, push/005-atomic-batch-revert.json:

{
  "batch": {
    "offender_mutation_id": "00000000-0000-4000-8000-f10000000002",
    "outcome": "aborted",
    "reason": "PRECONDITION",
    "server_row": { "done": false, "owner_id": "00000000-0000-4000-8000-a10000000001", "title": "claimed by device-b" }
  }
}

Stale schema. The pack checks the client's schema_version before any mutation, and the response mirrors the pull RESET_REQUIRED signal. Real response, lifecycle/003-push-stale-schema.json:

{
  "signal": { "type": "RESET_REQUIRED" }
}

An applied verdict carries server_row when the mutation ran any transform, so the client can snap optimistic state to the arbitrated total.

Verdict reasons

A mutation is one unit. A rejected verdict leaves no effect: none of its columns, transforms, _changelog entries, _conflict_journal entries, or _row_hlc stamps are written. Only the verdict recorded in _verdicts persists, and it keeps no copy of server_row.

Policy errors

Raised rather than returned as verdicts:

HLC conflict mode

For a table with conflict_mode = 'hlc', every column the mutation names resolves on its own. The pack writes a column only when the incoming HLC is strictly greater than the stored winner in _row_hlc. Before that comparison, it clamps the physical component to now() plus _settings.hlc_max_skew_ms, 5000 ms by default, so a far-future clock cannot poison the row. When every named column loses and the mutation carries no transform, the verdict is SUPERSEDED.

Example

createRpcRemote makes this call for the app client. By hand, with the kizunasyncRpc module from the pull example, one update of a todo's title looks like this:

// src/inspect-sync.ts (excerpt)
import { kizunasyncRpc } from './kizunasync-rpc'

export async function pushTitle(todoId: string, lastMutationId: string | null): Promise<unknown> {
  const { data, error } = await kizunasyncRpc.rpc('push', {
    batch: {
      mutations: [{
        mutation_id: crypto.randomUUID(),
        table: 'todos',
        pk: todoId,
        op: 'update',
        columns: { title: 'works on a plane', done: false },
      }],
      atomic: false,
    },
    last_mutation_id: lastMutationId,
    schema_version: 1,
  })

  if (error !== null) {
    throw error
  }

  return data
}

kizunasync.reap_tombstones()#

-- packages/supabase-pack/supabase/migrations/0001_kizuna_init.sql (excerpt)
kizunasync.reap_tombstones() returns bigint

No arguments. Deletes tombstone rows older than coalesce(_config.tombstone_ttl_days, _settings.tombstone_ttl_days), raises _reap_state.reaped_seq to the highest removed seq, and returns that seq, or 0 when nothing was removed. Every run stamps _reap_state.reaped_at, whether or not anything expired, so an operator can tell "nothing expired" from "the job never ran". A table with no _config row, because kizunasync sync --remove dropped it, also loses its _changelog rows older than the project default TTL and every one of its _row_hlc rows, on the same run. An unsynced table has no reader left to hold that history for. pg_cron schedules the function by default, as Scheduled jobs describes.

Errors and signals

reap_tombstones runs for a call with no JWT, such as cron's or a direct connection's, and for a JWT whose role is service_role, so an operator can also call it over the Data API on a service-role key. It refuses every other claim set that does not come from pull or push with SQLSTATE 42501, and it raises no other error. A client whose checkpoint predates the new reaped_seq, including one in the middle of a transfer that started from it, receives CHECKPOINT_EXPIRED on its next pull, then re-syncs from cursor = '0'.

Example

-- Supabase SQL editor or psql
select kizunasync.reap_tombstones();

kizunasync.compact_changelog()#

-- packages/supabase-pack/supabase/migrations/0001_kizuna_init.sql (excerpt)
kizunasync.compact_changelog() returns bigint

compact_changelog takes no arguments and removes superseded changelog rows. A row qualifies when it sits at or below a floor and a newer changelog row or a newer tombstone exists for the same (table_name, pk); a row a tombstone supersedes belongs to a deleted row that a pull could only withhold. The same run deletes every _conflict_journal entry whose winning changelog row is gone. It returns the number of deleted changelog rows. The floor is the lowest cursor high-water among clients registered in _clients with last_seen inside _settings.client_ttl_days, leaving out registrations still at cursor '0', which have pulled nothing yet. A client silent past that TTL stops holding the floor back, and prune_clients() deletes its row on the same setting. With no live client registered at all, the floor is the current sequence high-water. A project that never turns the registry on therefore still compacts its own superseded rows. The floor never sits below _reap_state.reaped_seq, because a checkpoint under that watermark answers CHECKPOINT_EXPIRED and rehydrates without the history. It refuses a client-JWT call the same way reap_tombstones does. It also runs on a schedule by default, as Scheduled jobs describes.

Example

-- Supabase SQL editor or psql
select kizunasync.compact_changelog();

kizunasync.prune_clients()#

-- packages/supabase-pack/supabase/migrations/0001_kizuna_init.sql (excerpt)
kizunasync.prune_clients() returns bigint

No arguments. Deletes every _clients row whose last_seen predates now() - _settings.client_ttl_days, and returns the number of client rows deleted. It also deletes every _verdicts entry recorded before that same cutoff, and every _bucket_grants row whose user auth.users no longer holds, whatever its age; the return value counts neither. A pruned client that syncs again registers a fresh row on its next pull or push. Refuses a client-JWT call the same way reap_tombstones does, and it is scheduled by default; see Scheduled jobs.

Example

-- Supabase SQL editor or psql
select kizunasync.prune_clients();

kizunasync._schedule_jobs()#

-- packages/supabase-pack/supabase/migrations/0001_kizuna_init.sql (excerpt)
kizunasync._schedule_jobs() returns jsonb

No arguments. The single writer of the three scheduled jobs: it unschedules each of kizunasync-reap-tombstones, kizunasync-compact-changelog, and kizunasync-prune-clients where a job of that name already exists, then reschedules all three from _settings.reap_schedule, _settings.compact_schedule, and _settings.client_prune_schedule. The pack's own install calls it once; kizunasync init, kizunasync sync, and kizunasync upgrade call it again after any write to _settings, so a later upgrade never overwrites a schedule a project customized. On a database with no pg_cron extension it schedules nothing and reports that in its return value; the three functions stay directly callable through kizunasync jobs run either way.

Returns

jsonb: { "jobs": { "kizunasync-compact-changelog": "<schedule>", "kizunasync-prune-clients": "<schedule>", "kizunasync-reap-tombstones": "<schedule>" }, "pg_cron": boolean }.

Errors and signals

The function admits the same callers as reap_tombstones: no JWT, or a JWT whose role is service_role. It refuses every other claim set without the pull/push context with SQLSTATE 42501. No other error is raised.

Example

-- Supabase SQL editor or psql
select kizunasync._schedule_jobs();
-- {"jobs": {"kizunasync-compact-changelog": "47 3 * * *", "kizunasync-prune-clients": "31 3 * * *", "kizunasync-reap-tombstones": "16 3 * * *"}, "pg_cron": true}

kizunasync.jobs_status#

-- packages/supabase-pack/supabase/migrations/0001_kizuna_init.sql (excerpt)
kizunasync.jobs_status() returns table (
  jobname text,
  schedule text,
  active boolean,
  last_start timestamptz,
  last_status text,
  last_message text
)

No arguments. The cron schema is never exposed through the Data API, so this function is the read surface for a caller that reaches the three jobs over PostgREST rather than a direct connection. It returns one row per pack job pg_cron schedules, each carrying its latest run from cron.job_run_details. last_start, last_status, and last_message are null for a job that has never run. It returns no rows at all when pg_cron is absent, the same answer _schedule_jobs() gives as "pg_cron": false.

Errors and signals

The guard is the one the maintenance functions carry: it admits a call with no JWT or a claim set whose role is service_role, which is how the operator surface reads it over the Data API, and refuses every other claim set with SQLSTATE 42501. EXECUTE is granted to service_role alone either way.

Example

-- Supabase SQL editor or psql
select * from kizunasync.jobs_status();

kizunasync.attachment_confirm#

-- packages/supabase-pack/supabase/migrations/0001_kizuna_init.sql (excerpt)
kizunasync.attachment_confirm(
  p_bucket     text,
  p_path       text,
  p_sha256     text,
  p_size       bigint,
  p_media_type text,
  p_table      text default null
) returns void

Records the integrity metadata of an object the caller uploaded in a row of kizunasync.attachments, keyed by (bucket_id, object_path). Because SECURITY DEFINER bypasses the table's RLS, the function authorizes the uploader itself: the object must exist in storage.objects with the caller's auth.uid() as its owner_id, and the path's owner segment must be the caller too. An object uploaded with the service key has no owner_id, so no user can confirm it.

The write is an insert … on conflict (bucket_id, object_path) do update. Once a row carries a hash, its hash, size, and media type never change: a call with the same values succeeds and refreshes updated_at, and a call with a different hash, size, or media type raises 23514 and changes nothing. A row recorded without a table takes the table a later confirm names, and a recorded table stays. attachment_metadata answers a peer only through that recorded table, so a confirm without p_table leaves the object's metadata readable by its owner alone.

Errors and signals

Example

The Supabase transfer adapter, createSupabaseTransfer, makes this call after each upload. The same call by hand, for a todo image in a todo-images Storage bucket, goes through the kizunasyncRpc module from the pull example:

// src/inspect-sync.ts (excerpt)
import { kizunasyncRpc } from './kizunasync-rpc'

export async function confirmTodoImage(path: string, sha256: string, size: number, mediaType: string): Promise<void> {
  const { error } = await kizunasyncRpc.rpc('attachment_confirm', {
    p_bucket: 'todo-images',
    p_path: path,
    p_sha256: sha256,
    p_size: size,
    p_media_type: mediaType,
    p_table: 'todos',
  })

  if (error !== null) {
    throw error
  }
}

kizunasync.attachment_metadata#

-- packages/supabase-pack/supabase/migrations/0001_kizuna_init.sql (excerpt)
kizunasync.attachment_metadata(
  p_bucket_id    text,
  p_object_path  text
) returns table (sha256 text, size bigint, media_type text, created_at timestamptz, updated_at timestamptz)

attachment_metadata reads integrity metadata for an object the caller did not upload, so a peer can verify bytes it is about to download without becoming that object's owner. The caller sees a row in exactly two cases. First, the caller's own attachments row carries this (bucket_id, object_path). Second, the attachments row for this (bucket_id, object_path) recorded a table_name that _config still declares, and the object path's second segment is a primary key of that table. In that case _render_user_row shows the row to the caller under its own SELECT policy, and one of the row's columns equals p_object_path.

_config declares no dedicated attachment column, so the match is "any column of the recorded table's row the caller can already read carries this exact path". That is what makes the second branch a genuine RLS check rather than a bypass: the caller only ever confirms bytes it is already allowed to see, and nobody else learns whether the row exists. Only the recorded table is rendered, so a row of another table that carries the same primary key and path reveals nothing, and a row confirmed without a table gives peers nothing. A malformed path, one whose second segment is not a UUID, returns nothing rather than raising.

Returns

Zero or one row of sha256, size, media_type, created_at, updated_at, taken from the caller's own row or the peer's, once visibility is established.

Example

The transfer adapter reads this before it downloads a peer's attachment. The function below reads it for a todo image, with the kizunasyncRpc module from the pull example:

// src/inspect-sync.ts (excerpt)
import { kizunasyncRpc } from './kizunasync-rpc'

export async function readTodoImageMetadata(path: string): Promise<unknown> {
  const { data, error } = await kizunasyncRpc.rpc('attachment_metadata', {
    p_bucket_id: 'todo-images',
    p_object_path: path,
  })

  if (error !== null) {
    throw error
  }

  return data
}

kizunasync.attachment_vacuum#

-- packages/supabase-pack/supabase/migrations/0001_kizuna_init.sql (excerpt)
kizunasync.attachment_vacuum(
  p_bucket text,
  p_path   text
) returns void

Deletes the caller's metadata row for (bucket_id, object_path) once the object is gone from storage.objects. The row must have created_by = auth.uid(), and while the object exists the call deletes nothing, so the metadata a peer verifies against stays as long as the bytes do. The path is matched, never parsed, so a path of any shape is a no-op rather than an error. The adapter calls it after the Storage object is removed. SECURITY DEFINER, written in plain SQL, with both predicates in the delete itself.

Example

The transfer adapter calls this once it has removed the Storage object. By hand, the call takes the same kizunasyncRpc module:

// src/inspect-sync.ts (excerpt)
import { kizunasyncRpc } from './kizunasync-rpc'

export async function vacuumTodoImage(path: string): Promise<void> {
  const { error } = await kizunasyncRpc.rpc('attachment_vacuum', {
    p_bucket: 'todo-images',
    p_path: path,
  })

  if (error !== null) {
    throw error
  }
}

Internal helpers#

Sixty-six further functions carry the engine, and none is granted to authenticated; four of them, track_change, track_delete, _arm_stamp, and _stamp_transaction, are also listed under Triggers. The Owner column names the role that owns the function: the ten owned by kizunasync_rls run under the caller's Row Level Security, while the rest are owned by postgres, which is what lets the ones that read or write a private ledger do so. The Gate column records whether the body opens with _require_rpc_context(), the transaction-local check described under Grants and security.

A provisioning migration calls _seed_changelog once it has attached a table's capture triggers, because rows the table held before the triggers existed have no changelog entry and no pull would deliver them. It numbers every seeded row in one statement under the advisory lock _stamp_transaction() takes and keeps the lock until the migration commits, so sequence numbers stay commit-ordered, and a second call writes nothing. It writes no _change_pending row, so seeding queues no trigger event per row. Because the lock lasts until the provisioning transaction ends, seeding a large table makes every other commit that writes a synced table wait for it. The example migration 0002_example.sql calls it for public.todos.

A provisioning migration calls _relabel_changelog after it changes a table's _config.bucket_column, because every label a pull reads names the old column until then. Each changelog row takes the new column's value from the row it names as the table holds it now, and a changelog row whose pk is gone is deleted, since its tombstone supersedes it. A tombstone whose snapshot carries the new column is re-keyed by that value, keeping the newer of two that land on the same value, and every other tombstone is deleted, because it cannot be scoped by the new column. A bucket column change therefore needs a min_schema_version bump, so every device bootstraps again. The table's bucket grants name values of the old column, so the function deletes them as well.

A provisioning migration calls _rekey_changelog after it changes a table's _config.key_columns. Every bookkeeping row of the table names a row by its pk text under the old key, which the new key cannot locate: a single-column key would miss the row, and a composite key would fail every pull on a pk that is not a JSON array. The function deletes all of them and seeds the table again under the new key, so a key change also needs a min_schema_version bump, and every device bootstraps the table from the seeded rows.

The capture triggers, the seed, the relabel, and _pull_impl run with the time zone pinned to UTC, because to_jsonb renders a timestamptz in the session's TimeZone. A timestamptz bucket value therefore spells one label, one tombstone key, and one grant value whatever time zone the writer or the puller runs in, and a pull renders timestamptz columns in UTC.

_pull_candidates reads the backlog of the requested bucket values above the cursor once without rendering it, and _pull_page renders only the rows its page reaches, at most _settings.max_pull_scan per page. A pull creates no temporary table. _push_impl raises the internal sentinel KZA01 to roll an atomic batch back and catches it in the same block, so that code never reaches a client. _decide_mutation raises the internal sentinel KZM01, carrying the rejected verdict, to roll back every write of one rejected mutation, and catches it in the same function, so that code never leaves the function.

Triggers#

The base pack creates four trigger functions. The generated config migration attaches track_change and track_delete to each synced table, and the pack itself attaches _arm_stamp to _change_pending and _stamp_transaction to _stamp_marker. All four run SECURITY DEFINER so an authenticated caller needs no write privilege on the bookkeeping tables, which is what What Kizuna installs shows per table.

kizunasync.track_change()#

-- packages/supabase-pack/supabase/migrations/0001_kizuna_init.sql (excerpt)
create or replace function kizunasync.track_change() returns trigger
language plpgsql security definer set search_path to '' set timezone to 'UTC'

The trigger fires after insert or update, queues a _change_pending row with op = 'upsert', keyed by the row's key text and labeled with the new row's bucket value, and then sends a contentless Realtime broadcast on topic kizunasync:<table_name> with event changed, once per table per transaction, as Realtime doorbell describes. The broadcast is the doorbell hint, never a data path. An update that leaves every column unchanged queues no change and sends no doorbell. The trigger compares the old and new rows as jsonb, so a table with a json, xml, or point column, types Postgres gives no equality operator, updates normally, and a json rewrite that changes only whitespace or key order counts as unchanged.

An update that changes the value of the table's _config.bucket_column moves the row out of one bucket and into another. The trigger first queues a delete for the value the row left, with that value's snapshot, and only then the upsert, so the tombstone takes the lower sequence number in the same commit. A device that received the row from the old value and pulls only that value then receives the tombstone and drops the row, and a device that pulls the new value receives the row.

kizunasync.track_delete()#

-- packages/supabase-pack/supabase/migrations/0001_kizuna_init.sql (excerpt)
create or replace function kizunasync.track_delete() returns trigger
language plpgsql security definer set search_path to '' set timezone to 'UTC'

track_delete fires after delete. It reads the table's bucket_column and key_columns from _config, projects the OLD row onto the bucket column, and queues a _change_pending row with op = 'delete', the OLD row's key text, that projection, and the OLD row's bucket value as the label. It also deletes the row's _row_hlc entry, so the HLC state goes with the row whether the delete came through push or straight from SQL. It sends the same contentless broadcast track_change sends.

Both capture triggers read the key columns in the same _config lookup as the bucket column. A table with no _config row is not synced: its triggers queue nothing, so a direct write never fails because of Kizuna.

Example

kizunasync init generates this per-table trigger pair, and the pack migration does not ship it:

-- supabase/migrations/20260928120000_todos_policies.sql
create trigger kizunasync_track_change
  after insert or update on public.todos
  for each row execute function kizunasync.track_change();

create trigger kizunasync_track_delete
  after delete on public.todos
  for each row execute function kizunasync.track_delete();

kizunasync._arm_stamp()#

-- packages/supabase-pack/supabase/migrations/0001_kizuna_init.sql (excerpt)
create or replace function kizunasync._arm_stamp() returns trigger
language plpgsql security definer set search_path to ''

_arm_stamp fires once per statement that inserts into _change_pending. At the first such statement of a transaction it records the transaction id in the transaction-local setting kizunasync.stamp_armed and inserts one _stamp_marker row; a later statement finds the setting and does nothing. A rollback to a savepoint undoes the setting, the marker row, and the marker's trigger event together, so the next queued change arms the stamp again.

-- packages/supabase-pack/supabase/migrations/0001_kizuna_init.sql (excerpt)
create trigger kizunasync_arm_stamp
  after insert on kizunasync._change_pending
  for each statement execute function kizunasync._arm_stamp();

kizunasync._stamp_transaction()#

-- packages/supabase-pack/supabase/migrations/0001_kizuna_init.sql (excerpt)
create or replace function kizunasync._stamp_transaction() returns trigger
language plpgsql security definer set search_path to '' set enable_nestloop to off

_stamp_transaction numbers every change the transaction queued, once, at commit, together with any queued change a disabled stamp trigger left committed. It takes the transaction-scoped advisory lock pg_advisory_xact_lock(1264210777, 1) and, in one statement, draws one _change_seq value per _change_pending row it can see and pairs the numbers with the rows by rank, so queue order is sequence order. An upsert becomes a _changelog row that keeps the queued arrived_at and bucket label. A delete upserts the row's tombstone for the bucket value it left, '' when there is none, taking the newest number when the transaction deleted the row from that value more than once; on a conflict it refreshes seq, deleted_at, xid, and bucket_snapshot, so a re-delete reaches pulls as a new change. The same statement copies each number into the winner_seq of the _conflict_journal row that names the queued change, clears that row's pending_id, and deletes the queued rows. The function then deletes every marker it can see and clears kizunasync.stamp_armed. Another open transaction's marker is invisible to it, so the only other markers it removes are committed leftovers of a stamp trigger that was disabled.

The function plans its statement without nested loops. _change_pending is empty between transactions, so ANALYZE and autovacuum record it as empty while it keeps its pages, and the planner then estimates one queued row however many there are. A nested loop over the statement's materialized CTEs would make a large commit quadratic while every other synced write waits on the same lock.

The lock lasts until the transaction ends, so a transaction that commits later draws later numbers. A caller that runs SET CONSTRAINTS kizunasync.kizunasync_stamp_transaction IMMEDIATE makes the stamp run at that point, and the next queued change arms it again. The function does not call _require_rpc_context(), because a direct SQL write to a synced table must be numbered too. pull explains why numbers drawn at commit make the largest visible sequence number a safe cursor.

The pack attaches the function to the marker table, deferred to commit:

-- packages/supabase-pack/supabase/migrations/0001_kizuna_init.sql (excerpt)
create constraint trigger kizunasync_stamp_transaction
  after insert on kizunasync._stamp_marker
  deferrable initially deferred
  for each row execute function kizunasync._stamp_transaction();

Scheduled jobs#

pg_cron is optional, and the pack tries to give the project one the way Supabase's own install guide does. Its install block is the single statement create extension if not exists pg_cron with schema pg_catalog; inside a do $$ ... exception when ... then null; end $$, and it grants nothing on the cron schema: on the Supabase image an event trigger gives postgres what it needs on every create extension and keeps cron.job read-only, and _schedule_jobs() changes jobs only through cron.schedule() and cron.unschedule(). The wrapper absorbs every SQLSTATE meaning "this server will not give us cron": 0A000 when the extension is not available at all, P0001 when pg_cron refuses a database other than the one named by cron.database_name, and the defensive undefined_file, insufficient_privilege, and object_not_in_prerequisite_state. The install continues clean either way. That block is never ledgered, and kizunasync deprovision never drops the extension, because another schema in the same database may depend on it. The three retention functions stay directly callable through kizunasync jobs run whether or not the extension is present. A config migration that kizunasync init or kizunasync sync generates carries its own gate ahead of the tables it provisions, and refuses to apply with kizunasync: pg_cron is not enabled on this database unless the run passed --allow-no-cron.

Schedules come from _settings, and _schedule_jobs() is the only function that writes them into cron.job. The pack's own install calls it once, and kizunasync init, kizunasync sync, and kizunasync upgrade call it again after any write to _settings, so a re-applied pack never resets a schedule a project customized.

Each schedule is a five-field crontab (minute, hour, day-of-month, month, day-of-week), validated by _is_cron_schedule both at the _settings check constraint and, before a write reaches the database, by the matching Rust grammar in kizunasync. kizunasync jobs list reads the live schedule, the last run, and its status from cron.job and cron.job_run_details; kizunasync doctor reports the extension and job health as project checks.

Retention#

Every pack table keeps its rows until one of the paths below removes them. The three jobs cover the tables that grow with traffic, and the rest shrink only through a call or a CLI run.

A table with no _config row, because kizunasync sync --remove dropped it, has no reader left, so the jobs empty its bookkeeping without waiting for a client. On its next run reap_tombstones() deletes the table's tombstones and changelog rows older than _settings.tombstone_ttl_days and every one of its _row_hlc entries, and the next compact_changelog() deletes the conflict-journal entries whose winning changelog row went with them. Its bucket grants stay until their user is deleted, and the verdicts of its mutations stay until they pass client_ttl_days.

Grants and security#

The public RPCs are postgres-owned SECURITY DEFINER wrappers over private bookkeeping. They delegate every application-row read and write to a second set of SECURITY DEFINER helpers, owned by kizunasync_rls. That role is a NOBYPASSRLS member of authenticated, so the policies on the application table remain the authorization boundary.

What authenticated deliberately does not get#

• No table privilege on any bookkeeping table. pull and push are SECURITY DEFINER and never need a client SELECT on the change stream, and the change-capture triggers are SECURITY DEFINER too, so no client INSERT or UPDATE on _change_pending, _changelog, or _tombstones is required.
• No EXECUTE on any internal helper. Only the five public RPCs are granted.
• No USAGE on _change_seq, so a client cannot burn or forge a sequence number.
• No EXECUTE on reap_tombstones, compact_changelog, prune_clients, _schedule_jobs, or jobs_status, which cron, kizunasync jobs run, or the sync inspector's service-role connection calls instead. All five refuse every claim set that does not carry role: service_role regardless, so the service_role grant widens the operator surface only.
• No default-privileges mechanism protects a newly created function. A per-schema default-privileges entry only adds to PostgreSQL's built-in defaults, and it cannot subtract the built-in PUBLIC execute default. A role-global entry leaks into every other schema in the database. The pack uses one explicit blanket revoke instead, and that statement runs after the last create function. Any migration that adds a function carries its own revoke. The audit test packages/supabase-pack/tests/rpc-privilege-lockdown.test.ts enforces that discipline.

GUC call gate#

Twenty-five of the internal helpers open with _require_rpc_context(), which raises 42501 unless current_setting('kizunasync.rpc') is '1'. Only pull and push set it, and only for their own transaction. The rest carry no such call, each for its own reason. The three trigger functions fire from ordinary application DML or from its commit and would break under the gate. The codec, comparison, matching, grammar, and envelope helpers hold no privileged state. _render_user_row reads under the caller's own policies, and _register_client checks the JWT user and session itself. _seed_changelog, _relabel_changelog, and _rekey_changelog run from a provisioning migration, outside any pull or push, and refuse any call that carries a JWT. Only _pull_envelope reaches _conflicts_for_page. With the grants above, a direct Data API call to any of them already fails on missing EXECUTE. The gate is the second line if a role ever gains one.

How application-row authorization works#

The caller's own Row Level Security is the sole authorization boundary, and the pack holds no ownership opinion. The kizunasync_rls owner cannot bypass RLS and inherits request.jwt.claims, so auth.uid() inside a helper is the real caller. A public-read table using using (true) returns every row, and a stricter policy filters the result. A tenant table's own policy authorizes against the tenant value, rather than comparing a column to auth.uid(). The bucket column only scopes which permitted rows a pull selects, as Sync rules and buckets explains. The three attachment RPCs are the exception in form only. They bypass the attachments policies as DEFINER and authorize the caller themselves. attachment_confirm requires a Storage object the caller owns under its own owner segment, attachment_vacuum deletes only a row whose created_by is auth.uid(), and attachment_metadata reads either the caller's own row or the caller's own RLS on the recorded table's row.

Column-level privileges#

Row Level Security decides which rows a caller reaches; Postgres's own column-level GRANT and REVOKE decide which columns of a reachable row a caller reads or writes, and the pack applies neither on the project's behalf. pull renders only the columns _readable_columns reports authenticated may SELECT, so a restricted column is absent from row rather than rendered as null. A pull is refused with KZL02 when a key column or the bucket_column of a requested table is unreadable, because those are the columns a pull selects to run at all. A push refuses a mutation that writes a column outside _writable_columns with the verdict reason COLUMN_DENIED, before applying anything else in that mutation, and server_row carries the row narrowed to the columns the caller may read. Both probes resolve the caller's role through _caller_role: the transaction's SET ROLE first, the JWT role claim next, authenticated last. The conflict journal never surfaces a column authenticated cannot read, for the same reason pull omits it. Column privileges are granted to a role, not to a row, so every authenticated caller sees the same column projection regardless of which row they reach.

Supabase documents column-level security as an advanced feature: it is applied by hand in SQL or from the dashboard's policy editor, and neither the Supabase CLI nor supabase db diff manages or diffs it. Supabase also notes the Postgres ordering this depends on: a column-level REVOKE only narrows access once the table-level privilege is revoked too, because has_column_privilege folds a table-level grant into every column it covers regardless of a narrower column-level grant sitting beside it. Column Level Security covers both points. kizunasync doctor's column-privileges check reports what a project's own grants currently allow.

Tombstone visibility#

A deleted row's image never travels, and only its primary key does. A tombstone rides the page when three conditions hold. Its key names a requested bucket value and its stored bucket_snapshot matches the pull params on the bucket column, since a bucket's other params filter live rows only. The caller holds a bucket grant for its table and bucket value, meaning an earlier pull delivered that caller a live row of the pair. Finally, the row's current state is not deliverable to the caller: it is gone, hidden by the caller's policies, or outside every requested bucket. Naming another tenant's bucket value therefore reveals none of its deleted keys, and a first pull carries no tombstone of a bucket value it had not received before. An unscoped pull of a bucketed table is refused with KZL01 before any page is built. Unbucketed tables stay table-scoped under the grant ''.

A row that a write moves to another bucket value leaves the old value a tombstone as well, which reaches the callers that received the row from the old value. A row that moved to another requested value, or was recreated where the caller can see it, travels as a row instead, so a caller that pulls both the old and the new value keeps the row, and a caller that cannot see a recreated row still drops its stale copy.

A policy stricter than the bucket does not replay on a row that is gone, and grants never expire by age, so two residuals remain. Members of the same bucket value receive the deleted keys of rows they never saw, and a member removed from a bucket keeps receiving the deletions of that bucket value. A table whose Row Level Security is finer than its bucket should mark removals with its soft_delete_column, so each removal travels as an ordinary row update under the caller's policies.

Row Level Security policies#

The pack creates four:

Each one wraps the call as (select auth.uid()) so PostgreSQL caches the JWT lookup per statement. There is no send policy on realtime.messages: the trigger functions emit through realtime.send as SECURITY DEFINER, so no send policy is needed. Realtime authorization covers how a private channel reads that topic.

What a caller can still learn#

A few signals cross the authorization boundary in one direction: never a row, only that something happened to one. The Realtime doorbell names the table on its topic, and the kizunasync wakeup receive policy admits every authenticated caller, so any signed-in user can watch when a table it cannot read is written, never what changed. The pull horizon is one sequence numbered across every synced table by the same stamp lock, so a caller's own cursor reflects commit activity on tables outside its own policies as well as its own; What commit-time numbering costs covers the same lock from the write side. An error a pull or a push raises names the table and, on a bucketed table, the bucket column, because the schema and bucket gates run before Row Level Security does and have nothing else to report.

Danger: Row Level Security must be enabled on every synced table. pull and push reach application rows through kizunasync_rls, and Postgres applies no policy at all to a table with Row Level Security disabled, to that role or any other, so a pull or a push hands every row to any signed-in caller. kizunasync init and kizunasync sync refuse to sync a table in that state unless the run passes --allow-no-rls.

A trigger function the project attaches to a synced table runs in the same transaction as track_change() and track_delete(). Set a fixed search_path on it the same way those two do, so a schema earlier on the caller's default path cannot shadow an unqualified reference inside it. Retention lists what removes each bookkeeping table's rows, none of it reachable by a signed-in caller.

The surrounding project#

The pack rides a Supabase project its owner operates, so TLS, Auth, and RLS remain platform controls rather than a second Kizuna data plane. The following are project settings, not pack behavior:

• A client carries a publishable key or the legacy anon JWT. A client never ships a secret key, because security rests on policies rather than on key secrecy.
• Policies authorize on auth.uid() and app_metadata, never on user-editable user_metadata.
• Rotating to asymmetric JWT signing keys replaces reliance on the legacy JWT secret.
• Network restrictions, Auth CAPTCHA, leaked-password protection, and a shorter access-token expiry stay available. A JWT remains valid until it expires, even after sign-out or user deletion.
• Clients point at the HTTPS project URL. The native HTTP stack uses rustls and trusts the Mozilla root certificates compiled into it rather than the device's certificate store, and it adds no certificate pinning.

Local ports#

Defined in packages/supabase-pack/supabase/config.toml, which also sets the shadow database port to 55320. The kizunasync schema is exposed through the Data API alongside public and graphql_public, which is what makes the two RPCs callable. Local Supabase covers running the stack.

Pack vs demo#

The Supabase CLI reads one migrations directory, so the installable pack and the local demo fixtures share packages/supabase-pack/supabase/migrations/. pack.manifest.json beside that directory is the machine-readable record of which file is which, and kizunasync init reads it when emitting SQL into a real project. The $comment key at the top of the file is omitted here:

{
  "pack": ["0001_kizuna_init.sql"],
  "demo": [
    "0002_example.sql"
  ]
}

The demo file creates the example table, its Storage setup, sample identities, the soft-delete column, and the shared-board and rate-limit policies. It is a local fixture and does not belong in an application's migration set.

The CLI records a full-file hash in a pack-file ledger row for version reconciliation. Object rows use name-derived identity hashes, and they drive teardown. The tables, indexes, sequence, and schema carry no object row, so a teardown leaves them in place. It never infers or removes unledgered application data, which Remove shows step by step.

Realtime doorbell#

track_change and track_delete call realtime.send with the payload {"t": "<table>"}, event changed, topic kizunasync:<table>, and the private flag set. The payload exists to satisfy the function signature: a client subscribes to the topic, discards what arrives, and pulls. A missed signal delays the next pull and loses nothing, because the poll fallback and the cursor carry correctness on their own.

A transaction sends one doorbell per table, however many of its rows it writes. The first write of a table sets a transaction-local flag with set_config(..., true), named by the table's oid, and a later write of that table in the same transaction finds the flag and sends nothing, so a push that writes 500 rows of one table sends one Realtime message. A subtransaction that rolls back takes its flag and its message with it. realtime.send never raises, so a doorbell that is not delivered is caught by the client's poll.

A third emitter sits in _register_client, which sends {"t": "_clients"} on topic kizunasync:clients after it upserts a registration row, once per transaction by the same kind of flag. The kizunasync wakeup receive policy matches kizunasync:%, so that topic is readable by the same authenticated callers, and no client in this repository subscribes to it.

On the client side, createRealtimeWakeup from kizunasync/supabase subscribes to those channels and implements the IWakeup port. createSupabaseKizunaSync builds one for the config's tables unless the config sets realtimeWakeups: false, so an app calls it directly only to pass its own wakeup. Its topicPrefix option must match the kizunasync prefix the triggers use, and its private option must stay true while the kizunasync wakeup receive policy gates the topic.

// src/kizunasync.ts (excerpt)
import { createRealtimeWakeup } from 'kizunasync/supabase'
import { supabase } from './supabase-client'

const wakeup = createRealtimeWakeup(supabase, {
  tables: ['todos'],
  topicPrefix: 'kizunasync',
  private: true,
})

Related reference#

• What Kizuna installs: the same objects, grouped as a provisioning checklist.
• Local Supabase: start, migrate, reset, stop.
• Sync rules and buckets: _config rows and bucket filters.
• Media and attachments: attachment_confirm and attachment_vacuum in use.
• Fencing and horizons: commit-time numbering, the pull horizon, and cursor semantics.
• Protocol reference: the wire shapes these RPCs produce.
• CLI: kizunasync init, kizunasync deprovision, kizunasync doctor.
• Configuration: the _config and _settings columns, and what writes each one.
• CI and CD: the job that replays transcript families against this pack.