feat: type-safe JSON insertions/updates, eb.jval & sql.jval.

[igalklebanov]

Hey 👋

JSONColumnType demands manual serialization before passing values in insertions/updates. Once you do that, it is not that type-safe - you can pass any string value really.

This PR deprecates JSONColumnType, and introduces the stricter Json type that enforces type-safe insertions/updates.

Using a branded type as the InsertType and UpdateType AND as the return value of new serialization helpers in ExpressionBuilder and sql template tag, users can now insert/update and serialize their JSON objects/arrays safely into JSON columns.

Compilers/plugins can serialize the objects/arrays differently, as the value is passed around in a ValueNode with a serialized flag. The default serialization method is, well, JSON.stringify.

db.insertInto('person_metadata')
  .values((eb) => ({
    website: eb.jval({ url: 'https://kysely.dev' }),
    // or...
    experience: sql.jval([{
      establishment: 'The University of Life',
    }]),
  }))

If you want the non-type-safe old JSONColumnType.. we don't encourage it, but you can continue using JSONColumnType (until we decide to remove it) or just use:

import type { ColumnType } from 'kysely'

type MetadataColumn = ColumnType<YourJSONType, string, string>

For a readonly Json, use:

import type { ColumnType, Json, Serialized } from 'kysely'

type MetadataColumn = Json<YourJSONType, Serialized<YourJSONType>, never>

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
kysely	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Aug 9, 2025 9:21pm

[ethanresnick]

Love this conceptually, but really think the function name should be more explicit (e.g., eb.jsonVal). Imo, the clarity (including for AI models) is absolutely worth the extra three characters.