kysely
Version:
Type safe SQL query builder
295 lines (294 loc) • 10.2 kB
JavaScript
/// <reference types="./query-creator.d.ts" />
import { createSelectQueryBuilder, } from './query-builder/select-query-builder.js';
import { InsertQueryBuilder } from './query-builder/insert-query-builder.js';
import { DeleteQueryBuilder } from './query-builder/delete-query-builder.js';
import { UpdateQueryBuilder } from './query-builder/update-query-builder.js';
import { DeleteQueryNode } from './operation-node/delete-query-node.js';
import { InsertQueryNode } from './operation-node/insert-query-node.js';
import { SelectQueryNode } from './operation-node/select-query-node.js';
import { UpdateQueryNode } from './operation-node/update-query-node.js';
import { parseTable, parseTableExpression, parseTableExpressionOrList, parseAliasedTable, } from './parser/table-parser.js';
import { parseCommonTableExpression, } from './parser/with-parser.js';
import { WithNode } from './operation-node/with-node.js';
import { createQueryId } from './util/query-id.js';
import { WithSchemaPlugin } from './plugin/with-schema/with-schema-plugin.js';
import { freeze } from './util/object-utils.js';
import { parseSelectArg, } from './parser/select-parser.js';
import { MergeQueryBuilder } from './query-builder/merge-query-builder.js';
import { MergeQueryNode } from './operation-node/merge-query-node.js';
export class QueryCreator {
#props;
constructor(props) {
this.#props = freeze(props);
}
selectFrom(from) {
return createSelectQueryBuilder({
queryId: createQueryId(),
executor: this.#props.executor,
queryNode: SelectQueryNode.createFrom(parseTableExpressionOrList(from), this.#props.withNode),
});
}
selectNoFrom(selection) {
return createSelectQueryBuilder({
queryId: createQueryId(),
executor: this.#props.executor,
queryNode: SelectQueryNode.cloneWithSelections(SelectQueryNode.create(this.#props.withNode), parseSelectArg(selection)),
});
}
/**
* Creates an insert query.
*
* The return value of this query is an instance of {@link InsertResult}. {@link InsertResult}
* has the {@link InsertResult.insertId | insertId} field that holds the auto incremented id of
* the inserted row if the db returned one.
*
* See the {@link InsertQueryBuilder.values | values} method for more info and examples. Also see
* the {@link ReturningInterface.returning | returning} method for a way to return columns
* on supported databases like PostgreSQL.
*
* ### Examples
*
* ```ts
* const result = await db
* .insertInto('person')
* .values({
* first_name: 'Jennifer',
* last_name: 'Aniston'
* })
* .executeTakeFirst()
*
* console.log(result.insertId)
* ```
*
* Some databases like PostgreSQL support the `returning` method:
*
* ```ts
* const { id } = await db
* .insertInto('person')
* .values({
* first_name: 'Jennifer',
* last_name: 'Aniston'
* })
* .returning('id')
* .executeTakeFirst()
* ```
*/
insertInto(table) {
return new InsertQueryBuilder({
queryId: createQueryId(),
executor: this.#props.executor,
queryNode: InsertQueryNode.create(parseTable(table), this.#props.withNode),
});
}
/**
* Creates a replace query.
*
* A MySQL-only statement similar to {@link InsertQueryBuilder.onDuplicateKeyUpdate}
* that deletes and inserts values on collision instead of updating existing rows.
*
* The return value of this query is an instance of {@link InsertResult}. {@link InsertResult}
* has the {@link InsertResult.insertId | insertId} field that holds the auto incremented id of
* the inserted row if the db returned one.
*
* See the {@link InsertQueryBuilder.values | values} method for more info and examples.
*
* ### Examples
*
* ```ts
* const result = await db
* .replaceInto('person')
* .values({
* first_name: 'Jennifer',
* last_name: 'Aniston'
* })
* .executeTakeFirst()
*
* console.log(result.insertId)
* ```
*/
replaceInto(table) {
return new InsertQueryBuilder({
queryId: createQueryId(),
executor: this.#props.executor,
queryNode: InsertQueryNode.create(parseTable(table), this.#props.withNode, true),
});
}
deleteFrom(tables) {
return new DeleteQueryBuilder({
queryId: createQueryId(),
executor: this.#props.executor,
queryNode: DeleteQueryNode.create(parseTableExpressionOrList(tables), this.#props.withNode),
});
}
updateTable(table) {
return new UpdateQueryBuilder({
queryId: createQueryId(),
executor: this.#props.executor,
queryNode: UpdateQueryNode.create(parseTableExpression(table), this.#props.withNode),
});
}
mergeInto(targetTable) {
return new MergeQueryBuilder({
queryId: createQueryId(),
executor: this.#props.executor,
queryNode: MergeQueryNode.create(parseAliasedTable(targetTable), this.#props.withNode),
});
}
/**
* Creates a `with` query (Common Table Expression).
*
* ### Examples
*
* ```ts
* await db
* .with('jennifers', (db) => db
* .selectFrom('person')
* .where('first_name', '=', 'Jennifer')
* .select(['id', 'age'])
* )
* .with('adult_jennifers', (db) => db
* .selectFrom('jennifers')
* .where('age', '>', 18)
* .select(['id', 'age'])
* )
* .selectFrom('adult_jennifers')
* .where('age', '<', 60)
* .selectAll()
* .execute()
* ```
*
* The CTE name can optionally specify column names in addition to
* a name. In that case Kysely requires the expression to retun
* rows with the same columns.
*
* ```ts
* await db
* .with('jennifers(id, age)', (db) => db
* .selectFrom('person')
* .where('first_name', '=', 'Jennifer')
* // This is ok since we return columns with the same
* // names as specified by `jennifers(id, age)`.
* .select(['id', 'age'])
* )
* .selectFrom('jennifers')
* .selectAll()
* .execute()
* ```
*
* The first argument can also be a callback. The callback is passed
* a `CTEBuilder` instance that can be used to configure the CTE:
*
* ```ts
* await db
* .with(
* (cte) => cte('jennifers').materialized(),
* (db) => db
* .selectFrom('person')
* .where('first_name', '=', 'Jennifer')
* .select(['id', 'age'])
* )
* .selectFrom('jennifers')
* .selectAll()
* .execute()
* ```
*/
with(nameOrBuilder, expression) {
const cte = parseCommonTableExpression(nameOrBuilder, expression);
return new QueryCreator({
...this.#props,
withNode: this.#props.withNode
? WithNode.cloneWithExpression(this.#props.withNode, cte)
: WithNode.create(cte),
});
}
/**
* Creates a recursive `with` query (Common Table Expression).
*
* Note that recursiveness is a property of the whole `with` statement.
* You cannot have recursive and non-recursive CTEs in a same `with` statement.
* Therefore the recursiveness is determined by the **first** `with` or
* `withRecusive` call you make.
*
* See the {@link with} method for examples and more documentation.
*/
withRecursive(nameOrBuilder, expression) {
const cte = parseCommonTableExpression(nameOrBuilder, expression);
return new QueryCreator({
...this.#props,
withNode: this.#props.withNode
? WithNode.cloneWithExpression(this.#props.withNode, cte)
: WithNode.create(cte, { recursive: true }),
});
}
/**
* Returns a copy of this query creator instance with the given plugin installed.
*/
withPlugin(plugin) {
return new QueryCreator({
...this.#props,
executor: this.#props.executor.withPlugin(plugin),
});
}
/**
* Returns a copy of this query creator instance without any plugins.
*/
withoutPlugins() {
return new QueryCreator({
...this.#props,
executor: this.#props.executor.withoutPlugins(),
});
}
/**
* 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.
*
* See [this recipe](https://github.com/koskimas/kysely/tree/master/site/docs/recipes/schemas.md)
* for a more detailed explanation.
*
* ### Examples
*
* ```
* await db
* .withSchema('mammals')
* .selectFrom('pet')
* .selectAll()
* .innerJoin('public.person', 'public.person.id', 'pet.owner_id')
* .execute()
* ```
*
* The generated SQL (PostgreSQL):
*
* ```sql
* select * from "mammals"."pet"
* inner join "public"."person"
* on "public"."person"."id" = "mammals"."pet"."owner_id"
* ```
*
* `withSchema` is smart enough to not add schema for aliases,
* common table expressions or other places where the schema
* doesn't belong to:
*
* ```
* await db
* .withSchema('mammals')
* .selectFrom('pet as p')
* .select('p.name')
* .execute()
* ```
*
* The generated SQL (PostgreSQL):
*
* ```sql
* select "p"."name" from "mammals"."pet" as "p"
* ```
*/
withSchema(schema) {
return new QueryCreator({
...this.#props,
executor: this.#props.executor.withPluginAtFront(new WithSchemaPlugin(schema)),
});
}
}