Skip to content

Releases

0.29.9

Choose a tag to compare

@igalklebanov igalklebanov released this 12 Nov 16:48
Immutable release. Only release title and notes can be modified.
51221fb

Hey 👋

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

Kysely's migrator no longer records timestamps that go backwards when the wall clock jumps back during a migration run (WSL2/VM time sync, an NTP step, an unsmeared leap second). Such timestamps made every later migrateToLatest() fail with "corrupted migrations", even though the migrations ran in the correct order. The migrator now reads the latest recorded timestamp while holding the migration lock, and records each new migration at max(now, latest + 1ms), so the order holds across runs and hosts. Executed migrations with an invalid timestamp now fail with "corrupted migrations" instead of being sorted arbitrarily.

Migration tables that already have out-of-order timestamps need a one-time repair. Run the query for your dialect below. It goes through executed migrations in name order, which is the order the migrator runs them in by default, and moves every timestamp that isn't later than the previous one to 1 millisecond after it. Running it again changes nothing.

Replace kysely_migration with your migration table's name, prefixed with the schema if you set migrationTableSchema. Run it while no migrations are running. Skip this if you use allowUnorderedMigrations: true. Name order isn't the execution order in that mode, and out-of-order timestamps don't block migrations there.

PostgreSQL and PGlite:

with ordered as (
  select
    name,
    (extract(epoch from "timestamp"::timestamptz) * 1000)::bigint as executed_at,
    row_number() over (order by name collate "C") as position
  from kysely_migration
),
repaired as (
  select
    name,
    executed_at,
    position + max(executed_at - position) over (order by position) as repaired_executed_at
  from ordered
)
update kysely_migration
set "timestamp" = to_char(
  (timestamptz 'epoch' + repaired_executed_at * interval '1 millisecond') at time zone 'UTC',
  'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'
)
from repaired
where kysely_migration.name = repaired.name
  and repaired.repaired_executed_at <> repaired.executed_at;

MySQL 8.0+:

update kysely_migration
join (
  select
    name,
    executed_at,
    position + max(executed_at - position) over (order by position) as repaired_executed_at
  from (
    select
      name,
      timestampdiff(
        microsecond,
        '1970-01-01',
        str_to_date(`timestamp`, '%Y-%m-%dT%H:%i:%s.%fZ')
      ) div 1000 as executed_at,
      row_number() over (order by cast(name as binary)) as position
    from kysely_migration
  ) as ordered
) as repaired using (name)
set kysely_migration.`timestamp` = concat(
  date_format(
    timestamp '1970-01-01 00:00:00' + interval repaired.repaired_executed_at * 1000 microsecond,
    '%Y-%m-%dT%H:%i:%s.'
  ),
  lpad(repaired.repaired_executed_at mod 1000, 3, '0'),
  'Z'
)
where repaired.repaired_executed_at <> repaired.executed_at;

MS SQL Server 2016+:

with ordered as (
  select
    name,
    datediff_big(millisecond, '1970-01-01', convert(datetime2(3), [timestamp], 127)) as executed_at,
    row_number() over (order by name collate Latin1_General_BIN2) as position
  from kysely_migration
),
repaired as (
  select
    name,
    executed_at,
    position + max(executed_at - position) over (order by position rows unbounded preceding) as repaired_executed_at
  from ordered
)
update kysely_migration
set [timestamp] = convert(
    varchar(19),
    dateadd(
      millisecond,
      repaired.repaired_executed_at % 86400000,
      dateadd(day, repaired.repaired_executed_at / 86400000, cast('1970-01-01' as datetime2(3)))
    ),
    126
  ) + '.' + right('00' + cast(repaired.repaired_executed_at % 1000 as varchar(3)), 3) + 'Z'
from kysely_migration
join repaired on repaired.name = kysely_migration.name
where repaired.repaired_executed_at <> repaired.executed_at;

SQLite 3.33+:

with ordered as (
  select
    name,
    cast(round((julianday("timestamp") - 2440587.5) * 86400000) as integer) as executed_at,
    row_number() over (order by name collate binary) as position
  from kysely_migration
),
repaired as (
  select
    name,
    executed_at,
    position + max(executed_at - position) over (order by position) as repaired_executed_at
  from ordered
)
update kysely_migration
set "timestamp" = strftime('%Y-%m-%dT%H:%M:%S', repaired_executed_at / 1000, 'unixepoch')
  || printf('.%03dZ', repaired_executed_at % 1000)
from repaired
where kysely_migration.name = repaired.name
  and repaired.repaired_executed_at <> repaired.executed_at;

The binary collations (collate "C", cast(name as binary), etc.) make the database sort names the same way the migrator does in JavaScript.

Also, PGlite 0.5.15+ commits that roll back aborted transactions now throw AbortedTransactionError, same as PostgreSQL since 0.29.8.

🚀 Features

🐞 Bugfixes

  • fix: inline key()/at() JSON path references infer unknown in jsonBuildObject. by @igalklebanov in #2228
  • fix: migration timestamps go backwards when the clock jumps back. by @igalklebanov in #2248

PostgreSQL 🐘 / PGlite 🟨

  • fix: withSchema crashes on for ... of and json_agg/to_json tables in subqueries. by @igalklebanov in #2227

PGlite 🟨

  • fix(pglite): reject commits that roll back aborted transactions by @igalklebanov in #2217

📖 Documentation

📦 CICD & Tooling

⚠️ Breaking Changes

  • key() and at() no longer accept a 2nd type argument for the output type (e.g. .key<'url', number>('url')). It was never documented. Use $castTo<T>() to override the output type. (#2228)

🐤 New Contributors

What's Changed

Full Changelog: v0.29.8...v0.29.9

0.28.20

Choose a tag to compare

@igalklebanov igalklebanov released this 12 Nov 17:44
Immutable release. Only release title and notes can be modified.
v0.28.20
7c42987

Hey 👋

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

This maintenance release backports the fixes from 0.29.9.

Kysely's migrator no longer records timestamps that go backwards when the wall clock jumps back during a migration run (WSL2/VM time sync, an NTP step, an unsmeared leap second). Such timestamps made every later migrateToLatest() fail with "corrupted migrations", even though the migrations ran in the correct order. The migrator now reads the latest recorded timestamp while holding the migration lock, and records each new migration at max(now, latest + 1ms), so the order holds across runs and hosts. Executed migrations with an invalid timestamp now fail with "corrupted migrations" instead of being sorted arbitrarily.

Migration tables that already have out-of-order timestamps need a one-time repair. Run the query for your dialect below. It goes through executed migrations in name order, which is the order the migrator runs them in by default, and moves every timestamp that isn't later than the previous one to 1 millisecond after it. Running it again changes nothing.

Replace kysely_migration with your migration table's name, prefixed with the schema if you set migrationTableSchema. Run it while no migrations are running. Skip this if you use allowUnorderedMigrations: true. Name order isn't the execution order in that mode, and out-of-order timestamps don't block migrations there.

PostgreSQL:

with ordered as (
  select
    name,
    (extract(epoch from "timestamp"::timestamptz) * 1000)::bigint as executed_at,
    row_number() over (order by name collate "C") as position
  from kysely_migration
),
repaired as (
  select
    name,
    executed_at,
    position + max(executed_at - position) over (order by position) as repaired_executed_at
  from ordered
)
update kysely_migration
set "timestamp" = to_char(
  (timestamptz 'epoch' + repaired_executed_at * interval '1 millisecond') at time zone 'UTC',
  'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'
)
from repaired
where kysely_migration.name = repaired.name
  and repaired.repaired_executed_at <> repaired.executed_at;

MySQL 8.0+:

update kysely_migration
join (
  select
    name,
    executed_at,
    position + max(executed_at - position) over (order by position) as repaired_executed_at
  from (
    select
      name,
      timestampdiff(
        microsecond,
        '1970-01-01',
        str_to_date(`timestamp`, '%Y-%m-%dT%H:%i:%s.%fZ')
      ) div 1000 as executed_at,
      row_number() over (order by cast(name as binary)) as position
    from kysely_migration
  ) as ordered
) as repaired using (name)
set kysely_migration.`timestamp` = concat(
  date_format(
    timestamp '1970-01-01 00:00:00' + interval repaired.repaired_executed_at * 1000 microsecond,
    '%Y-%m-%dT%H:%i:%s.'
  ),
  lpad(repaired.repaired_executed_at mod 1000, 3, '0'),
  'Z'
)
where repaired.repaired_executed_at <> repaired.executed_at;

MS SQL Server 2016+:

with ordered as (
  select
    name,
    datediff_big(millisecond, '1970-01-01', convert(datetime2(3), [timestamp], 127)) as executed_at,
    row_number() over (order by name collate Latin1_General_BIN2) as position
  from kysely_migration
),
repaired as (
  select
    name,
    executed_at,
    position + max(executed_at - position) over (order by position rows unbounded preceding) as repaired_executed_at
  from ordered
)
update kysely_migration
set [timestamp] = convert(
    varchar(19),
    dateadd(
      millisecond,
      repaired.repaired_executed_at % 86400000,
      dateadd(day, repaired.repaired_executed_at / 86400000, cast('1970-01-01' as datetime2(3)))
    ),
    126
  ) + '.' + right('00' + cast(repaired.repaired_executed_at % 1000 as varchar(3)), 3) + 'Z'
from kysely_migration
join repaired on repaired.name = kysely_migration.name
where repaired.repaired_executed_at <> repaired.executed_at;

SQLite 3.33+:

with ordered as (
  select
    name,
    cast(round((julianday("timestamp") - 2440587.5) * 86400000) as integer) as executed_at,
    row_number() over (order by name collate binary) as position
  from kysely_migration
),
repaired as (
  select
    name,
    executed_at,
    position + max(executed_at - position) over (order by position) as repaired_executed_at
  from ordered
)
update kysely_migration
set "timestamp" = strftime('%Y-%m-%dT%H:%M:%S', repaired_executed_at / 1000, 'unixepoch')
  || printf('.%03dZ', repaired_executed_at % 1000)
from repaired
where kysely_migration.name = repaired.name
  and repaired.repaired_executed_at <> repaired.executed_at;

The binary collations (collate "C", cast(name as binary), etc.) make the database sort names the same way the migrator does in JavaScript.

🚀 Features

🐞 Bugfixes

  • fix: inline key()/at() JSON path references infer unknown in jsonBuildObject. by @igalklebanov in #2228
  • fix: migration timestamps go backwards when the clock jumps back. by @igalklebanov in #2248

PostgreSQL 🐘

  • fix: withSchema crashes on for ... of and json_agg/to_json tables in subqueries. by @igalklebanov in #2227

📖 Documentation

📦 CICD & Tooling

⚠️ Breaking Changes

  • key() and at() no longer accept a 2nd type argument for the output type (e.g. .key<'url', number>('url')). It was never documented. Use $castTo<T>() to override the output type. (#2228)

🐤 New Contributors

What's Changed

Full Changelog: v0.28.19...v0.28.20

0.29.8

Choose a tag to compare

@igalklebanov igalklebanov released this 01 Nov 02:07
Immutable release. Only release title and notes can be modified.
fe483ef

Hey 👋

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

PostgreSQL transactions get two fixes:

  • Clients whose rollback fails are discarded instead of returned to the pool for reuse.
  • Commits that PostgreSQL turns into rollbacks now throw AbortedTransactionError instead of reporting success. Controlled transactions are marked as rolled back and release their connection; a subsequent rollback().execute() safely succeeds without sending another rollback.

🚀 Features

🐞 Bugfixes

PostgreSQL 🐘

📖 Documentation

📦 CICD & Tooling

⚠️ Breaking Changes

🐤 New Contributors

What's Changed

Full Changelog: v0.29.7...v0.29.8

0.28.19

Choose a tag to compare

@igalklebanov igalklebanov released this 01 Nov 02:24
Immutable release. Only release title and notes can be modified.
a33379c

Hey 👋

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

This maintenance release backports the PostgreSQL transaction fixes from 0.29.8.

PostgreSQL transactions get two fixes:

  • Clients whose rollback fails are discarded instead of returned to the pool for reuse.
  • Commits that PostgreSQL turns into rollbacks now throw AbortedTransactionError instead of reporting success. Controlled transactions are marked as rolled back and release their connection; a subsequent rollback().execute() safely succeeds without sending another rollback.

🚀 Features

🐞 Bugfixes

PostgreSQL 🐘

📖 Documentation

📦 CICD & Tooling

⚠️ Breaking Changes

🐤 New Contributors

What's Changed

Full Changelog: v0.28.18...v0.28.19

0.29.7

Choose a tag to compare

@igalklebanov igalklebanov released this 17 Oct 15:52
Immutable release. Only release title and notes can be modified.
ac876c2

Hey 👋

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

Controlled transactions get fixes for connection leaks, shared completion state, and commands racing with ongoing queries:

  • Commit, rollback, and savepoint commands now wait for ongoing queries and streams to finish.
  • Close or exhaust active streams before awaiting these commands.
  • A failed rollback now releases the connection and marks the transaction as rolled back.

🚀 Features

🐞 Bugfixes

  • fix: release controlled transaction connection when begin fails by @igalklebanov in #2080
  • fix: share completion state between controlled transaction handles by @igalklebanov in #2090
  • fix: release controlled transaction connection when rollback fails by @B4nan in #2136
  • fix: serialize controlled transaction commands with queries by @igalklebanov in #2081

PostgreSQL 🐘

MSSQL 🥅

📖 Documentation

📦 CICD & Tooling

⚠️ Breaking Changes

🐤 New Contributors

What's Changed

Full Changelog: v0.29.6...v0.29.7

0.28.18

Choose a tag to compare

@igalklebanov igalklebanov released this 17 Oct 19:28
Immutable release. Only release title and notes can be modified.
v0.28.18
2ead574

Hey 👋

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

This maintenance release backports bug fixes and documentation improvements from the 0.29 line.

Controlled transactions get fixes for connection leaks, shared completion state, and commands racing with ongoing queries:

  • Commit, rollback, and savepoint commands now wait for ongoing queries and streams to finish.
  • Close or exhaust active streams before awaiting these commands.
  • A failed rollback now releases the connection and marks the transaction as rolled back.

PostgreSQL and MSSQL now use session-level migration locks, including with disableTransactions: true. PostgreSQL migrations through PgBouncer transaction pooling need a direct connection, session pooling, or custom migration locking.

🚀 Features

🐞 Bugfixes

  • fix: allow explicit undefined in Updateable with exactOptionalPropertyTypes. by @y-hsgw in #1496
  • fix infinite type check recursion by @koskimas in #1960
  • fix: release controlled transaction connection when begin fails by @igalklebanov in #2080
  • fix: share completion state between controlled transaction handles by @igalklebanov in #2090
  • fix: release controlled transaction connection when rollback fails by @B4nan in #2136
  • fix: serialize controlled transaction commands with queries by @igalklebanov in #2081

PostgreSQL 🐘 / MSSQL 🥅

PostgreSQL 🐘 / SQLite 📘

On-conflict WHERE predicates now use column select types, including for columns that cannot be updated.

PostgreSQL 🐘

SQLite 📘

  • fix(sqlite): output RETURNING before ORDER BY and LIMIT in delete queries. by @igalklebanov in #1946

MSSQL 🥅

📖 Documentation

📦 CICD & Tooling

⚠️ Breaking Changes

PostgreSQL 🐘

  • PostgreSQL migrations now use session-level advisory locks, including when transactions are enabled. This is incompatible with PgBouncer transaction pooling and other transaction-mode connection poolers. Run migrations through a direct connection, session pooling, or custom migration locking. Otherwise, migration locks can remain held on pooled connections and block subsequent migration runs. See #1919 and #2200.

🐤 New Contributors

What's Changed

Full Changelog: v0.28.17...v0.28.18

0.29.6

Choose a tag to compare

@igalklebanov igalklebanov released this 16 Sep 01:06
Immutable release. Only release title and notes can be modified.
2fefd4c

Hey 👋

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

🚀 Features

🐞 Bugfixes

PostgreSQL 🐘 / SQLite 📘

📖 Documentation

  • feat(site): grow the proof wall from npm's dependents (Cypress, Canton, Tailor, Supabase Lite) + verify every pin by @igalklebanov in #1985
  • Update link to Migrator API docs by @ardouglass in #1991

📦 CICD & Tooling

⚠️ Breaking Changes

🐤 New Contributors

What's Changed

Full Changelog: v0.29.5...v0.29.6

0.30.0-beta.2

0.30.0-beta.2 Pre-release
Pre-release

Choose a tag to compare

@igalklebanov igalklebanov released this 14 Sep 01:34
Immutable release. Only release title and notes can be modified.
4f5fc83

Hey 👋

0.30 season is upon us. pnpm i kysely@next and get a sneak peak into the future!

We've got a new transactionMode: 'per-run' | 'per-migration' | 'none' property you can pass to Migrator or it's methods.

  • 'per-run' is the classic behavior you're used to where kysely wrap the entire run in a transaction when your dialect supports transactional DDL.
  • 'per-migration' enables each migration to pick whether it runs in its own transaction or not. Just expose config: { transaction: false } from the module, right next to the up/down functions.
  • 'none' means no transactions are used, which is similar to the now deprecated disableTransactions: true.
import * as fs from 'node:fs/promises'
import * as path from 'node:path'
import { FileMigrationProvider, Migrator } from 'kysely/migration'

const migrator = new Migrator({
  db,
  provider: new FileMigrationProvider({
    fs,
    migrationFolder: path.join(import.meta.dirname, 'migrations'),
  }),
  transactionMode: 'per-migration', // <-------------------------------
})

await migrator.migrateToLatest()

We've got a new defineMigration helper function that you can use to easily write your migrations and meet the contract requirements:

import { defineMigration } from 'kysely/migration'

export default defineMigration({
  up: async (db) => {
    // ...
  },

  config: { transaction: false }, // <--------------------
})

You can now use mysql2/promise, where in the past it would hang forever since we only supported the callback style of mysql2 root import.

We're trying various type-level solutions that provide compilation performance and type-safety improvements of Kysely, Transaction, ControlledTransaction and their readonly variants. QueryCreator, FunctionModule, MergeQueryBuilder too.

We've got a new stream method on RawBuilder that allows you to:

import { sql } from 'kysely'
import { db } from 'path/to/db'

for await (const row of sql`select * from person`.stream(db)) {
  // ...
}

🚀 Features

PostgreSQL 🐘 / MSSQL 🥅

PostgreSQL 🐘

MySQL 🐬

  • feat(mysql): support both mysql2 and mysql2/promise in MysqlDialect. by @igalklebanov in #1958
  • feat(mysql): add withNonDefaultDatabases to support introspection of non-default databases. by @igalklebanov in #2007

SQLite 📘

🐞 Bugfixes

📖 Documentation

📦 CICD & Tooling

⚠️ Breaking Changes

  • disableTransactions is deprecated. Use the new transactionMode: 'none', or transactionMode: 'per-migration' with combination of config: { transaction: false }.
  • MySQL introspection now always excludes system databases - mysql, information_schema, performance_schema, sys and nbinfo tables will not be returned.
  • You might start seeing invocations of some your custom helpers failing compilation now that Kysely, Transaction, ControlledTransaction and their readonly variants are compared more tightly. QueryCreator, FunctionModule, MergeQueryBuilder too. Please report these cases.

SQLite 📘

  • Trying to pass records with BLOB columns in JSON helpers emits compile-time errors - e.g.
     KyselyTypeError<'SQLite does not support passing `BLOB` values to `json_object`. Cast to `TEXT`.'>

🐤 New Contributors

What's Changed

Full Changelog: v0.29.5...v0.30.0-beta.2

0.29.5

Choose a tag to compare

@igalklebanov igalklebanov released this 10 Aug 01:06
Immutable release. Only release title and notes can be modified.
f24018c

Hey 👋

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

TypeScript 7 is allowing for deeper computations which now cause way more instantiations and wall clock times in various scenarios. We're diving deep into our types and finding optimizations. In this version @koskimas brought some nice wins for builder vs. builder assignability checks.

We're also revamping the docs site, working on style, message and usefulness. Swing by our Discord and share your opinions/ideas. We got docs->apidocs search now. The playground is back supporting short links and will allow saving short links very soon.

🚀 Features

🐞 Bugfixes

  • fix infinite type check recursion by @koskimas in #1960
  • Add missing beforeThrow calls in getInflightQueryAbortHandler by @lourd in #1971

📖 Documentation

  • Fix typo in CreateTypeBuilder.asEnum docstring by @anonpay-sh in #1949
  • chore: revamp docs hero page. by @igalklebanov in #1959
  • fix(site): various issues with stats section. by @igalklebanov in #1966
  • chore(site): replace most text proof with logos. by @igalklebanov in #1968
  • feat(site): migrate to pagefind for cross-site search we own. by @igalklebanov in #1972
  • chore(site): drop self-narrating captions, make proof arrows a standing cue by @igalklebanov in #1973
  • feat(site): grow the proof wall (Replicas, EmbedPDF) + fix production hover by @igalklebanov in #1974
  • feat(site): add AirTrail, bknd, Civitai, Corsair.dev, Hot Updater, Profilarr and Tunarr to the proof wall. by @igalklebanov in #1975
  • feat(site): proof-strength gauges, query-module evidence, and new wall names by @igalklebanov in #1976
  • feat(site): explain the proof gauge behind a (?) on the production wall by @igalklebanov in #1977
  • feat(site): align docs code blocks with the landing page's VS Code themes by @igalklebanov in #1978

📦 CICD & Tooling

⚠️ Breaking Changes

🐤 New Contributors

What's Changed

Full Changelog: v0.29.4...v0.29.5

0.30.0-beta.1

0.30.0-beta.1 Pre-release
Pre-release

Choose a tag to compare

@igalklebanov igalklebanov released this 26 Jul 17:34
Immutable release. Only release title and notes can be modified.
979db93

Hey 👋

0.30 season is upon us. pnpm i kysely@next and get a sneak peak into the future!

We've got a new transactionMode: 'per-run' | 'per-migration' | 'none' property you can pass to Migrator or it's methods.

  • 'per-run' is the classic behavior you're used to where kysely wrap the entire run in a transaction when your dialect supports transactional DDL.
  • 'per-migration' enables each migration to pick whether it runs in its own transaction or not. Just expose config: { transaction: false } from the module, right next to the up/down functions.
  • 'none' means no transactions are used, which is similar to the now deprecated disableTransactions: true.
import * as fs from 'node:fs/promises'
import * as path from 'node:path'
import { FileMigrationProvider, Migrator } from 'kysely/migration'

const migrator = new Migrator({
  db,
  provider: new FileMigrationProvider({
    fs,
    migrationFolder: path.join(import.meta.dirname, 'migrations'),
  }),
  transactionMode: 'per-migration', // <-------------------------------
})

await migrator.migrateToLatest()

We've got a new defineMigration helper function that you can use to easily write your migrations and meet the contract requirements:

import { defineMigration } from 'kysely/migration'

export default defineMigration({
  up: async (db) => {
    // ...
  },

  config: { transaction: false }, // <--------------------
})

You can now use mysql2/promise, where in the past it would hang forever since we only supported the callback style of mysql2 root import.

🚀 Features

  • feat(migrator): add migrateTo(name, { direction: 'Up' | 'Down' }) to enforce direction. by @igalklebanov in #1957

PostgreSQL 🐘 / MSSQL 🥅

MySQL 🐬

  • feat(mysql): support both mysql2 and mysql2/promise in MysqlDialect. by @igalklebanov in #1958

SQLite 📘

🐞 Bugfixes

📖 Documentation

📦 CICD & Tooling

⚠️ Breaking Changes

  • disableTransactions is deprecated. Use the new transactionMode: 'none', or transactionMode: 'per-migration' with combination of config: { transaction: false }.

SQLite 📘

  • Trying to pass records with BLOB columns in JSON helpers emits compile-time errors - e.g.
     KyselyTypeError<'SQLite does not support passing `BLOB` values to `json_object`. Cast to `TEXT`.'>

🐤 New Contributors

What's Changed

Full Changelog: 4ba0bd4...v0.30.0-beta.1