Hey 👋

This one's a banger! 💥 💥 💥

pnpm i kysely@next

We got $pickTables, $omitTables compile-time helpers to narrow the world view of downstream queries, cutting down on compilation complexity/time while at it!

const results = await db
  .$pickTables<'person' | 'pet'>() // <----- now `DB` is only { person: {...}, pet: {...} } for following methods.
  .selectFrom('person')
  .innerJoin('pet', 'pet.owner_id', 'person.id')
  .selectAll()
  .execute()

const results = await db
  .$omitTables<'toy'>() // <----- now `DB` doesn't have a "toy" table description for following methods.
  .selectFrom('person')
  .innerJoin('pet', 'pet.owner_id', 'person.id')
  .selectAll()
  .execute()

We got a new ReadonlyKysely<DB> helper type that turns your instance into a compile-time readonly instance!

import { Kysely } from 'kysely'
import type { ReadonlyKysely } from 'kysely/readonly'

export const db = new Kysely<Database>({...}) as never as ReadonlyKysely<Database>

db.selectFrom('person').selectAll() // no problem.
db.selectNoFrom(sql`now()`.as('now')) // no problem.

db.deleteFrom('person') // compilation error + deprecation!
db.insertInto('person').values({...}) // compilation error + deprecation!
db.mergeInto('person')...  // compilation error + deprecation!
db.updateTable('person').set('first_name', 'Timmy') // compilation error + deprecation!
sql`...`.execute(db) // compilation error!
// etc. etc.

We got a brand new PGlite dialect. With it comes a new supportsMultipleConnections adapter flag that uses a new centralized connection mutex when false - should help simplify all SQLite dialects out here!

import { PGlite } from '@electric-sql/pglite'
import { Kysely, PGliteDialect } from 'kysely'

const db = new Kysely<DB>({
  // ...
  dialect: new PGliteDialect({
    pglite: new PGlite(),
  }),
  // ...
})

We got $narrowType supporting nested narrowing and discriminated unions!

db.selectFrom('person_metadata')
  .select(['discriminatedUnionProfile']) 
  // output type inferred as:
  //
  // {
  //   discriminatedUnionProfile: {
  //     auth:
  //       | { type: 'token'; token: string }
  //       | { type: 'session'; session_id: string }
  //     tags: string[]
  //   }
  // }[]
  .$narrowType<{ discriminatedUnionProfile: { auth: { type: 'token' } } }>()
  // output type narrowed to:
  // 
  // {
  //   discriminatedUnionProfile: {
  //     auth: { type: 'token'; token: string }
  //     tags: string[]
  //   }
  // }[]
  .execute()

We got web standards driven query cancellation support. Pass an abort signal to execute* methods and similar. Pick between different inflight query abort strategies - ignore the query, cancel it on the database side or even kill the session on the database side.

  import { Kysely, PostgresDialect } from 'kysely'
  import { Client, ... } from 'pg'

  const db = new Kysely<Database>({
    dialect: new PostgresDialect({
      // ...
      controlClient: Client, // optional, for out-of-pool connections for database side query aborts.
      // ...
    })
  })

  const options = { signal: AbortSignal.timeout(3_000) } // throw abort/timeout errors and ignore query reuslts

  query.execute(options)
  query.stream(options)
  sql`...`.execute(db, options)
  db.executeQuery(compiledQuery, options)
  // etc. etc.

  query.execute({ ...options, inflightQueryAbortStrategy: 'cancel query' }) // also cancel query database side
  query.execute({ ...options, inflightQueryAbortStrategy: 'kill session' }) // also kill session database side

We got SafeNullComparisonPlugin to flip (in)equality operators to is and is not when right hand side argument is null.

import { Kysely, SafeNullComparisonPlugin } from 'kysely'

const db = new Kysely<DB>({
  // ...
  plugins: [new SafeNullComparisonPlugin()],
  // ...
})

db.selectFrom('pet')
  .where('name', '=', null) // outputs: "name" is null
  .where('owner_id', '!=', null) // outputs: "owner_id" is not null
  .selectAll()

We got a new shouldParse(value, path) option in ParseJSONResultsPlugin for granular control of what gets JSON.parse'd and what stays a string using JSON paths.

import { JSONParseResultsPlugin } from 'kysely'

db.selectFrom('person')
  .select((eb) => jsonArrayFrom(
	  eb.selectFrom('pet')
      .where('pet.owner_id', '=', 'person.id')
 	    .selectAll()
  ).as('pets'))
  .withPlugin(new JSONParseResultsPlugin({ 
    shouldParse: (_value, path) => {
      // parse only the pets array
      if (path.endsWith('.pets')) {
        return true
      }
    
      return false
    } 
  }))

🚀 Features

• feat(utils): Allow explicit undefined in Updateable type (for exactOptionalPropertyTypes support) by @y-hsgw in #1496
• feat(migrator): allow disabling transactions in migrate methods. by @igalklebanov in #1517
• feat: add thenRef method in eb.case by @ericsodev in #1531
• feat: add whenRef(lhs, op, rhs) in eb.case. by @iam-abdul in #1598
• feat: add elseRef in eb.case() by @iam-abdul in #1601
• feat: add $pickTables, $omitTables and $extendTables, deprecate withTables. by @igalklebanov in #1582
• feat: add SafeNullComparisonPlugin plugin by @rafaelalmeidatk in #1338
• feat: add more control through configuration @ ParseJSONResultsPlugin. by @igalklebanov in #1453
• feat: allow expressions in create/add index's column and columns functions, deprecate their expression functions. by @igalklebanov in #1664
• feat: add with(name, query). by @igalklebanov in #1702
• feat: expose migrations from 'kysely/migration'. deprecate migration exports in root. by @igalklebanov in #1618
• refactor: bump minimum TypeScript version to 4.7. by @igalklebanov in #1696
• refactor: bump minimum TypeScript version to 4.8. by @igalklebanov in #1756
• refactor: bump minimum TypeScript version to 4.9. by @igalklebanov in #1759
• refactor: bump minimum TypeScript version to 5.0. by @igalklebanov in #1761
• refactor: bump minimum TypeScript version to 5.1. by @igalklebanov in #1770
• refactor: bump minimum TypeScript version to 5.2. by @igalklebanov in #1771
• refactor: bump minimum TypeScript version to 5.3. by @igalklebanov in #1772
• refactor: bump minimum TypeScript version to 5.4. by @igalklebanov in #1773
• feat: support narrowing by deep object keys in NarrowPartial by @ethanresnick in #1667
• feat: add ReadonlyKysely<DB> helper. by @igalklebanov in #218
• refactor: replace requireAllProps<T>(obj) usage with satisfies AllProps<T>. by @igalklebanov in #1787
• feat: allow overriding file import function @ FileMigrationProvider. by @igalklebanov in #1661
• feat: query cancellation. by @igalklebanov in #1796 & #1797 & #1798 & 33e60df & b739e02 & 4d7064f

PostgreSQL 🐘 / MySQL 🐬

• feat(Introspect): add support for postgres & mysql foreign tables by @williamluke4 in #1494

PostgreSQL 🐘 / MSSQL 🥅

• feat(Migrator): allow passing transactions to Migrator. by @jlucaso1 in #1480
• feat: support IF EXISTS in DROP COLUMN by @shuaixr in #1692

PostgreSQL 🐘

• feat: support dropping multiple types with schema.dropType(), cascade. by @aantia in #1516
• feat: add alter type query support. by @lucianolix in #1363

MySQL 🐬

• feat: allow expressions in unique constraint by @ericsodev in #1518
• feat: Add support for dropping temporary tables with temporary() modifier by @szalonna in #1615
• feat: add addIndex to CreateTableBuilder by @alenap93 in #1352

MSSQL 🥅

• feat: add datetime2 data type support. by @igalklebanov in #1792

PGlite 🟨

• feat: add PGlite dialect. by @igalklebanov in #1510

🐞 Bugfixes

📖 Documentation

• docs(returning): remove outdated SQLite alias workaround by @aymenhmaidiwastaken in #1793

📦 CICD & Tooling

• chore: improve TypeScript benchmarks. by @igalklebanov in #1757
• chore: add returning.bench.ts by @igalklebanov in 65b6ec4abe15101ea2fad61...

Hey 👋

A small batch of bug fixes. Please report any issues. 🤞😰🤞

0.29 is getting closer btw. 🌶️

🚀 Features

🐞 Bugfixes

• fix: FilterObject allows any defined value when query context has no tables (TB is never). by @igalklebanov in #1791

📖 Documentation

• add socket security badge. by @igalklebanov in db646ac
• chore: make socket security badge reflect current specific version. by @igalklebanov in 5597144
• support multi-entry point tsdoc without index module. by @igalklebanov in 6998915
• fix broken tsdoc references. by @igalklebanov in 5a0f14b

📦 CICD & Tooling

• chore(pnpm): add strictDepBuilds: true. by @igalklebanov in 2301610
• chore: harden dependencies, pnpm. by @igalklebanov in f4f1d9e
• chore: re-add ignore-workspace-root-check. by @igalklebanov in ab6d00e
• add openssf scorecard. by @igalklebanov in 521156b
• chore: bump dependencies and github actions. by @igalklebanov in #1789
• chore: change verifyDepsBeforeRun to "prompt". by @igalklebanov in 20548bc

⚠️ Breaking Changes

🐤 New Contributors

What's Changed

Full Changelog: v0.28.15...v0.28.16

Hey 👋

The introduction of dehydration in JSON functions/helpers caused an unexpected bug for consumers that have some columns defined as '${number}', e.g. '1' | '2' (also when wrapped in ColumnType or similar). Such columns, when participating in a JSON function/helper would dehydrate to number instead of staying as string.

Why dehydrate numeric strings to numbers in the first place? Select types in kysely describe the data after underlying driver's (e.g. pg) data transformation. Some drivers transform numeric columns to strings to be safe. When these columns participate in JSON functions, they lose original column data types - drivers don't know they need to transform to string - they return as-is.

This release introduces a special helper type that wraps your column type definition and tells kysely to NOT dehydrate it in JSON functions/helpers.

import type { NonDehydrateable } from 'kysely'

interface Database {
  my_table: {
    a_column: '1' | '2' | '3', // dehydrates to `number`
    another_column: NonDehydrateable<'1' | '2' | '3'>, // stays `'1' | '2' | '3'`
    column_too: NonDehydrateable<ColumnType<'1' | '2' | '3'>> // stays `'1' | '2' | '3'`
  }
}

🚀 Features

• feat: add NonDehydrateable<T> to allow opt-out from dehydration in JSON functions/helpers. by @igalklebanov in #1697

🐞 Bugfixes

PostgreSQL 🐘

• fix: PostgreSQL introspector unnecessarily slow in result processing. by @igalklebanov & @rubenferreira97 in #1774

📖 Documentation

• Add complex function helpers section to documentation by @mifi & @igalklebanov in #1758

📦 CICD & Tooling

• chore: bump TypeScript to 6. by @igalklebanov in #1769
• chore: bump dependencies. by @igalklebanov in #1775

⚠️ Breaking Changes

🐤 New Contributors

• @rubenferreira97 made their first contribution in #1774

Full Changelog: v0.28.14...v0.28.15

Hey 👋

A small batch of bug fixes. Please report any issues. 🤞😰🤞

🚀 Features

🐞 Bugfixes

MySQL 🐬

• fix: string literals are injectable on MySQL when backslash escapes (\\') are used. by @igalklebanov in #1754 & 054e801

📖 Documentation

• Add Node SQLite link to dialects documentation by @wolfie in #1709 & #1755
• docs: document immediate value behavior in case() then/else by @alexchenai in #1753

📦 CICD & Tooling

• bump deno kysely dependency. by @igalklebanov in 9e02f3b

⚠️ Breaking Changes

🐤 New Contributors

• @wolfie made their first contribution in #1709
• @alexchenai made their first contribution in #1753

Full Changelog: v0.28.13...v0.28.14

Hey 👋

A small batch of bug fixes. Please report any issues. 🤞😰🤞

🚀 Features

🐞 Bugfixes

• fix: missing sideEffects: false in root package.json resulting in bigger bundles in various bundlers. by @igalklebanov in #1746
• fix: Insertable allows non-objects when a table has no required columns. by @igalklebanov in #1747

PostgreSQL 🐘

• fix: ON COMMIT clause not being output when using .as(query) in CREATE TABLE queries. by @igalklebanov in #1748

📖 Documentation

📦 CICD & Tooling

• chore: fix node tests tsconfig.json for TypeScript native. by @igalklebanov in #1749
• chore: bump dependencies. by @igalklebanov in #1750
• chore: bump GitHub actions. by @igalklebanov in #1751

⚠️ Breaking Changes

🐤 New Contributors

Full Changelog: v0.28.12...v0.28.13

Hey 👋

A small batch of bug fixes. Please report any issues. 🤞😰🤞

🚀 Features

🐞 Bugfixes

• fix: eb.ref(col, '->$').key(key) is injectable. by @igalklebanov in #1727

MySQL 🐬

• feat(mysql): Update types for mysql2@v3.18.2 support #1722 by @fenichelar in #1729

📖 Documentation

📦 CICD & Tooling

• chore: bump dependencies. by @igalklebanov in #1732
• chore: bump dependencies. by @igalklebanov in #1742

⚠️ Breaking Changes

🐤 New Contributors

• @fenichelar made their first contribution in #1729

Full Changelog: v0.28.11...v0.28.12

Hey 👋

A small batch of bug fixes. Please report any issues. 🤞😰🤞

🚀 Features

🐞 Bugfixes

• Prevent re-use of finished trx outside callback by @jacobpgn in #1694

SQLite 📘

• returning needs to come before order by in sqlite for an update..where query. by @hwisu in #1691

📖 Documentation

• Add MariaDB Dialect by @AwaludinAR in #1646

📦 CICD & Tooling

• test: add runtime json dehydration tests. by @igalklebanov in #1688
• chore: bump dependencies. by @igalklebanov in #1693

⚠️ Breaking Changes

🐤 New Contributors

• @hwisu made their first contribution in #1691
• @AwaludinAR made their first contribution in #1646

Full Changelog: v0.28.10...v0.28.11

Hey 👋

A small batch of bug fixes. Please report any issues. 🤞😰🤞

🚀 Features

🐞 Bugfixes

• Add ExtractColumnType and DrainOuterGeneric type exports by @mifi in #1679
• fix: $narrowType compilation errors when composite: true. by @igalklebanov in #1681
• fix: executeTakeFirst compilation error when composite. by @igalklebanov in #1683
• fix: with/withRecursive compilation errors when composite. by @igalklebanov in #1684

PostgreSQL 🐘 / MSSQL 🥅

• fix: Migrator attempts to create custom migration schema even if it exists and fails on dialects that don't support if not exists. by @austin-hall-skylight in #1608

PostgreSQL 🐘 / SQLite 📘

• fix: returning compilation errors when composite. by @igalklebanov in #1682

📖 Documentation

📦 CICD & Tooling

• chore: bump pnpm to 10.26.1, use allowBuilds and blockExoticSubdeps. by @igalklebanov in #1663
• chore: bump dependencies. by @igalklebanov in #1685

⚠️ Breaking Changes

🐤 New Contributors

• @austin-hall-skylight made their first contribution in #1608
• @mifi made their first contribution in #1679

Full Changelog: v0.28.9...v0.28.10

Hey 👋

A small batch of bug fixes. Please report any issues. 🤞😰🤞

🚀 Features

🐞 Bugfixes

PostgreSQL 🐘

• fix: withSchema not applying for delete query using clause. by @igalklebanov in #1648
• fix: withSchema adds schema to for update|share|key share|no key share of tables causing database errors. by @igalklebanov in #1659

📖 Documentation

📦 CICD & Tooling

• publish to jsr. by @igalklebanov in #1457
• chore: bump pnpm, use trustPolicy, exclude safe downgrades, fix browser test, fix bun tests. by @igalklebanov in #1641
• chore(ci): add deno lint with JSR rules. Add verbatimModuleSyntax in tsconfig.json. Apply lint fixes. by @igalklebanov in #1642
• chore: bump dependencies, run prettier. by @igalklebanov in #1644
• chore: bump github actions. by @igalklebanov in #1645
• fix TypeScript native type errors in test-setup.ts. by @igalklebanov in #1660

⚠️ Breaking Changes

🐤 New Contributors

Full Changelog: v0.28.8...v0.28.9

Hey 👋

A small batch of bug fixes. Please report any issues. 🤞😰🤞

🚀 Features

🐞 Bugfixes

PostgreSQL 🐘

• fix: filter schemas the current user does not have access to in postres introspector by @chanon in #1550
• fix: insert/update not being wrapped in parens when in CTE of a merge query. by @igalklebanov & @msifd in #1611

📖 Documentation

• chore: add SECURITY.md. by @igalklebanov in #1590
• fix: correct JSDoc type references in migration docs by @iyoshi-rgb in #1536

📦 CICD & Tooling

• chore(ci): add dependency provenance check, bump deps to force check. by @igalklebanov in #1589
• chore: bumps dependencies. by @igalklebanov in #1600
• chore: bump deps. by @igalklebanov in #1612

⚠️ Breaking Changes

🐤 New Contributors

• @chanon made their first contribution in #1550
• @iyoshi-rgb made their first contribution in #1536
• @msifd made their first contribution in #1611

Full Changelog: v0.28.7...v0.28.8