Skip to Content
v0.5.4-rc.1 Release

KalamDB v0.5.4-rc.1 Release

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.

SQL: INSERT … RETURNING

INSERT statements can now return affected rows directly in the SQL response.

Supported syntax:

SQL
INSERT INTO users (id, name, age) VALUES (1, 'Nader', 3) RETURNING *;INSERT INTO users (id, name, age) VALUES (1, 'Nader', 3) RETURNING id, name;

Behavior:

  • RETURNING * returns all table columns in schema order
  • RETURNING col1, col2, ... returns a selected projection
  • Works for single-row and multi-row INSERT
  • API responses include the returned rows in the standard results[].rows shape
  • Parameterized inserts support RETURNING over HTTP and through the SDKs

SQL: INSERT … ON CONFLICT (upsert)

PostgreSQL-style upsert is supported on the primary key conflict target.

SQL
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 *;
FeatureBehavior
ON CONFLICT (pk) DO UPDATE SET ...Updates existing row; unassigned columns are preserved
EXCLUDED.columnReferences the proposed insert values
ON CONFLICT (pk) DO NOTHINGSkips conflicting rows
DO UPDATE ... WHEREApplies update only when the predicate is true
RETURNING with DO NOTHINGReturns zero rows for skipped conflicts
Multi-row upsertOne returned row per input row (insert or update)
User tablesConflicts are scoped per user (RLS isolation)
Shared tablesConflicts are global on the primary key

Limitations (current release):

  • Conflict target must be the table’s primary key column
  • ON CONFLICT ON CONSTRAINT is not supported
  • Non-primary-key unique targets are rejected with a clear error

TypeScript ORM (@kalamdb/orm)

Drizzle-style upsert and returning now work end-to-end:

typescript
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();

Live OKF Context Sync example

A new showcase app under examples/live-okf-context-sync/ demonstrates syncing a Google Open Knowledge Format (OKF) folder into KalamDB for multi-client AI agent context.

  • Per-user OKF Markdown folders synced into KalamDB via a Node sync worker
  • File metadata in a user-scoped SQL table; bytes via KalamDB FILE upload/download
  • Local folder watch (push) + liveTable() pull with a SQLite hash cache under .index/
  • Schema-first workflow: kalam/schema.sql is the source of truth; TypeScript types are generated via @kalamdb/orm
  • Live subscriptions so every sync worker sees metadata changes in realtime
  • Delete local data/ and restart — files restore from the server (KalamDB is the source of truth)

Docs: Live OKF Context Sync

CLI and dev workflow

  • kalam dev improvements — stronger prechecks for auth, paths, and server readiness before starting dev processes
  • Project init refactor — cleaner scaffolding for TypeScript projects and connection URL handling
  • Self-update — more reliable version comparison (version first, then build date for same-version rebuilds)
  • Update-check tests — version-bump-proof; no longer require editing hardcoded release numbers on each release
  • run-tests.sh — improved running-server credential validation and supplementary suite orchestration

Security and auth

  • OIDC bearer auth fix — closes a repository bypass where OIDC bearer tokens could skip expected authorization checks
  • Auth endpoint hardening — login, setup, and OIDC exchange paths tightened for consistency

Upgrade notes

  1. Rebuild or update server and CLI to 0.5.4-rc.1
  2. TypeScript projects — bump @kalamdb/* packages together; run npm install to refresh lockfiles
  3. Upsert adoption — replace read-then-write patterns with ON CONFLICT ... DO UPDATE where appropriate
  4. RETURNING — use instead of a follow-up SELECT after inserts when you need the written row
  5. OKF example — requires kalam dev (starts server, applies schema, generates ORM types)

Release post

For the narrative announcement with SQL examples, the OKF context sync summary, and release links, read the KalamDB v0.5.4-rc.1 pre-release blog post.

Last updated on
Overviewv0.5.3-rc.1 Release