kysely 0.11.1 → 0.12.0

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

@@ -0,0 +1,439 @@
+import { OperationNodeSource } from '../operation-node/operation-node-source.js';
+import { CompiledQuery } from '../query-compiler/compiled-query.js';
+import { SelectExpression } from '../parser/select-parser.js';
+import { InsertObject } from '../parser/insert-values-parser.js';
+import { InsertQueryNode } from '../operation-node/insert-query-node.js';
+import { AnyColumn, SingleResultType } from '../util/type-utils.js';
+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 { OnConflictConstraintTarget } from '../parser/on-conflict-parser.js';
+import { ParseContext } from '../parser/parse-context.js';
+import { KyselyPlugin } from '../plugin/kysely-plugin.js';
+import { ReturningRow } from '../parser/returning-parser.js';
+import { NoResultErrorConstructor } from './no-result-error.js';
+import { ComplexExpression } from '../parser/complex-expression-parser.js';
+import { ReturningInterface } from './returning-interface.js';
+export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements ReturningInterface<DB, TB, O>, OperationNodeSource, Compilable {
+    #private;
+    constructor(props: InsertQueryBuilderProps);
+    /**
+     * Sets the values to insert for an {@link Kysely.insertInto | insert} query.
+     *
+     * This method takes an object whose keys are column names and values are
+     * values to insert. In addition to the column's type, the values can be
+     * {@link Kysely.raw | raw} instances, select queries or the
+     * {@link Kysely.generated | generated} placeholder.
+     *
+     * You must provide all values defined by the interface of the table you
+     * are inserting into. Values that are generated by the database like auto incrementing
+     * identifiers can be marked with the {@link Kysely.generated} placeholder unless you
+     * want to insert a specific value instead of the generated default.
+     *
+     * The return value of an `insert` query is an instance of {@link InsertResult}. The
+     * {@link InsertResult.insertId | insertId} field holds the auto incremented primary
+     * key if the database returned one.
+     *
+     * On PostgreSQL and some other dialects, you need to call `returning` to get
+     * something out of the query.
+     *
+     * Also see the {@link expression} method for inserting the result of a select
+     * query or any other expression.
+     *
+     * ### Examples
+     *
+     * Insert a row into `person`:
+     * ```ts
+     * const id = await db
+     *   .insertInto('person')
+     *   .values({
+     *     id: db.generated,
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston'
+     *   })
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "person" ("first_name", "last_name") values ($1, $2)
+     * ```
+     *
+     * On dialects that support it (for example PostgreSQL) you can insert multiple
+     * rows by providing an array. Note that the return value is once again very
+     * dialect-specific. Some databases may only return the id of the *last* inserted
+     * row and some return nothing at all unless you call `returning`.
+     *
+     * ```ts
+     * await db
+     *   .insertInto('person')
+     *   .values([{
+     *     id: db.generated,
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston'
+     *   }, {
+     *     id: db.generated,
+     *     first_name: 'Arnold',
+     *     last_name: 'Schwarzenegger',
+     *   }])
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "person" ("first_name", "last_name") values (($1, $2), ($3, $4))
+     * ```
+     *
+     * On PostgreSQL you need to chain `returning` to the query to get
+     * the inserted row's columns (or any other expression) as the
+     * return value:
+     *
+     * ```ts
+     * const row = await db
+     *   .insertInto('person')
+     *   .values({
+     *     id: db.generated,
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston'
+     *   })
+     *   .returning('id')
+     *   .executeTakeFirstOrThrow()
+     *
+     * row.id
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "person" ("first_name", "last_name") values ($1, $2) returning "id"
+     * ```
+     *
+     * In addition to primitives, the values can also be `raw` expressions or
+     * select queries:
+     *
+     * ```ts
+     * const result = await db
+     *   .insertInto('person')
+     *   .values({
+     *     id: db.generated,
+     *     first_name: 'Jennifer',
+     *     last_name: db.raw('? || ?', ['Ani', 'ston']),
+     *     age: db.selectFrom('person').select(raw('avg(age)')),
+     *   })
+     *   .executeTakeFirst()
+     *
+     * console.log(result.insertId)
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "person" ("first_name", "last_name", "age")
+     * values ($1, $2 || $3, (select avg(age) from "person"))
+     * ```
+     *
+     * You can also use the callback version of subqueries or raw expressions:
+     *
+     * ```ts
+     * db.with('jennifer', (db) => db
+     *   .selectFrom('person')
+     *   .where('first_name', '=', 'Jennifer')
+     *   .select(['id', 'first_name', 'gender'])
+     *   .limit(1)
+     * ).insertInto('pet').values({
+     *   id: db.generated,
+     *   owner_id: (eb) => eb.selectFrom('jennifer').select('id'),
+     *   name: (eb) => eb.selectFrom('jennifer').select('first_name'),
+     *   species: 'cat',
+     * })
+     * ```
+     */
+    values(row: InsertObject<DB, TB>): InsertQueryBuilder<DB, TB, O>;
+    values(row: ReadonlyArray<InsertObject<DB, TB>>): InsertQueryBuilder<DB, TB, O>;
+    /**
+     * Sets the columns to insert.
+     *
+     * The {@link values} method sets both the columns and the values and this method
+     * is not needed. But if you are using the {@link expression} method, you can use
+     * this method to set the columns to insert.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.insertInto('person')
+     *   .columns(['first_name'])
+     *   .expression((eb) => eb.selectFrom('pet').select('pet.name'))
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "person" ("first_name")
+     * select "pet"."name" from "pet"
+     * ```
+     */
+    columns(columns: ReadonlyArray<keyof DB[TB] & string>): InsertQueryBuilder<DB, TB, O>;
+    /**
+     * Insert an arbitrary expression. For example the result of a select query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.insertInto('person')
+     *   .columns(['first_name'])
+     *   .expression((eb) => eb.selectFrom('pet').select('pet.name'))
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "person" ("first_name")
+     * select "pet"."name" from "pet"
+     * ```
+     */
+    expression(expression: ComplexExpression<DB, TB>): InsertQueryBuilder<DB, TB, O>;
+    /**
+     * Ignores the insert if the column or constraint given as the first
+     * argument conflicts with the current rows in the database. The
+     * default behavior without this method call is to throw an error.
+     *
+     * For example if a table has a field `name` that has a unique constraint
+     * and you try to insert a row with a `name` that already exists in the
+     * database, calling `onConflictDoNothing('name')` will ignore the conflict
+     * and do nothing. By default the query would throw.
+     *
+     * Only some dialects like PostgreSQL and SQLite implement the `on conflict`
+     * statement. On MySQL you should use the {@link ignore} method to achieve
+     * similar results.
+     *
+     * Also see the {@link InsertQueryBuilder.onConflictUpdate | onConflictUpdate}
+     * method if you want to perform an update in case of a conflict (upsert).
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db
+     *   .insertInto('pet')
+     *   .values({
+     *     id: db.generated,
+     *     name: 'Catto',
+     *     species: 'cat',
+     *   })
+     *   .onConflictDoNothing('name')
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "pet" ("name", "species")
+     * values ($1, $2)
+     * on conflict ("name") do nothing
+     * ```
+     *
+     * You can provide the name of the constraint instead of a column name
+     *
+     * ```ts
+     * await db
+     *   .insertInto('pet')
+     *   .values({
+     *     id: db.generated,
+     *     name: 'Catto',
+     *     species: 'cat',
+     *   })
+     *   .onConflictDoNothing({
+     *     constraint: 'pet_name_key'
+     *   })
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "pet" ("name", "species")
+     * values ($1, $2)
+     * on conflict on constraint "pet_name_key"
+     * do nothing
+     * ```
+     */
+    onConflictDoNothing(column: AnyColumn<DB, TB>): InsertQueryBuilder<DB, TB, O>;
+    onConflictDoNothing(columns: ReadonlyArray<AnyColumn<DB, TB>>): InsertQueryBuilder<DB, TB, O>;
+    onConflictDoNothing(constraint: OnConflictConstraintTarget): InsertQueryBuilder<DB, TB, O>;
+    /**
+     * Changes an `insert into` query to an `insert ignore into` query.
+     *
+     * If you use the ignore modifier, ignorable errors that occur while executing the
+     * insert statement are ignored. For example, without ignore, a row that duplicates
+     * an existing unique index or primary key value in the table causes a duplicate-key
+     * error and the statement is aborted. With ignore, the row is discarded and no error
+     * occurs.
+     *
+     * This is only supported on some dialects like MySQL. On most dialects you should
+     * use the {@link onConflictDoNothing} method.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.insertInto('person')
+     *   .ignore()
+     *   .values(values)
+     *   .execute()
+     * ```
+     */
+    ignore(): InsertQueryBuilder<DB, TB, O>;
+    /**
+     * Ignores an insert if the column or constraint given as the first
+     * argument conflicts with the current rows in the database and
+     * performs an update on the conflicting row instead. This method
+     * can be used to implement an upsert operation.
+     *
+     * For example if a table has a field `name` that has a unique constraint
+     * and you try to insert a row with a `name` that already exists in the
+     * database, calling `onConfictUpdate('name', { species: 'hamster' })`
+     * will set the conflicting row's `species` field to value `'hamster'`.
+     * By default the query would throw.
+     *
+     * The second argument (updates) can be anything the {@link UpdateQueryBuilder.set | set}
+     * method accepts.
+     *
+     * The `on conflict do update` statement is only implemented by some dialects
+     * like PostgreSQL and SQLite. On MySQL you should use the {@link onDuplicateKeyUpdate}
+     * method instead.
+     *
+     * Also see the {@link InsertQueryBuilder.onConflictDoNothing | onConflictDoNothing}
+     * method.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db
+     *   .insertInto('pet')
+     *   .values({
+     *     id: db.generated,
+     *     name: 'Catto',
+     *     species: 'cat',
+     *   })
+     *   .onConflictUpdate('name', { species: 'hamster' })
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "pet" ("name", "species")
+     * values ($1, $2)
+     * on conflict ("name") do update set "species" = $3
+     * ```
+     *
+     * You can provied the name of the constraint instead of a column name
+     *
+     * ```ts
+     * await db
+     *   .insertInto('pet')
+     *   .values({
+     *     id: db.generated,
+     *     name: 'Catto',
+     *     species: 'cat',
+     *   })
+     *   .onConflictUpdate(
+     *     { constraint: 'pet_name_key' },
+     *     { species: 'hamster' }
+     *   )
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "pet" ("name", "species")
+     * values ($1, $2)
+     * on conflict on constraint "pet_name_key"
+     * do update set "species" = $3
+     * ```
+     */
+    onConflictUpdate(column: AnyColumn<DB, TB>, updates: MutationObject<DB, TB>): InsertQueryBuilder<DB, TB, O>;
+    onConflictUpdate(columns: ReadonlyArray<AnyColumn<DB, TB>>, updates: MutationObject<DB, TB>): InsertQueryBuilder<DB, TB, O>;
+    onConflictUpdate(constraint: OnConflictConstraintTarget, updates: MutationObject<DB, TB>): InsertQueryBuilder<DB, TB, O>;
+    /**
+     * Adds `on duplicate key update` to the query.
+     *
+     * If you specify `on duplicate key update`, and a row is inserted that would cause
+     * a duplicate value in a unique index or primary key, an update of the old row occurs.
+     *
+     * This is only implemented by some dialects like MySQL. On most dialects you should
+     * use {@link onConflictUpdate} instead.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db
+     *   .insertInto('person')
+     *   .values(values)
+     *   .onDuplicateKeyUpdate({ species: 'hamster' })
+     * ```
+     */
+    onDuplicateKeyUpdate(updates: MutationObject<DB, TB>): InsertQueryBuilder<DB, TB, O>;
+    returning<SE extends SelectExpression<DB, TB>>(selections: ReadonlyArray<SE>): InsertQueryBuilder<DB, TB, ReturningRow<DB, TB, O, SE>>;
+    returning<SE extends SelectExpression<DB, TB>>(selection: SE): InsertQueryBuilder<DB, TB, ReturningRow<DB, TB, O, SE>>;
+    returningAll(): InsertQueryBuilder<DB, TB, DB[TB]>;
+    /**
+     * Simply calls the given function passing `this` as the only argument.
+     *
+     * This method can be useful when adding optional method calls:
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.insertInto('person')
+     *   .selectAll()
+     *   .call((qb) => {
+     *     if (something) {
+     *       return qb.onConflictDoNothing('something')
+     *     } else {
+     *       return qb.onConflictDoNothing('something_else')
+     *     }
+     *   })
+     *   .execute()
+     * ```
+     */
+    call<T>(func: (qb: this) => T): T;
+    /**
+     * Change the output type of the query.
+     *
+     * You should only use this method as the last resort if the types
+     * don't support your use case.
+     */
+    castTo<T>(): InsertQueryBuilder<DB, TB, T>;
+    withPlugin(plugin: KyselyPlugin): InsertQueryBuilder<DB, TB, O>;
+    toOperationNode(): InsertQueryNode;
+    compile(): CompiledQuery;
+    /**
+     * Executes the query and returns an array of rows.
+     *
+     * Also see the {@link executeTakeFirst} and {@link executeTakeFirstOrThrow} methods.
+     */
+    execute(): Promise<O[]>;
+    /**
+     * Executes the query and returns the first result or undefined if
+     * the query returned no result.
+     */
+    executeTakeFirst(): Promise<SingleResultType<O>>;
+    /**
+     * Executes the query and returns the first result or throws if
+     * the query returned no result.
+     *
+     * By default an instance of {@link NoResultError} is thrown, but you can
+     * provide a custom error class as the only argument to throw a different
+     * error.
+     */
+    executeTakeFirstOrThrow(errorConstructor?: NoResultErrorConstructor): Promise<O>;
+}
+export interface InsertQueryBuilderProps {
+    readonly queryId: QueryId;
+    readonly queryNode: InsertQueryNode;
+    readonly executor: QueryExecutor;
+    readonly parseContext: ParseContext;
+}

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

@@ -0,0 +1,252 @@
+import { parseSelectExpressionOrList, parseSelectAll, } from '../parser/select-parser.js';
+import { parseInsertObjectOrList, } from '../parser/insert-values-parser.js';
+import { InsertQueryNode } from '../operation-node/insert-query-node.js';
+import { QueryNode } from '../operation-node/query-node.js';
+import { parseUpdateObject, } from '../parser/update-set-parser.js';
+import { preventAwait } from '../util/prevent-await.js';
+import { parseOnConflictDoNothing, parseOnConflictUpdate, } from '../parser/on-conflict-parser.js';
+import { freeze } from '../util/object-utils.js';
+import { OnDuplicateKeyNode } from '../operation-node/on-duplicate-key-node.js';
+import { InsertResult } from './insert-result.js';
+import { NoResultError } from './no-result-error.js';
+import { parseComplexExpression, } from '../parser/complex-expression-parser.js';
+import { ColumnNode } from '../operation-node/column-node.js';
+export class InsertQueryBuilder {
+    #props;
+    constructor(props) {
+        this.#props = freeze(props);
+    }
+    values(args) {
+        const [columns, values] = parseInsertObjectOrList(this.#props.parseContext, args);
+        return new InsertQueryBuilder({
+            ...this.#props,
+            queryNode: InsertQueryNode.cloneWith(this.#props.queryNode, {
+                columns,
+                values,
+            }),
+        });
+    }
+    /**
+     * Sets the columns to insert.
+     *
+     * The {@link values} method sets both the columns and the values and this method
+     * is not needed. But if you are using the {@link expression} method, you can use
+     * this method to set the columns to insert.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.insertInto('person')
+     *   .columns(['first_name'])
+     *   .expression((eb) => eb.selectFrom('pet').select('pet.name'))
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "person" ("first_name")
+     * select "pet"."name" from "pet"
+     * ```
+     */
+    columns(columns) {
+        return new InsertQueryBuilder({
+            ...this.#props,
+            queryNode: InsertQueryNode.cloneWith(this.#props.queryNode, {
+                columns: freeze(columns.map(ColumnNode.create)),
+            }),
+        });
+    }
+    /**
+     * Insert an arbitrary expression. For example the result of a select query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.insertInto('person')
+     *   .columns(['first_name'])
+     *   .expression((eb) => eb.selectFrom('pet').select('pet.name'))
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "person" ("first_name")
+     * select "pet"."name" from "pet"
+     * ```
+     */
+    expression(expression) {
+        return new InsertQueryBuilder({
+            ...this.#props,
+            queryNode: InsertQueryNode.cloneWith(this.#props.queryNode, {
+                values: parseComplexExpression(this.#props.parseContext, expression),
+            }),
+        });
+    }
+    onConflictDoNothing(target) {
+        return new InsertQueryBuilder({
+            ...this.#props,
+            queryNode: InsertQueryNode.cloneWith(this.#props.queryNode, {
+                onConflict: parseOnConflictDoNothing(target),
+            }),
+        });
+    }
+    /**
+     * Changes an `insert into` query to an `insert ignore into` query.
+     *
+     * If you use the ignore modifier, ignorable errors that occur while executing the
+     * insert statement are ignored. For example, without ignore, a row that duplicates
+     * an existing unique index or primary key value in the table causes a duplicate-key
+     * error and the statement is aborted. With ignore, the row is discarded and no error
+     * occurs.
+     *
+     * This is only supported on some dialects like MySQL. On most dialects you should
+     * use the {@link onConflictDoNothing} method.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.insertInto('person')
+     *   .ignore()
+     *   .values(values)
+     *   .execute()
+     * ```
+     */
+    ignore() {
+        return new InsertQueryBuilder({
+            ...this.#props,
+            queryNode: InsertQueryNode.cloneWith(this.#props.queryNode, {
+                ignore: true,
+            }),
+        });
+    }
+    onConflictUpdate(target, updates) {
+        return new InsertQueryBuilder({
+            ...this.#props,
+            queryNode: InsertQueryNode.cloneWith(this.#props.queryNode, {
+                onConflict: parseOnConflictUpdate(this.#props.parseContext, target, updates),
+            }),
+        });
+    }
+    /**
+     * Adds `on duplicate key update` to the query.
+     *
+     * If you specify `on duplicate key update`, and a row is inserted that would cause
+     * a duplicate value in a unique index or primary key, an update of the old row occurs.
+     *
+     * This is only implemented by some dialects like MySQL. On most dialects you should
+     * use {@link onConflictUpdate} instead.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db
+     *   .insertInto('person')
+     *   .values(values)
+     *   .onDuplicateKeyUpdate({ species: 'hamster' })
+     * ```
+     */
+    onDuplicateKeyUpdate(updates) {
+        return new InsertQueryBuilder({
+            ...this.#props,
+            queryNode: InsertQueryNode.cloneWith(this.#props.queryNode, {
+                onDuplicateKey: OnDuplicateKeyNode.create(parseUpdateObject(this.#props.parseContext, updates)),
+            }),
+        });
+    }
+    returning(selection) {
+        return new InsertQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithReturning(this.#props.queryNode, parseSelectExpressionOrList(this.#props.parseContext, selection)),
+        });
+    }
+    returningAll() {
+        return new InsertQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithReturning(this.#props.queryNode, parseSelectAll()),
+        });
+    }
+    /**
+     * Simply calls the given function passing `this` as the only argument.
+     *
+     * This method can be useful when adding optional method calls:
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.insertInto('person')
+     *   .selectAll()
+     *   .call((qb) => {
+     *     if (something) {
+     *       return qb.onConflictDoNothing('something')
+     *     } else {
+     *       return qb.onConflictDoNothing('something_else')
+     *     }
+     *   })
+     *   .execute()
+     * ```
+     */
+    call(func) {
+        return func(this);
+    }
+    /**
+     * Change the output type of the query.
+     *
+     * You should only use this method as the last resort if the types
+     * don't support your use case.
+     */
+    castTo() {
+        return new InsertQueryBuilder(this.#props);
+    }
+    withPlugin(plugin) {
+        return new InsertQueryBuilder({
+            ...this.#props,
+            executor: this.#props.executor.withPlugin(plugin),
+        });
+    }
+    toOperationNode() {
+        return this.#props.executor.transformQuery(this.#props.queryNode, this.#props.queryId);
+    }
+    compile() {
+        return this.#props.executor.compileQuery(this.toOperationNode(), this.#props.queryId);
+    }
+    /**
+     * Executes the query and returns an array of rows.
+     *
+     * Also see the {@link executeTakeFirst} and {@link executeTakeFirstOrThrow} methods.
+     */
+    async execute() {
+        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) {
+            return result.rows;
+        }
+        else {
+            return [new InsertResult(result.insertId)];
+        }
+    }
+    /**
+     * Executes the query and returns the first result or undefined if
+     * the query returned no result.
+     */
+    async executeTakeFirst() {
+        const [result] = await this.execute();
+        return result;
+    }
+    /**
+     * Executes the query and returns the first result or throws if
+     * the query returned no result.
+     *
+     * By default an instance of {@link NoResultError} is thrown, but you can
+     * provide a custom error class as the only argument to throw a different
+     * error.
+     */
+    async executeTakeFirstOrThrow(errorConstructor = NoResultError) {
+        const result = await this.executeTakeFirst();
+        if (result === undefined) {
+            throw new errorConstructor(this.toOperationNode());
+        }
+        return result;
+    }
+}
+preventAwait(InsertQueryBuilder, "don't await InsertQueryBuilder instances directly. To execute the query you need to call `execute` or `executeTakeFirst`.");

package/dist/esm/query-builder/insert-result.d.ts

@@ -4,10 +4,11 @@
  * If the table has an auto incrementing primary key {@link insertId} will hold
  * the generated id on dialects that support it. For example PostgreSQL doesn't
  * return the id by default and {@link insertId} is undefined. On PostgreSQL you
- * need to use {@link QueryBuilder.returning} or {@link QueryBuilder.returningAll}
+ * need to use {@link ReturningInterface.returning} or {@link ReturningInterface.returningAll}
  * to get out the inserted id.
  *
- * @example
+ * ### Examples
+ *
  * ```ts
  * const result = await db
  *   .insertInto('person')