kysely 0.8.1 → 0.9.0

package/README.md

@@ -4,7 +4,8 @@
 # [Kysely](https://koskimas.github.io/kysely/index.html)
 
 A type-safe and autocompletion-friendly typescript SQL query builder for node.js. Inspired by
-[knex](http://knexjs.org/). You can find an introduction to Kysely [here](https://www.jakso.me/blog/kysely-a-type-safe-sql-query-builder-for-typescript).
+[knex](http://knexjs.org/). [Here's](https://www.jakso.me/blog/kysely-a-type-safe-sql-query-builder-for-typescript)
+an introductory blog post for you.
 
 ![](https://github.com/koskimas/kysely/blob/master/assets/demo.gif)
 
@@ -25,7 +26,8 @@ type-safety! See the [DynamicModule](https://koskimas.github.io/kysely/classes/D
 for more info.
 
 Kysely is still young and some useful features are propably not yet implemented. If you start
-using Kysely and can't find something you'd want to use, please open an issue.
+using Kysely and can't find something you'd want to use, please open an issue or join our
+[discord server](https://discord.gg/C9aJ49mCra).
 
 # Table of contents
 
@@ -161,13 +163,15 @@ changes completely. Migrations need to be "frozen in time".
 The migrations can use the [Kysely.schema](https://koskimas.github.io/kysely/classes/SchemaModule.html)
 module to modify the schema. Migrations can also run normal queries to modify the data.
 
+### PostgreSQL migration example
+
 ```ts
 import { Kysely } from 'kysely'
 
 export async function up(db: Kysely<any>): Promise<void> {
   await db.schema
     .createTable('person')
-    .addColumn('id', 'integer', (col) => col.increments().primaryKey())
+    .addColumn('id', 'serial', (col) => col.primaryKey())
     .addColumn('first_name', 'varchar')
     .addColumn('last_name', 'varchar')
     .addColumn('gender', 'varchar(50)')
@@ -175,7 +179,7 @@ export async function up(db: Kysely<any>): Promise<void> {
 
   await db.schema
     .createTable('pet')
-    .addColumn('id', 'integer', (col) => col.increments().primaryKey())
+    .addColumn('id', 'serial', (col) => col.primaryKey())
     .addColumn('name', 'varchar', (col) => col.notNull().unique())
     .addColumn('owner_id', 'integer', (col) =>
       col.references('person.id').onDelete('cascade')
@@ -196,6 +200,45 @@ export async function down(db: Kysely<any>): Promise<void> {
 }
 ```
 
+### MySQL migration example
+
+```ts
+import { Kysely } from 'kysely'
+
+export async function up(db: Kysely<any>): Promise<void> {
+  await db.schema
+    .createTable('person')
+    .addColumn('id', 'integer', (col) => col.increments().primaryKey())
+    .addColumn('first_name', 'varchar')
+    .addColumn('last_name', 'varchar')
+    .addColumn('gender', 'varchar(50)')
+    .execute()
+
+  await db.schema
+    .createTable('pet')
+    .addColumn('id', 'integer', (col) => col.increments().primaryKey())
+    .addColumn('name', 'varchar', (col) => col.notNull().unique())
+    .addColumn('owner_id', 'integer')
+    .addColumn('species', 'varchar')
+    .addForeignKeyConstraint(
+      'pet_owner_id_fk', ['owner_id'], 'person', ['id'],
+      (cb) => cb.onDelete('cascade')
+    )
+    .execute()
+
+  await db.schema
+    .createIndex('pet_owner_id_index')
+    .on('pet')
+    .column('owner_id')
+    .execute()
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await db.schema.dropTable('pet').execute()
+  await db.schema.dropTable('person').execute()
+}
+```
+
 You can then use
 
 ```ts

package/dist/cjs/dialect/mysql/mysql-query-compiler.d.ts

@@ -1,7 +1,5 @@
-import { ColumnDefinitionNode } from '../../operation-node/column-definition-node.js';
 import { DefaultQueryCompiler } from '../../query-compiler/default-query-compiler.js';
 export declare class MysqlQueryCompiler extends DefaultQueryCompiler {
-    protected visitColumnDefinition(node: ColumnDefinitionNode): void;
     protected visitReturning(): void;
     protected getSql(): string;
     protected getCurrentParameterPlaceholder(): string;

package/dist/cjs/dialect/mysql/mysql-query-compiler.js

@@ -3,35 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MysqlQueryCompiler = void 0;
 const default_query_compiler_js_1 = require("../../query-compiler/default-query-compiler.js");
 class MysqlQueryCompiler extends default_query_compiler_js_1.DefaultQueryCompiler {
-    visitColumnDefinition(node) {
-        this.visitNode(node.column);
-        this.append(' ');
-        this.visitNode(node.dataType);
-        if (node.defaultTo) {
-            this.append(' default ');
-            this.visitNode(node.defaultTo);
-        }
-        if (!node.isNullable || node.isAutoIncrementing) {
-            this.append(' not null');
-        }
-        if (node.isAutoIncrementing) {
-            this.append(' auto_increment');
-        }
-        if (node.isUnique) {
-            this.append(' unique');
-        }
-        if (node.isPrimaryKey) {
-            this.append(' primary key');
-        }
-        if (node.references) {
-            this.append(' ');
-            this.visitNode(node.references);
-        }
-        if (node.check) {
-            this.append(' ');
-            this.visitNode(node.check);
-        }
-    }
     visitReturning() {
         // Do nothing.
     }

package/dist/cjs/operation-node/primitive-value-list-node.js

@@ -12,7 +12,7 @@ exports.PrimitiveValueListNode = (0, object_utils_js_1.freeze)({
     create(values) {
         return (0, object_utils_js_1.freeze)({
             kind: 'PrimitiveValueListNode',
-            values: (0, object_utils_js_1.freeze)(values),
+            values: (0, object_utils_js_1.freeze)([...values]),
         });
     },
 });

package/dist/cjs/parser/join-parser.d.ts

@@ -1,8 +1,11 @@
 import { JoinNode, JoinType } from '../operation-node/join-node.js';
 import { AnyColumn, AnyColumnWithTable } from '../util/type-utils.js';
-import { ExtractAliasFromTableExpression, TableExpressionDatabaseType } from './table-parser.js';
+import { ExtractAliasFromTableExpression, TableExpressionDatabase } from './table-parser.js';
 import { JoinBuilder } from '../query-builder/join-builder.js';
 import { ParseContext } from './parse-context.js';
-export declare type JoinReferenceExpression<DB, TB extends keyof DB, F> = AnyColumn<TableExpressionDatabaseType<DB, F>, TB | ExtractAliasFromTableExpression<DB, F>> | AnyColumnWithTable<TableExpressionDatabaseType<DB, F>, TB | ExtractAliasFromTableExpression<DB, F>>;
-export declare type JoinCallbackExpression<DB, TB extends keyof DB, F> = (join: JoinBuilder<TableExpressionDatabaseType<DB, F>, TB | ExtractAliasFromTableExpression<DB, F>>) => JoinBuilder<any, any>;
+export declare type JoinReferenceExpression<DB, TB extends keyof DB, F> = AnyJoinColumn<DB, TB, F> | AnyJoinColumnWithTable<DB, TB, F>;
+export declare type JoinCallbackExpression<DB, TB extends keyof DB, F> = (join: JoinBuilder<TableExpressionDatabase<DB, F>, TB | ExtractAliasFromTableExpression<DB, F>>) => JoinBuilder<any, any>;
+declare type AnyJoinColumn<DB, TB extends keyof DB, F> = AnyColumn<TableExpressionDatabase<DB, F>, TB | ExtractAliasFromTableExpression<DB, F>>;
+declare type AnyJoinColumnWithTable<DB, TB extends keyof DB, F> = AnyColumnWithTable<TableExpressionDatabase<DB, F>, TB | ExtractAliasFromTableExpression<DB, F>>;
 export declare function parseJoin(ctx: ParseContext, joinType: JoinType, args: any[]): JoinNode;
+export {};

package/dist/cjs/parser/table-parser.d.ts

@@ -7,20 +7,20 @@ import { ParseContext } from './parse-context.js';
 export declare type TableExpression<DB, TB extends keyof DB> = TableReference<DB> | AnyAliasedQueryBuilder | AliasedQueryBuilderFactory<DB, TB>;
 export declare type TableExpressionOrList<DB, TB extends keyof DB> = TableExpression<DB, TB> | ReadonlyArray<TableExpression<DB, TB>>;
 export declare type TableReference<DB> = AnyAliasedTable<DB, any, any> | AnyTable<DB> | AnyAliasedRawBuilder;
-export declare type QueryBuilderWithTable<DB, TB extends keyof DB, O, TE> = QueryBuilder<TableExpressionDatabaseType<DB, TE>, TB | ExtractAliasFromTableExpression<DB, TE>, O>;
-export declare type TableExpressionDatabaseType<DB, TE, A extends keyof any = ExtractAliasFromTableExpression<DB, TE>> = {
+export declare type QueryBuilderWithTable<DB, TB extends keyof DB, O, TE> = QueryBuilder<TableExpressionDatabase<DB, TE>, TB | ExtractAliasFromTableExpression<DB, TE>, O>;
+export declare type TableExpressionDatabase<DB, TE, A extends keyof any = ExtractAliasFromTableExpression<DB, TE>> = {
     [C in keyof DB | A]: C extends A ? ExtractRowTypeFromTableExpression<DB, TE, C> : C extends keyof DB ? DB[C] : never;
 };
-export declare type QueryBuilderWithLeftJoin<DB, TB extends keyof DB, O, TE> = QueryBuilder<LeftJoinTableExpressionDatabaseType<DB, TE>, TB | ExtractAliasFromTableExpression<DB, TE>, O>;
-export declare type LeftJoinTableExpressionDatabaseType<DB, TE, A extends keyof any = ExtractAliasFromTableExpression<DB, TE>> = {
+export declare type QueryBuilderWithLeftJoin<DB, TB extends keyof DB, O, TE> = QueryBuilder<LeftJoinTableExpressionDatabase<DB, TE>, TB | ExtractAliasFromTableExpression<DB, TE>, O>;
+export declare type LeftJoinTableExpressionDatabase<DB, TE, A extends keyof any = ExtractAliasFromTableExpression<DB, TE>> = {
     [C in keyof DB | A]: C extends A ? Nullable<ExtractRowTypeFromTableExpression<DB, TE, C>> : C extends keyof DB ? DB[C] : never;
 };
-export declare type QueryBuilderWithRightJoin<DB, TB extends keyof DB, O, TE> = QueryBuilder<RightJoinTableExpressionDatabaseType<DB, TB, TE>, TB | ExtractAliasFromTableExpression<DB, TE>, O>;
-export declare type RightJoinTableExpressionDatabaseType<DB, TB extends keyof DB, TE, A extends keyof any = ExtractAliasFromTableExpression<DB, TE>> = {
+export declare type QueryBuilderWithRightJoin<DB, TB extends keyof DB, O, TE> = QueryBuilder<RightJoinTableExpressionDatabase<DB, TB, TE>, TB | ExtractAliasFromTableExpression<DB, TE>, O>;
+export declare type RightJoinTableExpressionDatabase<DB, TB extends keyof DB, TE, A extends keyof any = ExtractAliasFromTableExpression<DB, TE>> = {
     [C in keyof DB | A]: C extends A ? ExtractRowTypeFromTableExpression<DB, TE, C> : C extends keyof DB ? C extends TB ? Nullable<DB[C]> : DB[C] : never;
 };
-export declare type QueryBuilderWithFullJoin<DB, TB extends keyof DB, O, TE> = QueryBuilder<FullJoinTableExpressionDatabaseType<DB, TB, TE>, TB | ExtractAliasFromTableExpression<DB, TE>, O>;
-export declare type FullJoinTableExpressionDatabaseType<DB, TB extends keyof DB, TE, A extends keyof any = ExtractAliasFromTableExpression<DB, TE>> = {
+export declare type QueryBuilderWithFullJoin<DB, TB extends keyof DB, O, TE> = QueryBuilder<FullJoinTableExpressionDatabase<DB, TB, TE>, TB | ExtractAliasFromTableExpression<DB, TE>, O>;
+export declare type FullJoinTableExpressionDatabase<DB, TB extends keyof DB, TE, A extends keyof any = ExtractAliasFromTableExpression<DB, TE>> = {
     [C in keyof DB | A]: C extends A ? Nullable<ExtractRowTypeFromTableExpression<DB, TE, C>> : C extends keyof DB ? C extends TB ? Nullable<DB[C]> : DB[C] : never;
 };
 export declare type ExtractAliasFromTableExpression<DB, TE> = TE extends `${string} as ${infer TA}` ? TA : TE extends keyof DB ? TE : TE extends AliasedQueryBuilder<any, any, any, infer QA> ? QA : TE extends (qb: any) => AliasedQueryBuilder<any, any, any, infer QA> ? QA : TE extends AliasedRawBuilder<any, infer RA> ? RA : TE extends (qb: any) => AliasedRawBuilder<any, infer RA> ? RA : never;

package/dist/cjs/query-builder/function-builder.d.ts

@@ -66,9 +66,9 @@ export declare class FunctionBuilder<DB, TB extends keyof DB> {
      * Calls the `sum` function for the column given as the argument.
      *
      * If this is used in a `select` statement the type of the selected expression
-     * will be `number | string` by default. This is because Kysely can't know the
-     * type the db driver outputs. Sometimes the output can be larger than the
-     * largest javascript number and a string is returned instead. Most drivers
+     * will be `number | string | BigInt` by default. This is because Kysely can't
+     * know the type the db driver outputs. Sometimes the output can be larger than
+     * the largest javascript number and a string is returned instead. Most drivers
      * allow you to configure the output type of large numbers and Kysely can't
      * know if you've done so.
      *
@@ -88,9 +88,9 @@ export declare class FunctionBuilder<DB, TB extends keyof DB> {
      * Calls the `count` function for the column given as the argument.
      *
      * If this is used in a `select` statement the type of the selected expression
-     * will be `number | string` by default. This is because Kysely can't know the
-     * type the db driver outputs. Sometimes the output can be larger than the
-     * largest javascript number and a string is returned instead. Most drivers
+     * will be `number | string | BigInt` by default. This is because Kysely can't
+     * know the type the db driver outputs. Sometimes the output can be larger than
+     * the largest javascript number and a string is returned instead. Most drivers
      * allow you to configure the output type of large numbers and Kysely can't
      * know if you've done so.
      *

package/dist/cjs/query-builder/function-builder.js

@@ -82,9 +82,9 @@ class FunctionBuilder {
      * Calls the `sum` function for the column given as the argument.
      *
      * If this is used in a `select` statement the type of the selected expression
-     * will be `number | string` by default. This is because Kysely can't know the
-     * type the db driver outputs. Sometimes the output can be larger than the
-     * largest javascript number and a string is returned instead. Most drivers
+     * will be `number | string | BigInt` by default. This is because Kysely can't
+     * know the type the db driver outputs. Sometimes the output can be larger than
+     * the largest javascript number and a string is returned instead. Most drivers
      * allow you to configure the output type of large numbers and Kysely can't
      * know if you've done so.
      *
@@ -106,9 +106,9 @@ class FunctionBuilder {
      * Calls the `count` function for the column given as the argument.
      *
      * If this is used in a `select` statement the type of the selected expression
-     * will be `number | string` by default. This is because Kysely can't know the
-     * type the db driver outputs. Sometimes the output can be larger than the
-     * largest javascript number and a string is returned instead. Most drivers
+     * will be `number | string | BigInt` by default. This is because Kysely can't
+     * know the type the db driver outputs. Sometimes the output can be larger than
+     * the largest javascript number and a string is returned instead. Most drivers
      * allow you to configure the output type of large numbers and Kysely can't
      * know if you've done so.
      *

package/dist/cjs/query-compiler/default-query-compiler.d.ts

@@ -92,6 +92,7 @@ export declare class DefaultQueryCompiler extends OperationNodeVisitor implement
     protected visitTable(node: TableNode): void;
     protected visitCreateTable(node: CreateTableNode): void;
     protected visitColumnDefinition(node: ColumnDefinitionNode): void;
+    protected getAutoIncrement(): string;
     protected visitReferences(node: ReferencesNode): void;
     protected visitDropTable(node: DropTableNode): void;
     protected visitDataType(node: DataTypeNode): void;

package/dist/cjs/query-compiler/default-query-compiler.js

@@ -1,19 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DefaultQueryCompiler = void 0;
-const data_type_node_js_1 = require("../operation-node/data-type-node.js");
 const operation_node_visitor_js_1 = require("../operation-node/operation-node-visitor.js");
 const query_node_js_1 = require("../operation-node/query-node.js");
 const raw_node_js_1 = require("../operation-node/raw-node.js");
 const object_utils_js_1 = require("../util/object-utils.js");
 class DefaultQueryCompiler extends operation_node_visitor_js_1.OperationNodeVisitor {
-    #sqlFragments = [];
+    #sql = '';
     #parameters = [];
     get numParameters() {
         return this.#parameters.length;
     }
     compileQuery(node) {
-        this.#sqlFragments = [];
+        this.#sql = '';
         this.#parameters = [];
         this.visitNode(node);
         return (0, object_utils_js_1.freeze)({
@@ -22,7 +21,7 @@ class DefaultQueryCompiler extends operation_node_visitor_js_1.OperationNodeVisi
         });
     }
     getSql() {
-        return this.#sqlFragments.join('');
+        return this.#sql;
     }
     visitSelectQuery(node) {
         // This is a sub query if this is not the root node.
@@ -292,19 +291,7 @@ class DefaultQueryCompiler extends operation_node_visitor_js_1.OperationNodeVisi
     visitColumnDefinition(node) {
         this.visitNode(node.column);
         this.append(' ');
-        if (node.isAutoIncrementing) {
-            // Postgres overrides the data type for autoincrementing columns.
-            if (data_type_node_js_1.DataTypeNode.is(node.dataType) &&
-                node.dataType.dataType === 'bigint') {
-                this.append('bigserial');
-            }
-            else {
-                this.append('serial');
-            }
-        }
-        else {
-            this.visitNode(node.dataType);
-        }
+        this.visitNode(node.dataType);
         if (node.defaultTo) {
             this.append(' default ');
             this.visitNode(node.defaultTo);
@@ -312,6 +299,10 @@ class DefaultQueryCompiler extends operation_node_visitor_js_1.OperationNodeVisi
         if (!node.isNullable) {
             this.append(' not null');
         }
+        if (node.isAutoIncrementing) {
+            this.append(' ');
+            this.append(this.getAutoIncrement());
+        }
         if (node.isUnique) {
             this.append(' unique');
         }
@@ -327,6 +318,9 @@ class DefaultQueryCompiler extends operation_node_visitor_js_1.OperationNodeVisi
             this.visitNode(node.check);
         }
     }
+    getAutoIncrement() {
+        return 'auto_increment';
+    }
     visitReferences(node) {
         this.append('references ');
         this.visitNode(node.table);
@@ -637,7 +631,7 @@ class DefaultQueryCompiler extends operation_node_visitor_js_1.OperationNodeVisi
         this.visitNode(node.constraintName);
     }
     append(str) {
-        this.#sqlFragments.push(str);
+        this.#sql += str;
     }
     appendValue(value) {
         this.addParameter(value);

package/dist/cjs/query-creator.d.ts

@@ -10,7 +10,7 @@ export declare class QueryCreator<DB> {
     #private;
     constructor(props: QueryCreatorProps);
     /**
-     * Creates a `select` query builder against the given table/tables.
+     * Creates a `select` query builder for the given table or tables.
      *
      * The tables passed to this method are built as the query's `from` clause.
      *
@@ -221,6 +221,9 @@ export declare class QueryCreator<DB> {
      * Sets the schema to be used for all table references that don't explicitly
      * specify a schema.
      *
+     * This only affects the query created through the builder returned from
+     * this method and doesn't modify the `db` instance.
+     *
      * @example
      * ```
      * await db.withSchema('mammals')
@@ -261,10 +264,10 @@ export declare class QueryCreator<DB> {
      * Provides a way to pass arbitrary SQL into your query and executing completely
      * raw queries.
      *
-     * You can use strings `?` and `??` in the `sql` to bind parameters such as
+     * You can use the strings `?` and `??` in the `sql` to bind parameters such as
      * user input to the SQL. You should never EVER concatenate untrusted user
      * input to the SQL string to avoid injection vulnerabilities. Instead use `?`
-     * in place of the value and pass the actual value in the `params` list. See
+     * in place of a value and pass the actual value in the `parameters` list. See
      * the examples below.
      *
      * You should only use `raw` when there is no other way to get the job done. This is

package/dist/cjs/query-creator.js

@@ -158,6 +158,9 @@ class QueryCreator {
      * Sets the schema to be used for all table references that don't explicitly
      * specify a schema.
      *
+     * This only affects the query created through the builder returned from
+     * this method and doesn't modify the `db` instance.
+     *
      * @example
      * ```
      * await db.withSchema('mammals')
@@ -203,10 +206,10 @@ class QueryCreator {
      * Provides a way to pass arbitrary SQL into your query and executing completely
      * raw queries.
      *
-     * You can use strings `?` and `??` in the `sql` to bind parameters such as
+     * You can use the strings `?` and `??` in the `sql` to bind parameters such as
      * user input to the SQL. You should never EVER concatenate untrusted user
      * input to the SQL string to avoid injection vulnerabilities. Instead use `?`
-     * in place of the value and pass the actual value in the `params` list. See
+     * in place of a value and pass the actual value in the `parameters` list. See
      * the examples below.
      *
      * You should only use `raw` when there is no other way to get the job done. This is

package/dist/cjs/schema/alter-table-builder.d.ts

@@ -12,6 +12,9 @@ import { QueryId } from '../util/query-id.js';
 import { QueryExecutor } from '../query-executor/query-executor.js';
 import { DataTypeExpression } from '../parser/data-type-parser.js';
 import { ForeignKeyConstraintBuilder, ForeignKeyConstraintBuilderInterface } from './foreign-key-constraint-builder.js';
+/**
+ * This builder can be used to create a `alter table` query.
+ */
 export declare class AlterTableBuilder {
     #private;
     constructor(props: AlterTableBuilderProps);

package/dist/cjs/schema/alter-table-builder.js

@@ -23,6 +23,9 @@ const unique_constraint_node_js_1 = require("../operation-node/unique-constraint
 const check_constraint_node_js_1 = require("../operation-node/check-constraint-node.js");
 const foreign_key_constraint_node_js_1 = require("../operation-node/foreign-key-constraint-node.js");
 const column_node_js_1 = require("../operation-node/column-node.js");
+/**
+ * This builder can be used to create a `alter table` query.
+ */
 class AlterTableBuilder {
     #props;
     constructor(props) {

package/dist/cjs/schema/column-definition-builder.d.ts

@@ -6,11 +6,11 @@ import { AnyRawBuilder } from '../util/type-utils.js';
 import { DefaultValueExpression } from '../parser/default-value-parser.js';
 export interface ColumnDefinitionBuilderInterface<R> {
     /**
-     * Makes the column automatically incrementing.
+     * Adds `auto_increment` or `autoincrement` to the column definition
+     * depending on the dialect.
      *
-     * On some dialects this may change the column type as well. For example
-     * on postgres this sets the column type to `serial` no matter what you
-     * have specified before.
+     * Some dialects like PostgreSQL don't support this. On PostgreSQL
+     * you can use the `serial` or `bigserial` data type instead.
      */
     increments(): R;
     /**
@@ -23,6 +23,10 @@ export interface ColumnDefinitionBuilderInterface<R> {
     /**
      * Adds a foreign key constraint for the 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 TableBuilder.addForeignKeyConstraint} method instead.
+     *
      * @example
      * ```ts
      * col.references('person.id')
@@ -31,6 +35,11 @@ export interface ColumnDefinitionBuilderInterface<R> {
     references(ref: string): R;
     /**
      * Adds an `on delete` 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 TableBuilder.addForeignKeyConstraint} method instead.
+     *
      */
     onDelete(onDelete: OnModifyForeignAction): R;
     /**
@@ -64,7 +73,7 @@ export interface ColumnDefinitionBuilderInterface<R> {
      * ```ts
      * db.schema
      *   .createTable('pet')
-     *   .addColumn('number_of_legs', (col) => col.check('number_of_legs < 5', 'integer'))
+     *   .addColumn('number_of_legs', 'integer', (col) => col.check('number_of_legs < 5'))
      *   .execute()
      * ```
      */

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

@@ -7,7 +7,10 @@ import { ColumnDefinitionBuilder } from './column-definition-builder.js';
 import { QueryId } from '../util/query-id.js';
 import { ForeignKeyConstraintBuilder } from './foreign-key-constraint-builder.js';
 import { DataTypeExpression } from '../parser/data-type-parser.js';
-export declare class CreateTableBuilder implements OperationNodeSource, Compilable {
+/**
+ * This builder can be used to create a `create table` query.
+ */
+export declare class CreateTableBuilder<TB extends string, C extends string = never> implements OperationNodeSource, Compilable {
     #private;
     constructor(props: CreateTableBuilderProps);
     /**
@@ -15,7 +18,7 @@ export declare class CreateTableBuilder implements OperationNodeSource, Compilab
      *
      * If the table already exists, no error is thrown if this method has been called.
      */
-    ifNotExists(): CreateTableBuilder;
+    ifNotExists(): CreateTableBuilder<TB, C>;
     /**
      * Adds a column to the table.
      *
@@ -23,44 +26,86 @@ export declare class CreateTableBuilder implements OperationNodeSource, Compilab
      * ```ts
      * await db.schema
      *   .createTable('person')
-     *   .addColumn('int', 'id', (col) => col.increments().primary()),
+     *   .addColumn('id', 'integer', (col) => col.increments().primaryKey()),
      *   .addColumn('first_name', 'varchar(50), (col) => col.notNull())
-     *   .addColumn('varchar', 'last_name')
-     *   .addColumn('numeric(8, 2)', 'bank_balance')
+     *   .addColumn('last_name', 'varchar')
+     *   .addColumn('bank_balance', 'numeric(8, 2)')
      *   .addColumn('data', db.raw('customtype'))
+     *   .addColumn('parent_id', 'integer', (col) =>
+     *     col.references('person.id').onDelete('cascade'))
+     *   )
+     * ```
+     *
+     * With this method, it's once again good to remember that Kysely just builds the query
+     * that's as close to the structure of your builder method calls as possible, and doesn't
+     * provide the same API for all databses. For example, some databases like older MySQL
+     * don't support `references` statement in the column definition. Instead foreign key
+     * constraints need to be defined in at the level of the `create table` query. See
+     * the next example:
+     *
+     * @example
+     * ```ts
+     *   .addColumn('parent_id', 'integer')
+     *   .addForeignKeyConstraint(
+     *     'person_parent_id_fk', ['parent_id'], 'person', ['id'],
+     *     (cb) => cb.onDelete('cascade')
+     *   )
+     * ```
+     *
+     * Another good example is that PostgreSQL doesn't support the `auto_increment`
+     * keyword and you need to define an autoincrementing column for example using
+     * `serial`:
+     *
+     * @example
+     * ```ts
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('id', 'serial', (col) => col.primaryKey()),
      * ```
      */
-    addColumn(columnName: string, dataType: DataTypeExpression, build?: ColumnBuilderCallback): CreateTableBuilder;
+    addColumn<CN extends string>(columnName: CN, dataType: DataTypeExpression, build?: ColumnBuilderCallback): CreateTableBuilder<TB, C | CN>;
     /**
      * Adds a primary key constraint for one or more columns.
      *
+     * The constraint name can be anything you want, but it must be unique
+     * across the whole database.
+     *
      * @example
      * ```ts
      * addPrimaryKeyConstraint('primary_key', ['first_name', 'last_name'])
      * ```
      */
-    addPrimaryKeyConstraint(constraintName: string, columns: string[]): CreateTableBuilder;
+    addPrimaryKeyConstraint(constraintName: string, columns: C[]): CreateTableBuilder<TB, C>;
     /**
      * Adds a unique constraint for one or more columns.
      *
+     * The constraint name can be anything you want, but it must be unique
+     * across the whole database.
+     *
      * @example
      * ```ts
      * addUniqueConstraint('first_name_last_name_unique', ['first_name', 'last_name'])
      * ```
      */
-    addUniqueConstraint(constraintName: string, columns: string[]): CreateTableBuilder;
+    addUniqueConstraint(constraintName: string, columns: C[]): CreateTableBuilder<TB, C>;
     /**
      * Adds a check constraint.
      *
+     * The constraint name can be anything you want, but it must be unique
+     * across the whole database.
+     *
      * @example
      * ```ts
      * addCheckConstraint('check_legs', 'number_of_legs < 5')
      * ```
      */
-    addCheckConstraint(constraintName: string, checkExpression: string): CreateTableBuilder;
+    addCheckConstraint(constraintName: string, checkExpression: string): CreateTableBuilder<TB, C>;
     /**
      * Adds a foreign key constraint.
      *
+     * The constraint name can be anything you want, but it must be unique
+     * across the whole database.
+     *
      * @example
      * ```ts
      * addForeignKeyConstraint(
@@ -82,7 +127,7 @@ export declare class CreateTableBuilder implements OperationNodeSource, Compilab
      * )
      * ```
      */
-    addForeignKeyConstraint(constraintName: string, columns: string[], targetTable: string, targetColumns: string[], build?: ForeignKeyConstraintBuilderCallback): CreateTableBuilder;
+    addForeignKeyConstraint(constraintName: string, columns: C[], targetTable: string, targetColumns: string[], build?: ForeignKeyConstraintBuilderCallback): CreateTableBuilder<TB, C>;
     toOperationNode(): CreateTableNode;
     compile(): CompiledQuery;
     execute(): Promise<void>;