-TLgmZcK1heam1n69RVEGBCFlYidxUF.jpeg&w=128&q=75)
KalamDB v0.5.4-rc.1 is the June 25 pre-release for PostgreSQL-style INSERT ... RETURNING and ON CONFLICT upsert, the Live OKF Context Sync example, and CLI, auth, and test hardening.
What changed in v0.5.4-rc.1
This pre-release focuses on write-path SQL that agents actually use: return the row you just wrote, upsert on conflict instead of read-then-write, and share live file context across clients.
SQL: INSERT ... RETURNING
INSERT statements can now return affected rows directly in the SQL response. Use RETURNING * for all columns or RETURNING col1, col2 for a projection. It works for single-row and multi-row inserts over HTTP and through the SDKs. API responses include the returned rows in the standard results[].rows shape.
INSERT INTO users (id, name, age) VALUES (1, 'Nader', 3) RETURNING *;INSERT INTO users (id, name, age) VALUES (1, 'Nader', 3) RETURNING id, name;SQL: INSERT ... ON CONFLICT (upsert)
PostgreSQL-style upsert is supported on the primary key conflict target. DO UPDATE preserves unassigned columns, EXCLUDED.column references proposed insert values, DO NOTHING skips conflicts, and optional WHERE predicates gate conditional updates.
INSERT INTO users (id, name, age) VALUES (1, 'Nader Updated', 5)ON CONFLICT (id) DO UPDATE SET name = EXCLUDED.name, age = EXCLUDED.ageRETURNING *; INSERT INTO users (id, name, age) VALUES (1, 'Ignored', 99)ON CONFLICT (id) DO NOTHINGRETURNING *;On user tables, conflicts are scoped per user. Shared tables use global primary-key conflicts. Multi-row upserts return one row per input row. Type and constraint errors fail the statement atomically.
Current limitations: the conflict target must be the table primary key, ON CONFLICT ON CONSTRAINT is not supported, and non-primary-key unique targets are rejected with a clear error.
TypeScript ORM
Drizzle-style upsert and returning now work end-to-end in @kalamdb/orm:
const rows = await db .insert(users) .values({ id: 1, name: 'Nader', age: 3 }) .returning(); const updated = await db .insert(users) .values({ id: 1, name: 'Nader Updated', age: 5 }) .onConflictDoUpdate({ target: users.id, set: { name: sql`excluded.name`, age: sql`excluded.age` }, }) .returning();FILE uploads through Drizzle use kalamFile(name, blob) in .values() / .set(). See Live OKF Context Sync for a folder-sync example that upserts FILE columns with onConflictDoUpdate.
New example: Live OKF Context Sync
A new showcase app under examples/live-okf-context-sync/ syncs a Google Open Knowledge Format (OKF) Markdown folder into KalamDB for multi-client AI agent context. File metadata lives in a user-scoped SQL table; bytes flow through KalamDB FILE upload and download. Multiple clients — sync worker, web UI, local agent, cloud agent — share live context with conflict detection when the same file is edited on multiple devices.
Start with kalam/schema.sql as the source of truth, run kalam dev to apply schema and regenerate ORM types, then follow the Live OKF Context Sync use-case docs.
CLI, auth, and stability
kalam dev now runs stronger prechecks for auth, paths, and server readiness. Project init scaffolding is cleaner for TypeScript projects. Self-update compares version first, then build date for same-version rebuilds. OIDC bearer auth closes a repository bypass, and login, setup, and OIDC exchange paths are tightened. Internally, INSERT parsing moved into kalamdb-dialect modules while execution stays in kalamdb-core.
