kysely 0.27.4 → 0.27.6

package/dist/esm/schema/column-definition-builder.js

@@ -20,6 +20,23 @@ export class ColumnDefinitionBuilder {
      *
      * Some dialects like PostgreSQL don't support this. On PostgreSQL
      * you can use the `serial` or `bigserial` data type instead.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('id', 'integer', col => col.autoIncrement().primaryKey())
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * create table `person` (
+     *   `id` integer primary key auto_increment
+     * )
+     * ```
      */
     autoIncrement() {
         return new ColumnDefinitionBuilder(ColumnDefinitionNode.cloneWith(this.#node, { autoIncrement: true }));
@@ -30,6 +47,23 @@ export class ColumnDefinitionBuilder {
      * This only works on some dialects like MS SQL Server (MSSQL).
      *
      * For PostgreSQL's `generated always as identity` use {@link generatedAlwaysAsIdentity}.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('id', 'integer', col => col.identity().primaryKey())
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (MSSQL):
+     *
+     * ```sql
+     * create table "person" (
+     *   "id" integer identity primary key
+     * )
+     * ```
      */
     identity() {
         return new ColumnDefinitionBuilder(ColumnDefinitionNode.cloneWith(this.#node, { identity: true }));
@@ -39,6 +73,22 @@ export class ColumnDefinitionBuilder {
      *
      * If you want to specify a composite primary key use the
      * {@link CreateTableBuilder.addPrimaryKeyConstraint} method.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('id', 'integer', col => col.primaryKey())
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * create table `person` (
+     *   `id` integer primary key
+     * )
      */
     primaryKey() {
         return new ColumnDefinitionBuilder(ColumnDefinitionNode.cloneWith(this.#node, { primaryKey: true }));
@@ -53,7 +103,18 @@ export class ColumnDefinitionBuilder {
      * ### Examples
      *
      * ```ts
-     * col.references('person.id')
+     * await db.schema
+     *   .createTable('pet')
+     *   .addColumn('owner_id', 'integer', (col) => col.references('person.id'))
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * create table "pet" (
+     *   "owner_id" integer references "person" ("id")
+     * )
      * ```
      */
     references(ref) {
@@ -77,7 +138,22 @@ export class ColumnDefinitionBuilder {
      * ### Examples
      *
      * ```ts
-     * col.references('person.id').onDelete('cascade')
+     * await db.schema
+     *   .createTable('pet')
+     *   .addColumn(
+     *     'owner_id',
+     *     'integer',
+     *     (col) => col.references('person.id').onDelete('cascade')
+     *   )
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * create table "pet" (
+     *   "owner_id" integer references "person" ("id") on delete cascade
+     * )
      * ```
      */
     onDelete(onDelete) {
@@ -91,10 +167,29 @@ export class ColumnDefinitionBuilder {
     /**
      * Adds an `on update` constraint for the foreign key column.
      *
+     * If your database engine doesn't support foreign key constraints in the
+     * column definition (like MySQL 5) you need to call the table level
+     * {@link CreateTableBuilder.addForeignKeyConstraint} method instead.
+     *
      * ### Examples
      *
      * ```ts
-     * col.references('person.id').onUpdate('cascade')
+     * await db.schema
+     *   .createTable('pet')
+     *   .addColumn(
+     *     'owner_id',
+     *     'integer',
+     *     (col) => col.references('person.id').onUpdate('cascade')
+     *   )
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * create table "pet" (
+     *   "owner_id" integer references "person" ("id") on update cascade
+     * )
      * ```
      */
     onUpdate(onUpdate) {
@@ -107,12 +202,46 @@ export class ColumnDefinitionBuilder {
     }
     /**
      * Adds a unique constraint for the column.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('email', 'varchar(255)', col => col.unique())
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * create table `person` (
+     *   `email` varchar(255) unique
+     * )
+     * ```
      */
     unique() {
         return new ColumnDefinitionBuilder(ColumnDefinitionNode.cloneWith(this.#node, { unique: true }));
     }
     /**
      * Adds a `not null` constraint for the column.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('first_name', 'varchar(255)', col => col.notNull())
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * create table `person` (
+     *   `first_name` varchar(255) not null
+     * )
+     * ```
      */
     notNull() {
         return new ColumnDefinitionBuilder(ColumnDefinitionNode.cloneWith(this.#node, { notNull: true }));
@@ -121,6 +250,23 @@ export class ColumnDefinitionBuilder {
      * Adds a `unsigned` modifier for the column.
      *
      * This only works on some dialects like MySQL.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('age', 'integer', col => col.unsigned())
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * create table `person` (
+     *   `age` integer unsigned
+     * )
+     * ```
      */
     unsigned() {
         return new ColumnDefinitionBuilder(ColumnDefinitionNode.cloneWith(this.#node, { unsigned: true }));
@@ -131,27 +277,43 @@ export class ColumnDefinitionBuilder {
      * ### Examples
      *
      * ```ts
-     * db.schema
+     * await db.schema
      *   .createTable('pet')
      *   .addColumn('number_of_legs', 'integer', (col) => col.defaultTo(4))
      *   .execute()
      * ```
      *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * create table `pet` (
+     *   `number_of_legs` integer default 4
+     * )
+     * ```
+     *
      * Values passed to `defaultTo` are interpreted as value literals by default. You can define
      * an arbitrary SQL expression using the {@link sql} template tag:
      *
      * ```ts
      * import { sql } from 'kysely'
      *
-     * db.schema
+     * await db.schema
      *   .createTable('pet')
      *   .addColumn(
-     *     'number_of_legs',
-     *     'integer',
-     *     (col) => col.defaultTo(sql`any SQL here`)
+     *     'created_at',
+     *     'timestamp',
+     *     (col) => col.defaultTo(sql`CURRENT_TIMESTAMP`)
      *   )
      *   .execute()
      * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * create table `pet` (
+     *   `created_at` timestamp default CURRENT_TIMESTAMP
+     * )
+     * ```
      */
     defaultTo(value) {
         return new ColumnDefinitionBuilder(ColumnDefinitionNode.cloneWith(this.#node, {
@@ -166,13 +328,21 @@ export class ColumnDefinitionBuilder {
      * ```ts
      * import { sql } from 'kysely'
      *
-     * db.schema
+     * await db.schema
      *   .createTable('pet')
      *   .addColumn('number_of_legs', 'integer', (col) =>
      *     col.check(sql`number_of_legs < 5`)
      *   )
      *   .execute()
      * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * create table `pet` (
+     *   `number_of_legs` integer check (number_of_legs < 5)
+     * )
+     * ```
      */
     check(expression) {
         return new ColumnDefinitionBuilder(ColumnDefinitionNode.cloneWith(this.#node, {
@@ -187,13 +357,21 @@ export class ColumnDefinitionBuilder {
      * ```ts
      * import { sql } from 'kysely'
      *
-     * db.schema
+     * await db.schema
      *   .createTable('person')
      *   .addColumn('full_name', 'varchar(255)',
      *     (col) => col.generatedAlwaysAs(sql`concat(first_name, ' ', last_name)`)
      *   )
      *   .execute()
      * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * create table `person` (
+     *   `full_name` varchar(255) generated always as (concat(first_name, ' ', last_name))
+     * )
+     * ```
      */
     generatedAlwaysAs(expression) {
         return new ColumnDefinitionBuilder(ColumnDefinitionNode.cloneWith(this.#node, {
@@ -206,6 +384,23 @@ export class ColumnDefinitionBuilder {
      * This only works on some dialects like PostgreSQL.
      *
      * For MS SQL Server (MSSQL)'s identity column use {@link identity}.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('id', 'integer', col => col.generatedAlwaysAsIdentity().primaryKey())
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * create table "person" (
+     *   "id" integer generated always as identity primary key
+     * )
+     * ```
      */
     generatedAlwaysAsIdentity() {
         return new ColumnDefinitionBuilder(ColumnDefinitionNode.cloneWith(this.#node, {
@@ -214,6 +409,27 @@ export class ColumnDefinitionBuilder {
     }
     /**
      * Adds the `generated by default as identity` specifier on supported dialects.
+     *
+     * This only works on some dialects like PostgreSQL.
+     *
+     * For MS SQL Server (MSSQL)'s identity column use {@link identity}.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('id', 'integer', col => col.generatedByDefaultAsIdentity().primaryKey())
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * create table "person" (
+     *   "id" integer generated by default as identity primary key
+     * )
+     * ```
      */
     generatedByDefaultAsIdentity() {
         return new ColumnDefinitionBuilder(ColumnDefinitionNode.cloneWith(this.#node, {
@@ -227,14 +443,24 @@ export class ColumnDefinitionBuilder {
      * ### Examples
      *
      * ```ts
-     * db.schema
+     * import { sql } from 'kysely'
+     *
+     * await db.schema
      *   .createTable('person')
      *   .addColumn('full_name', 'varchar(255)', (col) => col
-     *     .generatedAlwaysAs("concat(first_name, ' ', last_name)")
+     *     .generatedAlwaysAs(sql`concat(first_name, ' ', last_name)`)
      *     .stored()
      *   )
      *   .execute()
      * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * create table `person` (
+     *   `full_name` varchar(255) generated always as (concat(first_name, ' ', last_name)) stored
+     * )
+     * ```
      */
     stored() {
         if (!this.#node.generated) {
@@ -252,10 +478,17 @@ export class ColumnDefinitionBuilder {
      * ### Examples
      *
      * ```ts
-     * db.schema.createTable('person')
-     *  .addColumn('id', 'integer', col => col.primaryKey())
-     *  .addColumn('first_name', 'varchar(36)', col => col.modifyFront(sql`collate utf8mb4_general_ci`).notNull())
-     *  .execute()
+     * import { sql } from 'kysely'
+     *
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('id', 'integer', col => col.primaryKey())
+     *   .addColumn(
+     *     'first_name',
+     *     'varchar(36)',
+     *     (col) => col.modifyFront(sql`collate utf8mb4_general_ci`).notNull()
+     *   )
+     *   .execute()
      * ```
      *
      * The generated SQL (MySQL):
@@ -279,10 +512,11 @@ export class ColumnDefinitionBuilder {
      * ### Examples
      *
      * ```ts
-     * db.schema.createTable('person')
-     *  .addColumn('id', 'integer', col => col.primaryKey())
-     *  .addColumn('first_name', 'varchar(30)', col => col.unique().nullsNotDistinct())
-     *  .execute()
+     * db.schema
+     *   .createTable('person')
+     *   .addColumn('id', 'integer', col => col.primaryKey())
+     *   .addColumn('first_name', 'varchar(30)', col => col.unique().nullsNotDistinct())
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -298,8 +532,22 @@ export class ColumnDefinitionBuilder {
         return new ColumnDefinitionBuilder(ColumnDefinitionNode.cloneWith(this.#node, { nullsNotDistinct: true }));
     }
     /**
-     * Adds `if not exists` specifier.
-     * This only works for PostgreSQL.
+     * Adds `if not exists` specifier. This only works for PostgreSQL.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.schema
+     *   .alterTable('person')
+     *   .addColumn('email', 'varchar(255)', col => col.unique().ifNotExists())
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * alter table "person" add column if not exists "email" varchar(255) unique
+     * ```
      */
     ifNotExists() {
         return new ColumnDefinitionBuilder(ColumnDefinitionNode.cloneWith(this.#node, { ifNotExists: true }));
@@ -310,10 +558,19 @@ export class ColumnDefinitionBuilder {
      * ### Examples
      *
      * ```ts
-     * db.schema.createTable('person')
-     *  .addColumn('id', 'integer', col => col.primaryKey())
-     *  .addColumn('age', 'integer', col => col.unsigned().notNull().modifyEnd(sql`comment ${sql.lit('it is not polite to ask a woman her age')}`))
-     *  .execute()
+     * import { sql } from 'kysely'
+     *
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('id', 'integer', col => col.primaryKey())
+     *   .addColumn(
+     *     'age',
+     *     'integer',
+     *     col => col.unsigned()
+     *       .notNull()
+     *       .modifyEnd(sql`comment ${sql.lit('it is not polite to ask a woman her age')}`)
+     *   )
+     *   .execute()
      * ```
      *
      * The generated SQL (MySQL):

package/dist/esm/schema/create-table-builder.d.ts

@@ -44,7 +44,7 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      *
      * await db.schema
      *   .createTable('person')
-     *   .addColumn('id', 'integer', (col) => col.autoIncrement().primaryKey()),
+     *   .addColumn('id', 'integer', (col) => col.autoIncrement().primaryKey())
      *   .addColumn('first_name', 'varchar(50)', (col) => col.notNull())
      *   .addColumn('last_name', 'varchar(255)')
      *   .addColumn('bank_balance', 'numeric(8, 2)')
@@ -52,7 +52,7 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      *   // don't include it.
      *   .addColumn('data', sql`any_type_here`)
      *   .addColumn('parent_id', 'integer', (col) =>
-     *     col.references('person.id').onDelete('cascade'))
+     *     col.references('person.id').onDelete('cascade')
      *   )
      * ```
      *
@@ -63,11 +63,18 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      * `create table` query. See the next example:
      *
      * ```ts
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('id', 'integer', (col) => col.primaryKey())
      *   .addColumn('parent_id', 'integer')
      *   .addForeignKeyConstraint(
-     *     'person_parent_id_fk', ['parent_id'], 'person', ['id'],
+     *     'person_parent_id_fk',
+     *     ['parent_id'],
+     *     'person',
+     *     ['id'],
      *     (cb) => cb.onDelete('cascade')
      *   )
+     *   .execute()
      * ```
      *
      * Another good example is that PostgreSQL doesn't support the `auto_increment`
@@ -77,7 +84,8 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      * ```ts
      * await db.schema
      *   .createTable('person')
-     *   .addColumn('id', 'serial', (col) => col.primaryKey()),
+     *   .addColumn('id', 'serial', (col) => col.primaryKey())
+     *   .execute()
      * ```
      */
     addColumn<CN extends string>(columnName: CN, dataType: DataTypeExpression, build?: ColumnBuilderCallback): CreateTableBuilder<TB, C | CN>;
@@ -90,7 +98,12 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      * ### Examples
      *
      * ```ts
-     * addPrimaryKeyConstraint('primary_key', ['first_name', 'last_name'])
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('first_name', 'varchar(64)')
+     *   .addColumn('last_name', 'varchar(64)')
+     *   .addPrimaryKeyConstraint('primary_key', ['first_name', 'last_name'])
+     *   .execute()
      * ```
      */
     addPrimaryKeyConstraint(constraintName: string, columns: C[]): CreateTableBuilder<TB, C>;
@@ -103,12 +116,30 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      * ### Examples
      *
      * ```ts
-     * addUniqueConstraint('first_name_last_name_unique', ['first_name', 'last_name'])
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('first_name', 'varchar(64)')
+     *   .addColumn('last_name', 'varchar(64)')
+     *   .addUniqueConstraint(
+     *     'first_name_last_name_unique',
+     *     ['first_name', 'last_name']
+     *   )
+     *   .execute()
      * ```
      *
      * In dialects such as PostgreSQL you can specify `nulls not distinct` as follows:
+     *
      * ```ts
-     * addUniqueConstraint('first_name_last_name_unique', ['first_name', 'last_name'], (builder) => builder.nullsNotDistinct())
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('first_name', 'varchar(64)')
+     *   .addColumn('last_name', 'varchar(64)')
+     *   .addUniqueConstraint(
+     *     'first_name_last_name_unique',
+     *     ['first_name', 'last_name'],
+     *     (cb) => cb.nullsNotDistinct()
+     *   )
+     *   .execute()
      * ```
      */
     addUniqueConstraint(constraintName: string, columns: C[], build?: UniqueConstraintNodeBuilderCallback): CreateTableBuilder<TB, C>;
@@ -123,7 +154,11 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      * ```ts
      * import { sql } from 'kysely'
      *
-     * addCheckConstraint('check_legs', sql`number_of_legs < 5`)
+     * await db.schema
+     *   .createTable('animal')
+     *   .addColumn('number_of_legs', 'integer')
+     *   .addCheckConstraint('check_legs', sql`number_of_legs < 5`)
+     *   .execute()
      * ```
      */
     addCheckConstraint(constraintName: string, checkExpression: Expression<any>): CreateTableBuilder<TB, C>;
@@ -136,24 +171,33 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      * ### Examples
      *
      * ```ts
-     * addForeignKeyConstraint(
-     *   'owner_id_foreign',
-     *   ['owner_id'],
-     *   'person',
-     *   ['id'],
-     * )
+     * await db.schema
+     *   .createTable('pet')
+     *   .addColumn('owner_id', 'integer')
+     *   .addForeignKeyConstraint(
+     *     'owner_id_foreign',
+     *     ['owner_id'],
+     *     'person',
+     *     ['id'],
+     *   )
+     *   .execute()
      * ```
      *
      * Add constraint for multiple columns:
      *
      * ```ts
-     * addForeignKeyConstraint(
-     *   'owner_id_foreign',
-     *   ['owner_id1', 'owner_id2'],
-     *   'person',
-     *   ['id1', 'id2'],
-     *   (cb) => cb.onDelete('cascade')
-     * )
+     * await db.schema
+     *   .createTable('pet')
+     *   .addColumn('owner_id1', 'integer')
+     *   .addColumn('owner_id2', 'integer')
+     *   .addForeignKeyConstraint(
+     *     'owner_id_foreign',
+     *     ['owner_id1', 'owner_id2'],
+     *     'person',
+     *     ['id1', 'id2'],
+     *     (cb) => cb.onDelete('cascade')
+     *   )
+     *   .execute()
      * ```
      */
     addForeignKeyConstraint(constraintName: string, columns: C[], targetTable: string, targetColumns: string[], build?: ForeignKeyConstraintBuilderCallback): CreateTableBuilder<TB, C>;
@@ -165,11 +209,14 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      * ### Examples
      *
      * ```ts
-     * db.schema.createTable('person')
+     * import { sql } from 'kysely'
+     *
+     * await db.schema
+     *   .createTable('person')
      *   .modifyFront(sql`global temporary`)
      *   .addColumn('id', 'integer', col => col.primaryKey())
      *   .addColumn('first_name', 'varchar(64)', col => col.notNull())
-     *   .addColumn('last_name', 'varchar(64), col => col.notNull())
+     *   .addColumn('last_name', 'varchar(64)', col => col.notNull())
      *   .execute()
      * ```
      *
@@ -192,10 +239,13 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      * ### Examples
      *
      * ```ts
-     * db.schema.createTable('person')
-     *   .addColumn('id', 'integer', col => col => primaryKey())
+     * import { sql } from 'kysely'
+     *
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('id', 'integer', col => col.primaryKey())
      *   .addColumn('first_name', 'varchar(64)', col => col.notNull())
-     *   .addColumn('last_name', 'varchar(64), col => col.notNull())
+     *   .addColumn('last_name', 'varchar(64)', col => col.notNull())
      *   .modifyEnd(sql`collate utf8_unicode_ci`)
      *   .execute()
      * ```
@@ -217,7 +267,8 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      * ### Examples
      *
      * ```ts
-     * db.schema.createTable('copy')
+     * await db.schema
+     *   .createTable('copy')
      *   .temporary()
      *   .as(db.selectFrom('person').select(['first_name', 'last_name']))
      *   .execute()
@@ -237,17 +288,19 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      * ### Examples
      *
      * ```ts
-     * db.schema
+     * await db.schema
      *   .createTable('test')
      *   .$call((builder) => builder.addColumn('id', 'integer'))
      *   .execute()
      * ```
      *
+     * This is useful for creating reusable functions that can be called with a builder.
+     *
      * ```ts
-     * const addDefaultColumns = <T extends string, C extends string = never>(
-     *   builder: CreateTableBuilder<T, C>
-     * ) => {
-     *   return builder
+     * import { type CreateTableBuilder, sql } from 'kysely'
+     *
+     * const addDefaultColumns = (ctb: CreateTableBuilder<any, any>) => {
+     *   return ctb
      *     .addColumn('id', 'integer', (col) => col.notNull())
      *     .addColumn('created_at', 'date', (col) =>
      *       col.notNull().defaultTo(sql`now()`)
@@ -257,7 +310,7 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      *     )
      * }
      *
-     * db.schema
+     * await db.schema
      *   .createTable('test')
      *   .$call(addDefaultColumns)
      *   .execute()