kysely 0.7.9 → 0.9.1

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
@@ -276,11 +279,11 @@ export declare class QueryCreator<DB> {
      * Raw builder instances can be passed to pretty much anywhere: `select`, `where`,
      * `*Join`, `groupBy`, `orderBy` etc. Just try it. If the method accepts it, it works.
      *
-     * @param sql - The raw SQL. Special strings `?` and `??` can be used to provide
-     *    parameter bindings. `?` for values and `??` for identifiers such as column names
+     * @param sql - The raw SQL. Special strings `?` and `??` can be used as parameter
+     *    placeholders. `?` for values and `??` for identifiers such as column names
      *    or `column.table` references.
      *
-     * @param params - The parameters that will be bound to the `?` and `??` bindings in
+     * @param params - The parameters that will be bound to the `?` and `??` placeholders in
      *    the sql string.
      *
      * @example
@@ -318,7 +321,7 @@ export declare class QueryCreator<DB> {
      *     the output type. In this case you need to use the `castTo` method on the query
      *     to specify a return type for the query.
      *
-     * We could've also used `??` bindings to provide `first_name` and `last_name` like
+     * We could've also used a `??` placeholder to provide `first_name` and `last_name` like
      * this:
      *
      * ```ts
@@ -333,9 +336,9 @@ export declare class QueryCreator<DB> {
      *
      * But it's often cleaner to just write the column names in the SQL. Again remember to
      * never concatenate column names or any other untrusted user input to the SQL string or you
-     * are going to create an injection vulnerability. All user input should go to the bindings
+     * are going to create an injection vulnerability. All user input should go to the parameters
      * array, never to the SQL string directly. But if the column names or values are trusted
-     * and known at compile time, there is no reason to use bindings.
+     * and known at compile time, there is no reason to use parameters.
      *
      * @example
      * Example of using `raw` in `where`:
@@ -361,7 +364,7 @@ export declare class QueryCreator<DB> {
      *
      * The function in the above example returns people that are older than the given number of
      * years. The number of years in this example is an untrusted user input, and therefore we use
-     * a `?` binding for it.
+     * a `?` placeholder for it.
      *
      * @example
      * Example of creating a completely raw query from scratch:
@@ -375,7 +378,7 @@ export declare class QueryCreator<DB> {
      * The result of `execute()` method is always an array. In this case the type of
      * the `persons` variable is `Person[]`.
      */
-    raw<T = unknown>(sql: string, params?: any[]): RawBuilder<T>;
+    raw<T = unknown>(sql: string, parameters?: any[]): RawBuilder<T>;
 }
 export interface QueryCreatorProps {
     readonly executor: QueryExecutor;

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
@@ -218,11 +221,11 @@ class QueryCreator {
      * Raw builder instances can be passed to pretty much anywhere: `select`, `where`,
      * `*Join`, `groupBy`, `orderBy` etc. Just try it. If the method accepts it, it works.
      *
-     * @param sql - The raw SQL. Special strings `?` and `??` can be used to provide
-     *    parameter bindings. `?` for values and `??` for identifiers such as column names
+     * @param sql - The raw SQL. Special strings `?` and `??` can be used as parameter
+     *    placeholders. `?` for values and `??` for identifiers such as column names
      *    or `column.table` references.
      *
-     * @param params - The parameters that will be bound to the `?` and `??` bindings in
+     * @param params - The parameters that will be bound to the `?` and `??` placeholders in
      *    the sql string.
      *
      * @example
@@ -260,7 +263,7 @@ class QueryCreator {
      *     the output type. In this case you need to use the `castTo` method on the query
      *     to specify a return type for the query.
      *
-     * We could've also used `??` bindings to provide `first_name` and `last_name` like
+     * We could've also used a `??` placeholder to provide `first_name` and `last_name` like
      * this:
      *
      * ```ts
@@ -275,9 +278,9 @@ class QueryCreator {
      *
      * But it's often cleaner to just write the column names in the SQL. Again remember to
      * never concatenate column names or any other untrusted user input to the SQL string or you
-     * are going to create an injection vulnerability. All user input should go to the bindings
+     * are going to create an injection vulnerability. All user input should go to the parameters
      * array, never to the SQL string directly. But if the column names or values are trusted
-     * and known at compile time, there is no reason to use bindings.
+     * and known at compile time, there is no reason to use parameters.
      *
      * @example
      * Example of using `raw` in `where`:
@@ -303,7 +306,7 @@ class QueryCreator {
      *
      * The function in the above example returns people that are older than the given number of
      * years. The number of years in this example is an untrusted user input, and therefore we use
-     * a `?` binding for it.
+     * a `?` placeholder for it.
      *
      * @example
      * Example of creating a completely raw query from scratch:
@@ -317,12 +320,12 @@ class QueryCreator {
      * The result of `execute()` method is always an array. In this case the type of
      * the `persons` variable is `Person[]`.
      */
-    raw(sql, params) {
+    raw(sql, parameters) {
         return new raw_builder_js_1.RawBuilder({
             queryId: (0, query_id_js_1.createQueryId)(),
             executor: this.#props.executor,
             sql,
-            params,
+            parameters,
         });
     }
 }

package/dist/cjs/raw-builder/raw-builder.d.ts

@@ -41,5 +41,5 @@ export interface RawBuilderProps {
     readonly queryId: QueryId;
     readonly executor: QueryExecutor;
     readonly sql: string;
-    readonly params?: any;
+    readonly parameters?: any;
 }

package/dist/cjs/raw-builder/raw-builder.js

@@ -28,24 +28,24 @@ class RawBuilder {
         });
     }
     toOperationNode() {
-        const bindingRegex = /(\?\??)/g;
+        const parameterPlaceholderRegex = /(\?\??)/g;
         const sql = this.#props.sql;
-        const params = this.#props.params ?? [];
+        const parameters = this.#props.parameters ?? [];
         const sqlFragments = [];
         const argNodes = [];
         let paramIdx = 0;
         let sqlIdx = 0;
         let match = null;
-        while ((match = bindingRegex.exec(sql))) {
+        while ((match = parameterPlaceholderRegex.exec(sql))) {
             const str = match[1];
-            if (paramIdx >= params.length) {
-                throw new Error(`value not provided for all bindings in string ${sql}`);
+            if (paramIdx >= parameters.length) {
+                throw new Error(`value not provided for all placeholders in string ${sql}`);
             }
             if (match.index > 0 && sql[match.index - 1] === '\\') {
                 continue;
             }
             sqlFragments.push(sql.slice(sqlIdx, match.index).replaceAll('\\?', '?'));
-            argNodes.push(parseRawArg(str, params[paramIdx]));
+            argNodes.push(parseRawArg(str, parameters[paramIdx]));
             sqlIdx = match.index + str.length;
             ++paramIdx;
         }

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-schema-builder.js

@@ -12,7 +12,7 @@ class CreateSchemaBuilder {
     ifNotExists() {
         return new CreateSchemaBuilder({
             ...this.#props,
-            createSchemaNode: create_schema_node_js_1.CreateSchemaNode.cloneWithModifier(this.#props.createSchemaNode, 'IfNotExists'),
+            createSchemaNode: create_schema_node_js_1.CreateSchemaNode.cloneWith(this.#props.createSchemaNode, { modifier: 'IfNotExists' }),
         });
     }
     toOperationNode() {

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>;

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

@@ -11,6 +11,12 @@ const column_node_js_1 = require("../operation-node/column-node.js");
 const table_node_js_1 = require("../operation-node/table-node.js");
 const foreign_key_constraint_builder_js_1 = require("./foreign-key-constraint-builder.js");
 const data_type_parser_js_1 = require("../parser/data-type-parser.js");
+const primary_constraint_node_js_1 = require("../operation-node/primary-constraint-node.js");
+const unique_constraint_node_js_1 = require("../operation-node/unique-constraint-node.js");
+const check_constraint_node_js_1 = require("../operation-node/check-constraint-node.js");
+/**
+ * This builder can be used to create a `create table` query.
+ */
 class CreateTableBuilder {
     #props;
     constructor(props) {
@@ -34,18 +40,45 @@ class CreateTableBuilder {
      * ```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, dataType, build) {
-        let columnBuilder = new column_definition_builder_js_1.ColumnDefinitionBuilder(column_definition_node_js_1.ColumnDefinitionNode.create(columnName, (0, data_type_parser_js_1.parseDataTypeExpression)(dataType)));
-        if (build) {
-            columnBuilder = build(columnBuilder);
-        }
+    addColumn(columnName, dataType, build = object_utils_js_1.noop) {
+        const columnBuilder = build(new column_definition_builder_js_1.ColumnDefinitionBuilder(column_definition_node_js_1.ColumnDefinitionNode.create(columnName, (0, data_type_parser_js_1.parseDataTypeExpression)(dataType))));
         return new CreateTableBuilder({
             ...this.#props,
             createTableNode: create_table_node_js_1.CreateTableNode.cloneWithColumn(this.#props.createTableNode, columnBuilder.toOperationNode()),
@@ -54,6 +87,9 @@ class CreateTableBuilder {
     /**
      * 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'])
@@ -62,12 +98,15 @@ class CreateTableBuilder {
     addPrimaryKeyConstraint(constraintName, columns) {
         return new CreateTableBuilder({
             ...this.#props,
-            createTableNode: create_table_node_js_1.CreateTableNode.cloneWithPrimaryKeyConstraint(this.#props.createTableNode, constraintName, columns),
+            createTableNode: create_table_node_js_1.CreateTableNode.cloneWithConstraint(this.#props.createTableNode, primary_constraint_node_js_1.PrimaryConstraintNode.create(columns, constraintName)),
         });
     }
     /**
      * 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'])
@@ -76,12 +115,15 @@ class CreateTableBuilder {
     addUniqueConstraint(constraintName, columns) {
         return new CreateTableBuilder({
             ...this.#props,
-            createTableNode: create_table_node_js_1.CreateTableNode.cloneWithUniqueConstraint(this.#props.createTableNode, constraintName, columns),
+            createTableNode: create_table_node_js_1.CreateTableNode.cloneWithConstraint(this.#props.createTableNode, unique_constraint_node_js_1.UniqueConstraintNode.create(columns, constraintName)),
         });
     }
     /**
      * 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')
@@ -90,12 +132,15 @@ class CreateTableBuilder {
     addCheckConstraint(constraintName, checkExpression) {
         return new CreateTableBuilder({
             ...this.#props,
-            createTableNode: create_table_node_js_1.CreateTableNode.cloneWithCheckConstraint(this.#props.createTableNode, constraintName, checkExpression),
+            createTableNode: create_table_node_js_1.CreateTableNode.cloneWithConstraint(this.#props.createTableNode, check_constraint_node_js_1.CheckConstraintNode.create(checkExpression, constraintName)),
         });
     }
     /**
      * 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(
@@ -117,14 +162,11 @@ class CreateTableBuilder {
      * )
      * ```
      */
-    addForeignKeyConstraint(constraintName, columns, targetTable, targetColumns, build) {
-        let builder = new foreign_key_constraint_builder_js_1.ForeignKeyConstraintBuilder(foreign_key_constraint_node_js_1.ForeignKeyConstraintNode.create(columns.map(column_node_js_1.ColumnNode.create), table_node_js_1.TableNode.create(targetTable), targetColumns.map(column_node_js_1.ColumnNode.create), constraintName));
-        if (build) {
-            builder = build(builder);
-        }
+    addForeignKeyConstraint(constraintName, columns, targetTable, targetColumns, build = object_utils_js_1.noop) {
+        const builder = build(new foreign_key_constraint_builder_js_1.ForeignKeyConstraintBuilder(foreign_key_constraint_node_js_1.ForeignKeyConstraintNode.create(columns.map(column_node_js_1.ColumnNode.create), table_node_js_1.TableNode.create(targetTable), targetColumns.map(column_node_js_1.ColumnNode.create), constraintName)));
         return new CreateTableBuilder({
             ...this.#props,
-            createTableNode: create_table_node_js_1.CreateTableNode.cloneWithForeignKeyConstraint(this.#props.createTableNode, builder.toOperationNode()),
+            createTableNode: create_table_node_js_1.CreateTableNode.cloneWithConstraint(this.#props.createTableNode, builder.toOperationNode()),
         });
     }
     toOperationNode() {

package/dist/cjs/schema/schema.d.ts

@@ -22,14 +22,49 @@ export declare class SchemaModule {
      * ```ts
      * await db.schema
      *   .createTable('person')
-     *   .addColumn('id', 'int', col => col.primaryKey().increments())
+     *   .addColumn('id', 'integer', col => col.primaryKey().increments())
      *   .addColumn('first_name', 'varchar', col => col.notNull())
      *   .addColumn('last_name', 'varchar', col => col.notNull())
      *   .addColumn('gender', 'varchar')
      *   .execute()
      * ```
+     *
+     * @example
+     * This example creates a table with a foreign key. Not all database
+     * engines support column-level foreign key constraint definitions.
+     * For example if you are using MySQL 5.X see the next example after
+     * this one.
+     *
+     * ```ts
+     * await db.schema
+     *   .createTable('pet')
+     *   .addColumn('id', 'integer', col => col.primaryKey().increments())
+     *   .addColumn('owner_id', 'integer', col => col
+     *     .references('person.id')
+     *     .onDelete('cascade')
+     *   )
+     *   .execute()
+     * ```
+     *
+     * @example
+     * This example adds a foreign key constraint for a columns just
+     * like the previous example, but using a table-level statement.
+     * On MySQL 5.X you need to define foreign key constraints like
+     * this:
+     *
+     * ```ts
+     * await db.schema
+     *   .createTable('pet')
+     *   .addColumn('id', 'integer', col => col.primaryKey().increments())
+     *   .addColumn('owner_id', 'integer')
+     *   .addForeignKeyConstraint(
+     *     'pet_owner_id_foreign', ['owner_id'], 'person', ['id'],
+     *     (constraint) => constraint.onDelete('cascade')
+     *   )
+     *   .execute()
+     * ```
      */
-    createTable(table: string): CreateTableBuilder;
+    createTable<TB extends string>(table: TB): CreateTableBuilder<TB, never>;
     /**
      * Drop a table.
      *

package/dist/cjs/schema/schema.js

@@ -36,12 +36,47 @@ class SchemaModule {
      * ```ts
      * await db.schema
      *   .createTable('person')
-     *   .addColumn('id', 'int', col => col.primaryKey().increments())
+     *   .addColumn('id', 'integer', col => col.primaryKey().increments())
      *   .addColumn('first_name', 'varchar', col => col.notNull())
      *   .addColumn('last_name', 'varchar', col => col.notNull())
      *   .addColumn('gender', 'varchar')
      *   .execute()
      * ```
+     *
+     * @example
+     * This example creates a table with a foreign key. Not all database
+     * engines support column-level foreign key constraint definitions.
+     * For example if you are using MySQL 5.X see the next example after
+     * this one.
+     *
+     * ```ts
+     * await db.schema
+     *   .createTable('pet')
+     *   .addColumn('id', 'integer', col => col.primaryKey().increments())
+     *   .addColumn('owner_id', 'integer', col => col
+     *     .references('person.id')
+     *     .onDelete('cascade')
+     *   )
+     *   .execute()
+     * ```
+     *
+     * @example
+     * This example adds a foreign key constraint for a columns just
+     * like the previous example, but using a table-level statement.
+     * On MySQL 5.X you need to define foreign key constraints like
+     * this:
+     *
+     * ```ts
+     * await db.schema
+     *   .createTable('pet')
+     *   .addColumn('id', 'integer', col => col.primaryKey().increments())
+     *   .addColumn('owner_id', 'integer')
+     *   .addForeignKeyConstraint(
+     *     'pet_owner_id_foreign', ['owner_id'], 'person', ['id'],
+     *     (constraint) => constraint.onDelete('cascade')
+     *   )
+     *   .execute()
+     * ```
      */
     createTable(table) {
         return new create_table_builder_js_1.CreateTableBuilder({

package/dist/cjs/util/object-utils.d.ts

@@ -16,3 +16,4 @@ export declare function freeze<T>(obj: T): Readonly<T>;
 export declare function asArray<T>(arg: T | T[]): T[];
 export declare function asReadonlyArray<T>(arg: T | ReadonlyArray<T>): ReadonlyArray<T>;
 export declare function isReadonlyArray(arg: unknown): arg is ReadonlyArray<unknown>;
+export declare function noop<T>(obj: T): T;