kysely

• Add allowUnorderedMigrations option for the migrator. #723 Awesome work by @tracehelms ❤️
• Fix update and insert query type issues when using Kysely<any>.
• Improve error messages when passing a wrong column name or wrong type for a column in UpdateQueryBuilder#set and InsertQueryBuilder#values methods.

• Add $notNull type helper
• Support for update of table and friends #683
• Support insert into "person" default values #685
• Support arbitrary expressions in limit and offset
• Support insert, update and delete queries in raw SQL substitutions #680
• Fix node 14 regression #824
• Fix fn.agg regression where two type arguments were required #829

• Add mssql dialect. A huge effort by @igalklebanov ❤️ #595
• Add postgres json_agg and to_json functions to function module
• Add is distinct from operator #673
• Add set('first_name', 'Jennifer') variant for update query's set method #672
• Add as statement support for createTable #771. Thank you @viraxslot ❤️
• Add nulls not distinct option for constraints #770. Thank you @viraxslot ❤️
• Add addIndex & dropIndex @ AlterTableBuilder #720. Thank you @Gaspero
• Add stream() support for sqlite dialect #754. Thank you @tgriesser ❤️
• Fix query and error logging both occur on error. #796. Thank you @igalklebanov ❤️
• Fix type issue with $if #793. Thank you @igalklebanov ❤️
• Fix issue where onConflict..doUpdateSet used select types instead of update types. #792. Thank you @igalklebanov ❤️
• Add eb.jsonPath<$> #791. Thank you @igalklebanov ❤️
• $narrowType supports new type tag NotNull for an easier way to mark columns not nullable manually
• Fix #811
• Support arbitrary expressions in min and max aggregate functions.

Breaking changes

• selectNoFrom is removed from ExpressionBuilder due to severe typescript performance issues. selectNoFrom still exists in the Kysely instance, and in most cases, you can use that instead. See this example on how to migrate: https://kyse.link/?p=s&i=sqAZIvTQktxgXYzHGkqX.
• Types are once again a little bit stricter in some places. You might get type errors from code like where('first_name', '=', sql`something`). You need to explicitly give a type for the sql expressions like this sql<string>`something`
• Deprecated functions eb.cmpr and eb.bxp have been removed. Use eb as a function instead.

• Type performance improvements. We got ~30% speedup in our type test suite. Results will vary.
• Fix autocompletion issues select(eb => [autocompletion works here now]).

• Added support for select statements without a from clause. The function is called selectNoFrom. The function name was selected after a lot of discussion. The most natural name would just be select, but new users would find that in a list of autocompletions before selectFrom and naturally use it when trying to create a select from query. This would be especially true for people coming from knex where a select from query is started using a select call. #605
• Add object variants of and and or functions. Allows easy where(eb => eb.and(object)) filters. #583
• Add support for tuples. See some examples here. #611
• Add addPrimaryKeyConstraint for AlterTableBuilder. #639 Thank you @n7olkachev ❤️
• Add any function to function module. #612
• Add between method to expression builder. #602
• Add lit method to expression builder. #600
• Add multi-column variant of orderBy. #423 Thank you @igalklebanov ❤️

An example of an object and call:

const persons = await db
  .selectFrom('person')
  .selectAll()
  .where((eb) => eb.and({
    first_name: 'Jennifer',
    last_name: eb.ref('first_name')
  }))
  .execute()

select * from "person"
where "first_name" = $1 and "last_name" = "first_name"

Expression builder improvements

We improved the expression builder based on excellent feedback from the community in this issue in addition to many discord discussions. Unfortunately this means deprecating the recently added cmpr and bxp methods, but the migration should be painless. Read more @ #565.

Before you could create comparisons and arbitrary binary expressions using cmpr and bxp respectively:

where((eb) => eb.or([
  eb.cmpr('first_name', '=', 'Jennifer'),
  eb.cmpr('first_name', '=', 'Sylvester'),
]))

set((eb) => ({
  age: eb.bxp('age', '+', 1)
}))

After this release, you'd do this instead:

where((eb) => eb.or([
  eb('first_name', '=', 'Jennifer'),
  eb('first_name', '=', 'Sylvester'),
]))

set((eb) => ({
  age: eb('age', '+', 1)
}))

As you can see we made the expression builder callable and it can create all kinds of binary expressions. You can still use destructuring as before since the expression builder has a new property eb that returns itself:

where(({ eb, or }) => or([
  eb('first_name', '=', 'Jennifer'),
  eb('first_name', '=', 'Sylvester'),
]))

or and and chaining

We've also added new way to create and and or expressions using chaining

where((eb) => 
  eb('first_name', '=', 'Jennifer').or('first_name', '=', 'Sylvester')
]))

The old and and or methods are still there and are not going anywhere.

JSON references

The expression builder's ref function can now be used to reference nested JSON columns' fields and array items in a type-safe way:

// Postgres syntax: "addresses"->0->'postalCode'
where(({ eb, ref }) =>
  eb(ref('addresses', '->').at(0).key('postalCode'), '=', '61710')
)

// MySQL syntax: `addresses`->'$[0].postalCode'
where(({ eb, ref }) =>
  eb(ref('addresses', '->$').at(0).key('postalCode'), '=', '61710')
)

The JSON reference builder is just our first guess of a good API. We're eager to hear your feedback. More examples and a recipe on the subject will follow shortly after this release. Read more @ #440.

Other changes

• fix onConflict compilation errors starting from TypeScript 5.1.6 #568. Thanks @igalklebanov ❤️
• Add UpdateResult.numChangedRows. #431 Thanks @wirekang ❤️
• Disallow AlterColumn method chaining. #468 Thanks @soanvig ❤️
• Allow arbitrary expressions in count and sum
• Allow parameters in raw sql. #512 Thanks @nicksrandall ❤️

Large amount of contributions from many awesome people in this one, but one definitely stands out:

Using his sorcerous knowledge of the typescript compiler internals @schusovskoy was able to significantly reduce the possibility of the notorious Type instantiation is excessively deep and possibly infinite compiler error throughout Kysely. Check out the PR here #483 🧙. In our typing tests, we were able to at least double the complexity of the troublesome queries without hitting slowdowns or compiler errors. In some cases the issue seems to have gone away completely.

Simply amazing work. Thank you so much @schusovskoy ❤️

Other fixes and improvements in no particular order:

• Add new case when then end builder #404. Thanks @igalklebanov ❤️
• Allow specifying column sort order when creating indexes #375. Thanks @igalklebanov ❤️
• Add $narrowType helper for narrowing the query output type #380. Thanks @igalklebanov ❤️
• Make subquery selections nullable by default #420
• Fix alter table schema handling #471. Thanks @hannesj ❤️
• Add agg method to expression builder for arbitrary aggregate function calls #417 @igalklebanov ❤️
• The $if method should no longer cause performance issues or excessively deep types
• Make logger support async calls #425. Thanks @mehulmpt ❤️

In addition to this there were small fixes from multiple awesome people including:

• #499 #463 by @neographer
• #444 by @rafaumlemos
• #478 by @thdxr
• Work on kysely.dev by @wirekang and @naorpeled

• Add mysql helper module with jsonArrayFrom and jsonObjectFrom functions. See this recipe for more info.

So much new stuff and big improvements, I don't know where to start! 🎉. There should be no breaking changes, but with this amount of changes and new features, it's always possible we've broken something 😬. As always, please open an issue if something is broken.

Let's start with the reason some of you are here: the deprecated filter methods and the improved ExpressionBuilder:

The improved ExpressionBuilder

We've deprecated most of the where, having, on and other filter methods like whereExists, whereNotExists, orWhere, orWhereExists in favour of the new expression builder. To get an idea what the expression builder is and what it can do, you should take a look at this recipe. Here are some of the most common migrations you should do:

// Old
where(eb => eb
  .where('first_name', '=', 'Jennifer')
  .orWhere('last_name', '=', 'Aniston')
)

// New
where(({ or, cmpr }) => or([
  cmpr('first_name', '=', 'Jennifer'),
  cmpr('last_name', '=', 'Aniston')
]))

// Old
whereNotExists(eb => eb
  .selectFrom('pet')
  .select('pet.id')
  .whereRef('pet.owner_id', '=', 'person.id')
)

// New
where(({ not, exists, selectFrom }) => not(exists(
  selectFrom('pet')
    .select('pet.id')
    .whereRef('pet.owner_id', '=', 'person.id')
)))

You can fine more examples here and here.

The new website 🎉

The first version of kysely.dev is out 🎉 A huge thanks to @fhur for the initiative and for doing allmost all work on that ❤️

Now that the site is out, we'll concentrate on adding more documentation and examples there. For now, it's pretty minimal.

Other changes

• Add compiled query and timings to error logs. Thank you @fwojciec ❤️ #355
• Add returningAll('table') overload for DeleteQueryBuilder. Thank you @anirudh1713 ❤️ #314
• Fix #398. Thank you @igalklebanov ❤️ #399
• Allow streaming of update, insert and delete query results on postgres. Thank you @igalklebanov ❤️ #377
• Add where method toCreateIndexBuilder. Thank you @igalklebanov ❤️ #371
• Added a new module kysely/helpers/postgres for some postgres-spcific higher level helpers. Similar packages will be added for other dialects too in the future. See this recipe for the newly available helpers.
• Simplified types (performance-wise). Small gains here and there.

• Force IDEs to show simple result types on hover

Thank you @steida for pointing me to the Simplify helper.

• Add ifNotExists for CreateIndexBuilder #253
• Add using clause support for DeleteQueryBuilder #241. Thank you @igalklebanov ❤️
• Add match to the list of supported comparison operators #280. Thank you @jonluca ❤️
• Pass options to dialect adapter migration lock methods (not a breaking change).

• Fix regression bug where comparing non-nullable and nullable values weren't allowed by the types in where, having and other comparison methods.

• Add the assertType method for dealing with Type instantiation is excessively deep and possibly infinite errors.
• Add clearSelect, clearWhere etc. methods. Thank you @wirekang ❤️

• Fix #258

So many fixes and features in this one. @igalklebanov has been on fire 🔥. Almost all of these are his awesome work.

• Fix bug that prevented ArrayBuffer usage with CamelCasePlugin #193. Thank you @igalklebanov ❤️
• Add fn.coalesce helper #179. Thank you @igalklebanov ❤️
• Refactor internals to use the new Expression interface
• Allow aggregate functions to return a nullable value #183. Thank you @igalklebanov ❤️
• Fix bug with multiple default values in inserts #202. Thank you @igalklebanov ❤️
• Support the exactOptionalPropertyTypes typescript setting #210. Thank you @igalklebanov ❤️
• Fix migrationKey calculation keeping dot when .mjs #220. Thank you @igalklebanov ❤️
• Allow subqueries and raw sql in distinctOn #239. Thank you @naorpeled ❤️
• Support multiple column operation in alter table query #238. Thank you @naorpeled ❤️
• Add numInsertedOrUpdatedRows to InsertResult #188. Thank you @igalklebanov ❤️
• Fix #235. Thank you @tobiasfoerg ❤️
• Add call method to create/alter table statement builders #242. Thank you @jacobpgn ❤️
• Add filter clause support at AggregateFunctionBuilder #208. Thank you @igalklebanov ❤️

Breaking changes

• The types are now more strict in some places. If you are using raw sql expressions or the RawBuilder class, you may need to specify a type for the expression like this:

sql<string>`something`

• Following the changes in #238, you can alter multiple columns, and the alterations have moved to a callback:

Before:

  await db.schema
    .alterTable('person')
    .alterColumn('first_name')
    .setDataType('text')
    .execute();

After:

await db.schema
  .alterTable('person')
  .alterColumn('first_name', (ac) => ac.setDataType('text'))
  .execute()

• Add better aggregate function builder. Thank you @igalklebanov ❤️
• Add support for intersect and except set operations. Thank you @igalklebanov ❤️

Breaking changes

CreateIndexBuilder used to invalidly add two sets of parentheses in some cases. For example, before you could write a query like this:

db.schema
  .createIndex('idx')
  .on('table')
  .expression('a < 10')

and it worked because Kysely added the needed double parentheses for that particular case. The problem is that not all expressions should have double parentheses and the expression method shouldn't add the second set.

If you've used db.schema.createIndex with a custom expression you may need to add the extra set of parentheses depending on the query (check the database docs). For example in case of our example, you'll need to change it into:

db.schema
  .createIndex('idx')
  .on('table')
  .expression('(a < 10)')

• Start using default instead of null for missing values in multi-row inserts on supported dialects.

• Enable returning for sqlite. Thank you @waynebloss ❤️

• Add cascade method to drop table, drop schema, drop view and drop index builders. Thank you @jaym910 ❤️

• fixes #134