kysely 0.16.9 → 0.17.1

package/dist/esm/query-builder/select-query-builder.js

@@ -21,109 +21,109 @@ export class SelectQueryBuilder {
     where(...args) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseWhereFilter(this.#props.parseContext, args)),
+            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseWhereFilter(args)),
         });
     }
     whereRef(lhs, op, rhs) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseReferenceFilter(this.#props.parseContext, lhs, op, rhs)),
+            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseReferenceFilter(lhs, op, rhs)),
         });
     }
     orWhere(...args) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithOrWhere(this.#props.queryNode, parseWhereFilter(this.#props.parseContext, args)),
+            queryNode: QueryNode.cloneWithOrWhere(this.#props.queryNode, parseWhereFilter(args)),
         });
     }
     orWhereRef(lhs, op, rhs) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithOrWhere(this.#props.queryNode, parseReferenceFilter(this.#props.parseContext, lhs, op, rhs)),
+            queryNode: QueryNode.cloneWithOrWhere(this.#props.queryNode, parseReferenceFilter(lhs, op, rhs)),
         });
     }
     whereExists(arg) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseExistFilter(this.#props.parseContext, arg)),
+            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseExistFilter(arg)),
         });
     }
     whereNotExists(arg) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseNotExistFilter(this.#props.parseContext, arg)),
+            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseNotExistFilter(arg)),
         });
     }
     orWhereExists(arg) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithOrWhere(this.#props.queryNode, parseExistFilter(this.#props.parseContext, arg)),
+            queryNode: QueryNode.cloneWithOrWhere(this.#props.queryNode, parseExistFilter(arg)),
         });
     }
     orWhereNotExists(arg) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithOrWhere(this.#props.queryNode, parseNotExistFilter(this.#props.parseContext, arg)),
+            queryNode: QueryNode.cloneWithOrWhere(this.#props.queryNode, parseNotExistFilter(arg)),
         });
     }
     having(...args) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: SelectQueryNode.cloneWithHaving(this.#props.queryNode, parseHavingFilter(this.#props.parseContext, args)),
+            queryNode: SelectQueryNode.cloneWithHaving(this.#props.queryNode, parseHavingFilter(args)),
         });
     }
     havingRef(lhs, op, rhs) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: SelectQueryNode.cloneWithHaving(this.#props.queryNode, parseReferenceFilter(this.#props.parseContext, lhs, op, rhs)),
+            queryNode: SelectQueryNode.cloneWithHaving(this.#props.queryNode, parseReferenceFilter(lhs, op, rhs)),
         });
     }
     orHaving(...args) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, parseHavingFilter(this.#props.parseContext, args)),
+            queryNode: SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, parseHavingFilter(args)),
         });
     }
     orHavingRef(lhs, op, rhs) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, parseReferenceFilter(this.#props.parseContext, lhs, op, rhs)),
+            queryNode: SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, parseReferenceFilter(lhs, op, rhs)),
         });
     }
     havingExists(arg) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: SelectQueryNode.cloneWithHaving(this.#props.queryNode, parseExistFilter(this.#props.parseContext, arg)),
+            queryNode: SelectQueryNode.cloneWithHaving(this.#props.queryNode, parseExistFilter(arg)),
         });
     }
     havingNotExist(arg) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: SelectQueryNode.cloneWithHaving(this.#props.queryNode, parseNotExistFilter(this.#props.parseContext, arg)),
+            queryNode: SelectQueryNode.cloneWithHaving(this.#props.queryNode, parseNotExistFilter(arg)),
         });
     }
     orHavingExists(arg) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, parseExistFilter(this.#props.parseContext, arg)),
+            queryNode: SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, parseExistFilter(arg)),
         });
     }
     orHavingNotExists(arg) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, parseNotExistFilter(this.#props.parseContext, arg)),
+            queryNode: SelectQueryNode.cloneWithOrHaving(this.#props.queryNode, parseNotExistFilter(arg)),
         });
     }
     select(selection) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: SelectQueryNode.cloneWithSelections(this.#props.queryNode, parseSelectExpressionOrList(this.#props.parseContext, selection)),
+            queryNode: SelectQueryNode.cloneWithSelections(this.#props.queryNode, parseSelectExpressionOrList(selection)),
         });
     }
     distinctOn(selection) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: SelectQueryNode.cloneWithDistinctOnSelections(this.#props.queryNode, parseSelectExpressionOrList(this.#props.parseContext, selection)),
+            queryNode: SelectQueryNode.cloneWithDistinctOnSelections(this.#props.queryNode, parseSelectExpressionOrList(selection)),
         });
     }
     /**
@@ -213,25 +213,25 @@ export class SelectQueryBuilder {
     innerJoin(...args) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithJoin(this.#props.queryNode, parseJoin(this.#props.parseContext, 'InnerJoin', args)),
+            queryNode: QueryNode.cloneWithJoin(this.#props.queryNode, parseJoin('InnerJoin', args)),
         });
     }
     leftJoin(...args) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithJoin(this.#props.queryNode, parseJoin(this.#props.parseContext, 'LeftJoin', args)),
+            queryNode: QueryNode.cloneWithJoin(this.#props.queryNode, parseJoin('LeftJoin', args)),
         });
     }
     rightJoin(...args) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithJoin(this.#props.queryNode, parseJoin(this.#props.parseContext, 'RightJoin', args)),
+            queryNode: QueryNode.cloneWithJoin(this.#props.queryNode, parseJoin('RightJoin', args)),
         });
     }
     fullJoin(...args) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithJoin(this.#props.queryNode, parseJoin(this.#props.parseContext, 'FullJoin', args)),
+            queryNode: QueryNode.cloneWithJoin(this.#props.queryNode, parseJoin('FullJoin', args)),
         });
     }
     /**
@@ -262,10 +262,12 @@ export class SelectQueryBuilder {
      * order by "id" asc, "fn" desc
      * ```
      *
-     * The order by expression can also be a `raw` expression or a subquery
+     * The order by expression can also be a raw sql expression or a subquery
      * in addition to column references:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * await db
      *   .selectFrom('person')
      *   .selectAll()
@@ -275,7 +277,7 @@ export class SelectQueryBuilder {
      *     .limit(1)
      *   )
      *   .orderBy(
-     *     db.raw('concat(first_name, last_name)')
+     *     sql`concat(first_name, last_name)`
      *   )
      *   .execute()
      * ```
@@ -322,13 +324,13 @@ export class SelectQueryBuilder {
     orderBy(orderBy, direction) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: SelectQueryNode.cloneWithOrderByItem(this.#props.queryNode, parseOrderBy(this.#props.parseContext, orderBy, direction)),
+            queryNode: SelectQueryNode.cloneWithOrderByItem(this.#props.queryNode, parseOrderBy(orderBy, direction)),
         });
     }
     groupBy(groupBy) {
         return new SelectQueryBuilder({
             ...this.#props,
-            queryNode: SelectQueryNode.cloneWithGroupByItems(this.#props.queryNode, parseGroupBy(this.#props.parseContext, groupBy)),
+            queryNode: SelectQueryNode.cloneWithGroupByItems(this.#props.queryNode, parseGroupBy(groupBy)),
         });
     }
     /**

package/dist/esm/query-builder/update-query-builder.d.ts

@@ -12,7 +12,6 @@ import { MutationObject } from '../parser/update-set-parser.js';
 import { Compilable } from '../util/compilable.js';
 import { QueryExecutor } from '../query-executor/query-executor.js';
 import { QueryId } from '../util/query-id.js';
-import { ParseContext } from '../parser/parse-context.js';
 import { UpdateResult } from './update-result.js';
 import { KyselyPlugin } from '../plugin/kysely-plugin.js';
 import { WhereInterface } from './where-interface.js';
@@ -47,7 +46,7 @@ export declare class UpdateQueryBuilder<DB, TB extends keyof DB, O> implements W
      * ```
      *
      * Operator can be any supported operator or if the typings don't support it
-     * you can always use `db.raw('your operator')`.
+     * you can always use `sql\`your operator\``.
      *
      * ```ts
      * const persons = await db
@@ -117,7 +116,7 @@ export declare class UpdateQueryBuilder<DB, TB extends keyof DB, O> implements W
      *
      * A `where in` query can be built by using the `in` operator and an array
      * of values. The values in the array can also be subqueries or raw
-     * instances.
+     * {@link sql} expressions.
      *
      * ```ts
      * const persons = await db
@@ -133,15 +132,17 @@ export declare class UpdateQueryBuilder<DB, TB extends keyof DB, O> implements W
      * select * from "person" where "id" in ($1, $2, $3)
      * ```
      *
-     * If everything else fails, you can always pass {@link Kysely.raw | raw}
+     * If everything else fails, you can always use the {@link sql} tag
      * as any of the arguments, including the operator:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()
      *   .where(
-     *     db.raw('coalesce(first_name, last_name)'),
+     *     sql`coalesce(first_name, last_name)`,
      *     'like',
      *     '%' + name + '%',
      *   )
@@ -176,24 +177,25 @@ export declare class UpdateQueryBuilder<DB, TB extends keyof DB, O> implements W
      * ```
      *
      * In all examples above the columns were known at compile time
-     * (except for the `raw` expressions). By default kysely only allows
-     * you to refer to columns that exist in the database **and** can be
-     * referred to in the current query and context.
+     * (except for the raw {@link sql} expressions). By default kysely only
+     * allows you to refer to columns that exist in the database **and**
+     * can be referred to in the current query and context.
      *
      * Sometimes you may want to refer to columns that come from the user
      * input and thus are not available at compile time.
      *
-     * You have two options, `db.raw` or `db.dynamic`. The example below
+     * You have two options, the {@link sql} tag or `db.dynamic`. The example below
      * uses both:
      *
      * ```ts
+     * import { sql } from 'kysely'
      * const { ref } = db.dynamic
      *
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()
      *   .where(ref(columnFromUserInput), '=', 1)
-     *   .orWhere(db.raw('??', [columnFromUserInput]), '=', 2)
+     *   .orWhere(sql.id(columnFromUserInput), '=', 2)
      *   .execute()
      * ```
      */
@@ -327,13 +329,14 @@ export declare class UpdateQueryBuilder<DB, TB extends keyof DB, O> implements W
     /**
      * Adds a `where exists` clause to the query.
      *
-     * You can either use a subquery or a raw instance.
+     * You can either use a subquery or a raw {@link sql} snippet.
      *
      * ### Examples
      *
      * The query below selets all persons that own a pet named Catto:
      *
      * ```ts
+     * const petName = 'Catto'
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()
@@ -341,7 +344,7 @@ export declare class UpdateQueryBuilder<DB, TB extends keyof DB, O> implements W
      *     .selectFrom('pet')
      *     .select('pet.id')
      *     .whereRef('person.id', '=', 'pet.owner_id')
-     *     .where('pet.name', '=', 'Catto')
+     *     .where('pet.name', '=', petName)
      *   )
      *   .execute()
      * ```
@@ -358,16 +361,16 @@ export declare class UpdateQueryBuilder<DB, TB extends keyof DB, O> implements W
      * )
      * ```
      *
-     * The same query as in the previous example but with using raw:
+     * The same query as in the previous example but with using raw {@link sql}:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
+     * const petName = 'Catto'
      * db.selectFrom('person')
      *   .selectAll()
      *   .whereExists(
-     *     db.raw(
-     *       '(select pet.id from pet where person.id = pet.owner_id and pet.name = ?)',
-     *       ['Catto']
-     *     )
+     *     sql`(select pet.id from pet where person.id = pet.owner_id and pet.name = ${petName})`
      *   )
      * ```
      *
@@ -526,8 +529,8 @@ export declare class UpdateQueryBuilder<DB, TB extends keyof DB, O> implements W
      * Sets the values to update for an {@link Kysely.updateTable | update} query.
      *
      * This method takes an object whose keys are column names and values are
-     * values to update. In addition to the column's type, the values can be `raw`
-     * instances or select queries.
+     * values to update. In addition to the column's type, the values can be
+     * raw {@link sql} snippets or select queries.
      *
      * The return value of an update query is an instance of {@link UpdateResult}.
      * You can use the {@link returning} method on supported databases to get out
@@ -580,16 +583,18 @@ export declare class UpdateQueryBuilder<DB, TB extends keyof DB, O> implements W
      * update "person" set "first_name" = $1, "last_name" = $2 where "id" = $3 returning "id"
      * ```
      *
-     * In addition to primitives, the values can also be `raw` expressions or
+     * In addition to primitives, the values can also be raw sql expressions or
      * select queries:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * const result = await db
      *   .updateTable('person')
      *   .set({
      *     first_name: 'Jennifer',
-     *     last_name: db.raw('? || ?', ['Ani', 'ston']),
-     *     age: db.selectFrom('person').select(raw('avg(age)')),
+     *     last_name: sql`${'Ani'} || ${'ston'}`,
+     *     age: db.selectFrom('person').select(sql`avg(age)`),
      *   })
      *   .where('id', '=', 1)
      *   .executeTakeFirst()
@@ -651,7 +656,7 @@ export declare class UpdateQueryBuilder<DB, TB extends keyof DB, O> implements W
      * Return arbitrary expressions:
      *
      * ```ts
-     * const { raw } = db
+     * import { sql } from 'kysely'
      *
      * const { id, full_name, first_pet_id } = await db
      *   .insertInto('person')
@@ -661,7 +666,7 @@ export declare class UpdateQueryBuilder<DB, TB extends keyof DB, O> implements W
      *   })
      *   .returning([
      *     'id as id',
-     *     raw<string>(`concat(first_name, ' ', last_name)`).as('full_name'),
+     *     sql<string>`concat(first_name, ' ', last_name)`.as('full_name'),
      *     (qb) => qb.selectFrom('pets').select('pet.id').limit(1).as('first_pet_id')
      *   ])
      *   .executeTakeFirst()
@@ -772,5 +777,4 @@ export interface UpdateQueryBuilderProps {
     readonly queryId: QueryId;
     readonly queryNode: UpdateQueryNode;
     readonly executor: QueryExecutor;
-    readonly parseContext: ParseContext;
 }

package/dist/esm/query-builder/update-query-builder.js

@@ -17,81 +17,81 @@ export class UpdateQueryBuilder {
     where(...args) {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseWhereFilter(this.#props.parseContext, args)),
+            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseWhereFilter(args)),
         });
     }
     whereRef(lhs, op, rhs) {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseReferenceFilter(this.#props.parseContext, lhs, op, rhs)),
+            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseReferenceFilter(lhs, op, rhs)),
         });
     }
     orWhere(...args) {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithOrWhere(this.#props.queryNode, parseWhereFilter(this.#props.parseContext, args)),
+            queryNode: QueryNode.cloneWithOrWhere(this.#props.queryNode, parseWhereFilter(args)),
         });
     }
     orWhereRef(lhs, op, rhs) {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithOrWhere(this.#props.queryNode, parseReferenceFilter(this.#props.parseContext, lhs, op, rhs)),
+            queryNode: QueryNode.cloneWithOrWhere(this.#props.queryNode, parseReferenceFilter(lhs, op, rhs)),
         });
     }
     whereExists(arg) {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseExistFilter(this.#props.parseContext, arg)),
+            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseExistFilter(arg)),
         });
     }
     whereNotExists(arg) {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseNotExistFilter(this.#props.parseContext, arg)),
+            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseNotExistFilter(arg)),
         });
     }
     orWhereExists(arg) {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithOrWhere(this.#props.queryNode, parseExistFilter(this.#props.parseContext, arg)),
+            queryNode: QueryNode.cloneWithOrWhere(this.#props.queryNode, parseExistFilter(arg)),
         });
     }
     orWhereNotExists(arg) {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithOrWhere(this.#props.queryNode, parseNotExistFilter(this.#props.parseContext, arg)),
+            queryNode: QueryNode.cloneWithOrWhere(this.#props.queryNode, parseNotExistFilter(arg)),
         });
     }
     innerJoin(...args) {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithJoin(this.#props.queryNode, parseJoin(this.#props.parseContext, 'InnerJoin', args)),
+            queryNode: QueryNode.cloneWithJoin(this.#props.queryNode, parseJoin('InnerJoin', args)),
         });
     }
     leftJoin(...args) {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithJoin(this.#props.queryNode, parseJoin(this.#props.parseContext, 'LeftJoin', args)),
+            queryNode: QueryNode.cloneWithJoin(this.#props.queryNode, parseJoin('LeftJoin', args)),
         });
     }
     rightJoin(...args) {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithJoin(this.#props.queryNode, parseJoin(this.#props.parseContext, 'RightJoin', args)),
+            queryNode: QueryNode.cloneWithJoin(this.#props.queryNode, parseJoin('RightJoin', args)),
         });
     }
     fullJoin(...args) {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithJoin(this.#props.queryNode, parseJoin(this.#props.parseContext, 'FullJoin', args)),
+            queryNode: QueryNode.cloneWithJoin(this.#props.queryNode, parseJoin('FullJoin', args)),
         });
     }
     /**
      * Sets the values to update for an {@link Kysely.updateTable | update} query.
      *
      * This method takes an object whose keys are column names and values are
-     * values to update. In addition to the column's type, the values can be `raw`
-     * instances or select queries.
+     * values to update. In addition to the column's type, the values can be
+     * raw {@link sql} snippets or select queries.
      *
      * The return value of an update query is an instance of {@link UpdateResult}.
      * You can use the {@link returning} method on supported databases to get out
@@ -144,16 +144,18 @@ export class UpdateQueryBuilder {
      * update "person" set "first_name" = $1, "last_name" = $2 where "id" = $3 returning "id"
      * ```
      *
-     * In addition to primitives, the values can also be `raw` expressions or
+     * In addition to primitives, the values can also be raw sql expressions or
      * select queries:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * const result = await db
      *   .updateTable('person')
      *   .set({
      *     first_name: 'Jennifer',
-     *     last_name: db.raw('? || ?', ['Ani', 'ston']),
-     *     age: db.selectFrom('person').select(raw('avg(age)')),
+     *     last_name: sql`${'Ani'} || ${'ston'}`,
+     *     age: db.selectFrom('person').select(sql`avg(age)`),
      *   })
      *   .where('id', '=', 1)
      *   .executeTakeFirst()
@@ -174,13 +176,13 @@ export class UpdateQueryBuilder {
     set(row) {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: UpdateQueryNode.cloneWithUpdates(this.#props.queryNode, parseUpdateObject(this.#props.parseContext, row)),
+            queryNode: UpdateQueryNode.cloneWithUpdates(this.#props.queryNode, parseUpdateObject(row)),
         });
     }
     returning(selection) {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithReturning(this.#props.queryNode, parseSelectExpressionOrList(this.#props.parseContext, selection)),
+            queryNode: QueryNode.cloneWithReturning(this.#props.queryNode, parseSelectExpressionOrList(selection)),
         });
     }
     returningAll() {
@@ -291,7 +293,7 @@ export class UpdateQueryBuilder {
         const compildQuery = this.compile();
         const query = compildQuery.query;
         const result = await this.#props.executor.executeQuery(compildQuery, this.#props.queryId);
-        if (this.#props.parseContext.adapter.supportsReturning && query.returning) {
+        if (this.#props.executor.adapter.supportsReturning && query.returning) {
             return result.rows;
         }
         else {

package/dist/esm/query-builder/where-interface.d.ts

@@ -26,7 +26,7 @@ export interface WhereInterface<DB, TB extends keyof DB> {
      * ```
      *
      * Operator can be any supported operator or if the typings don't support it
-     * you can always use `db.raw('your operator')`.
+     * you can always use `sql\`your operator\``.
      *
      * ```ts
      * const persons = await db
@@ -96,7 +96,7 @@ export interface WhereInterface<DB, TB extends keyof DB> {
      *
      * A `where in` query can be built by using the `in` operator and an array
      * of values. The values in the array can also be subqueries or raw
-     * instances.
+     * {@link sql} expressions.
      *
      * ```ts
      * const persons = await db
@@ -112,15 +112,17 @@ export interface WhereInterface<DB, TB extends keyof DB> {
      * select * from "person" where "id" in ($1, $2, $3)
      * ```
      *
-     * If everything else fails, you can always pass {@link Kysely.raw | raw}
+     * If everything else fails, you can always use the {@link sql} tag
      * as any of the arguments, including the operator:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()
      *   .where(
-     *     db.raw('coalesce(first_name, last_name)'),
+     *     sql`coalesce(first_name, last_name)`,
      *     'like',
      *     '%' + name + '%',
      *   )
@@ -155,24 +157,25 @@ export interface WhereInterface<DB, TB extends keyof DB> {
      * ```
      *
      * In all examples above the columns were known at compile time
-     * (except for the `raw` expressions). By default kysely only allows
-     * you to refer to columns that exist in the database **and** can be
-     * referred to in the current query and context.
+     * (except for the raw {@link sql} expressions). By default kysely only
+     * allows you to refer to columns that exist in the database **and**
+     * can be referred to in the current query and context.
      *
      * Sometimes you may want to refer to columns that come from the user
      * input and thus are not available at compile time.
      *
-     * You have two options, `db.raw` or `db.dynamic`. The example below
+     * You have two options, the {@link sql} tag or `db.dynamic`. The example below
      * uses both:
      *
      * ```ts
+     * import { sql } from 'kysely'
      * const { ref } = db.dynamic
      *
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()
      *   .where(ref(columnFromUserInput), '=', 1)
-     *   .orWhere(db.raw('??', [columnFromUserInput]), '=', 2)
+     *   .orWhere(sql.id(columnFromUserInput), '=', 2)
      *   .execute()
      * ```
      */
@@ -306,13 +309,14 @@ export interface WhereInterface<DB, TB extends keyof DB> {
     /**
      * Adds a `where exists` clause to the query.
      *
-     * You can either use a subquery or a raw instance.
+     * You can either use a subquery or a raw {@link sql} snippet.
      *
      * ### Examples
      *
      * The query below selets all persons that own a pet named Catto:
      *
      * ```ts
+     * const petName = 'Catto'
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()
@@ -320,7 +324,7 @@ export interface WhereInterface<DB, TB extends keyof DB> {
      *     .selectFrom('pet')
      *     .select('pet.id')
      *     .whereRef('person.id', '=', 'pet.owner_id')
-     *     .where('pet.name', '=', 'Catto')
+     *     .where('pet.name', '=', petName)
      *   )
      *   .execute()
      * ```
@@ -337,16 +341,16 @@ export interface WhereInterface<DB, TB extends keyof DB> {
      * )
      * ```
      *
-     * The same query as in the previous example but with using raw:
+     * The same query as in the previous example but with using raw {@link sql}:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
+     * const petName = 'Catto'
      * db.selectFrom('person')
      *   .selectAll()
      *   .whereExists(
-     *     db.raw(
-     *       '(select pet.id from pet where person.id = pet.owner_id and pet.name = ?)',
-     *       ['Catto']
-     *     )
+     *     sql`(select pet.id from pet where person.id = pet.owner_id and pet.name = ${petName})`
      *   )
      * ```
      *