kalamstack/KalamDB](https:

Highlights

This release adds PostgreSQL-style upsert and returning semantics for INSERT, a new Live OKF Context Sync example for multi-client agent context, and a broad round of CLI workflow, auth, and test hardening.

SQL: INSERT ... RETURNING

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

Supported syntax:

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 now supported on the primary key conflict target.

Supported syntax:

-- Upsert with returned row
INSERT INTO users (id, name, age) VALUES (1, 'Nader Updated', 5)
ON CONFLICT (id) DO UPDATE
  SET name = EXCLUDED.name, age = EXCLUDED.age
RETURNING *;

-- Skip duplicate, return nothing
INSERT INTO users (id, name, age) VALUES (1, 'Ignored', 99)
ON CONFLICT (id) DO NOTHING
RETURNING *;

-- Conditional update on conflict
INSERT INTO users (id, name, age) VALUES (1, 'Ignored', 99)
ON CONFLICT (id) DO UPDATE SET age = EXCLUDED.age
WHERE false
RETURNING *;

Semantics:

| Feature | Behavior |
|---|---|
| ON CONFLICT (pk) DO UPDATE SET ... | Updates existing row; unassigned columns are preserved |
| EXCLUDED.column | References the proposed insert values |
| ON CONFLICT (pk) DO NOTHING | Skips conflicting rows |
| DO UPDATE ... WHERE <expr> | Applies update only when the predicate is true |
| RETURNING with DO NOTHING | Returns zero rows for skipped conflicts |
| Multi-row upsert | One returned row per input row (insert or update) |
| Type/constraint errors | Statement fails atomically; no partial writes |
| User tables | Conflicts are scoped per user (RLS isolation) |
| Shared tables | Conflicts 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:

// INSERT ... RETURNING
const rows = await db
  .insert(users)
  .values({ id: 1, name: 'Nader', age: 3 })
  .returning();

// INSERT ... ON CONFLICT DO UPDATE 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();

New Example: Live OKF Context Sync

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.

What it shows:

• Per-user OKF Markdown folders (context/alice/, context/bob/) synced into KalamDB
• File metadata in a user-scoped SQL table; bytes via KalamDB FILE upload/download
• Multiple clients sharing live context: sync worker, web UI, local agent, cloud agent
• Schema-first workflow: kalam/schema.sql is the source of truth; TypeScript types are generated via @kalamdb/orm
• Live subscriptions so all clients see metadata changes in realtime
• Conflict detection when the same file is edited on multiple devices

Docs: Live OKF Context Sync

CLI & 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 & 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

Stability & Internal Improvements

• Dialect parser refactor — dedicated kalamdb-dialect modules for INSERT shape, VALUES, literals, and ON CONFLICT parsing; execution stays in kalamdb-core
• SQL executor — upsert and returning integrated into the applier fast path and transaction batch insert path
• DataFusion 54 — continued alignment with Apache DataFusion 54 SQL features
• Parquet I/O — reader/writer improvements in kalamdb-filestore
• Link crates — WASM and Python bridge cleanup
• Bench reporter — minor HTML reporter fix
• Release workflow — CI/release pipeline updates for the new version cohort

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)

Full Changelog: https://github.com/kalamdb/KalamDB/compare/v0.5.3-rc.1...v0.5.4-rc.1