Skip to content

v0.5.4-rc.1

Latest
Latest

Choose a tag to compare

View all tags
@github-actions github-actions released this 25 Jun 15:42
· 11 commits to b71eef41dd6b9434c4a8724137192f523aed69e7 since this release
v0.5.4-rc.1
f4477af
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

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: v0.5.3-rc.1...v0.5.4-rc.1

What's Changed

Full Changelog: v0.5.3-rc.1...v0.5.4-rc.1

What's Changed

Full Changelog: v0.5.3-rc.1...v0.5.4-rc.1

What's Changed

Full Changelog: v0.5.3-rc.1...v0.5.4-rc.1

Contributors

jamals86
Assets 16
Loading