import type { Dialect } from './dialect/dialect.js'; import { SchemaModule } from './schema/schema.js'; import { DynamicModule } from './dynamic/dynamic.js'; import type { QueryExecutor } from './query-executor/query-executor.js'; import { QueryCreator } from './query-creator.js'; import type { KyselyPlugin } from './plugin/kysely-plugin.js'; import type { DatabaseIntrospector } from './dialect/database-introspector.js'; import { type Driver, type IsolationLevel, type AccessMode } from './driver/driver.js'; import { type FunctionModule } from './query-builder/function-module.js'; import { type LogConfig } from './util/log.js'; import type { QueryExecutorProvider } from './query-executor/query-executor-provider.js'; import type { QueryResult } from './driver/database-connection.js'; import type { CompiledQuery } from './query-compiler/compiled-query.js'; import { type QueryId } from './util/query-id.js'; import { type Compilable } from './util/compilable.js'; import { CaseBuilder } from './query-builder/case-builder.js'; import type { Expression } from './expression/expression.js'; import type { DrainOuterGeneric } from './util/type-utils.js'; import type { ReleaseSavepoint, RollbackToSavepoint } from './parser/savepoint-parser.js'; import { type ControlledConnection } from './util/provide-controlled-connection.js'; declare global { interface AsyncDisposable { } interface SymbolConstructor { readonly asyncDispose: unique symbol; } } /** * The main Kysely class. * * You should create one instance of `Kysely` per database using the {@link Kysely} * constructor. Each `Kysely` instance maintains its own connection pool. * * ### Examples * * This example assumes your database has a "person" table: * * ```ts * import * as Sqlite from 'better-sqlite3' * import { type Generated, Kysely, SqliteDialect } from 'kysely' * * interface Database { * person: { * id: Generated * first_name: string * last_name: string | null * } * } * * const db = new Kysely({ * dialect: new SqliteDialect({ * database: new Sqlite(':memory:'), * }) * }) * ``` * * @typeParam DB - The database interface type. Keys of this type must be table names * in the database and values must be interfaces that describe the rows in those * tables. See the examples above. */ export declare class Kysely extends QueryCreator implements QueryExecutorProvider, AsyncDisposable { #private; constructor(args: KyselyConfig); constructor(args: KyselyProps); /** * Returns the {@link SchemaModule} module for building database schema. */ get schema(): SchemaModule; /** * Returns a the {@link DynamicModule} module. * * The {@link DynamicModule} module can be used to bypass strict typing and * passing in dynamic values for the queries. */ get dynamic(): DynamicModule; /** * Returns a {@link DatabaseIntrospector | database introspector}. */ get introspection(): DatabaseIntrospector; /** * Creates a `case` statement/operator. * * See {@link ExpressionBuilder.case} for more information. */ case(): CaseBuilder; case(value: Expression): CaseBuilder; /** * Returns a {@link FunctionModule} that can be used to write somewhat type-safe function * calls. * * ```ts * const { count } = db.fn * * await db.selectFrom('person') * .innerJoin('pet', 'pet.owner_id', 'person.id') * .select([ * 'id', * count('pet.id').as('person_count'), * ]) * .groupBy('person.id') * .having(count('pet.id'), '>', 10) * .execute() * ``` * * The generated SQL (PostgreSQL): * * ```sql * select "person"."id", count("pet"."id") as "person_count" * from "person" * inner join "pet" on "pet"."owner_id" = "person"."id" * group by "person"."id" * having count("pet"."id") > $1 * ``` * * Why "somewhat" type-safe? Because the function calls are not bound to the * current query context. They allow you to reference columns and tables that * are not in the current query. E.g. remove the `innerJoin` from the previous * query and TypeScript won't even complain. * * If you want to make the function calls fully type-safe, you can use the * {@link ExpressionBuilder.fn} getter for a query context-aware, stricter {@link FunctionModule}. * * ```ts * await db.selectFrom('person') * .innerJoin('pet', 'pet.owner_id', 'person.id') * .select((eb) => [ * 'person.id', * eb.fn.count('pet.id').as('pet_count') * ]) * .groupBy('person.id') * .having((eb) => eb.fn.count('pet.id'), '>', 10) * .execute() * ``` */ get fn(): FunctionModule; /** * Creates a {@link TransactionBuilder} that can be used to run queries inside a transaction. * * The returned {@link TransactionBuilder} can be used to configure the transaction. The * {@link TransactionBuilder.execute} method can then be called to run the transaction. * {@link TransactionBuilder.execute} takes a function that is run inside the * transaction. If the function throws an exception, * 1. the exception is caught, * 2. the transaction is rolled back, and * 3. the exception is thrown again. * Otherwise the transaction is committed. * * The callback function passed to the {@link TransactionBuilder.execute | execute} * method gets the transaction object as its only argument. The transaction is * of type {@link Transaction} which inherits {@link Kysely}. Any query * started through the transaction object is executed inside the transaction. * * To run a controlled transaction, allowing you to commit and rollback manually, * use {@link startTransaction} instead. * * ### Examples * * * * This example inserts two rows in a transaction. If an exception is thrown inside * the callback passed to the `execute` method, * 1. the exception is caught, * 2. the transaction is rolled back, and * 3. the exception is thrown again. * Otherwise the transaction is committed. * * ```ts * const catto = await db.transaction().execute(async (trx) => { * const jennifer = await trx.insertInto('person') * .values({ * first_name: 'Jennifer', * last_name: 'Aniston', * age: 40, * }) * .returning('id') * .executeTakeFirstOrThrow() * * return await trx.insertInto('pet') * .values({ * owner_id: jennifer.id, * name: 'Catto', * species: 'cat', * is_favorite: false, * }) * .returningAll() * .executeTakeFirst() * }) * ``` * * Setting the isolation level: * * ```ts * import type { Kysely } from 'kysely' * * await db * .transaction() * .setIsolationLevel('serializable') * .execute(async (trx) => { * await doStuff(trx) * }) * * async function doStuff(kysely: typeof db) { * // ... * } * ``` */ transaction(): TransactionBuilder; /** * Creates a {@link ControlledTransactionBuilder} that can be used to run queries inside a controlled transaction. * * The returned {@link ControlledTransactionBuilder} can be used to configure the transaction. * The {@link ControlledTransactionBuilder.execute} method can then be called * to start the transaction and return a {@link ControlledTransaction}. * * A {@link ControlledTransaction} allows you to commit and rollback manually, * execute savepoint commands. It extends {@link Transaction} which extends {@link Kysely}, * so you can run queries inside the transaction. Once the transaction is committed, * or rolled back, it can't be used anymore - all queries will throw an error. * This is to prevent accidentally running queries outside the transaction - where * atomicity is not guaranteed anymore. * * ### Examples * * * * A controlled transaction allows you to commit and rollback manually, execute * savepoint commands, and queries in general. * * In this example we start a transaction, use it to insert two rows and then commit * the transaction. If an error is thrown, we catch it and rollback the transaction. * * ```ts * const trx = await db.startTransaction().execute() * * try { * const jennifer = await trx.insertInto('person') * .values({ * first_name: 'Jennifer', * last_name: 'Aniston', * age: 40, * }) * .returning('id') * .executeTakeFirstOrThrow() * * const catto = await trx.insertInto('pet') * .values({ * owner_id: jennifer.id, * name: 'Catto', * species: 'cat', * is_favorite: false, * }) * .returningAll() * .executeTakeFirstOrThrow() * * await trx.commit().execute() * * // ... * } catch (error) { * await trx.rollback().execute() * } * ``` * * * * A controlled transaction allows you to commit and rollback manually, execute * savepoint commands, and queries in general. * * In this example we start a transaction, insert a person, create a savepoint, * try inserting a toy and a pet, and if an error is thrown, we rollback to the * savepoint. Eventually we release the savepoint, insert an audit record and * commit the transaction. If an error is thrown, we catch it and rollback the * transaction. * * ```ts * const trx = await db.startTransaction().execute() * * try { * const jennifer = await trx * .insertInto('person') * .values({ * first_name: 'Jennifer', * last_name: 'Aniston', * age: 40, * }) * .returning('id') * .executeTakeFirstOrThrow() * * const trxAfterJennifer = await trx.savepoint('after_jennifer').execute() * * try { * const catto = await trxAfterJennifer * .insertInto('pet') * .values({ * owner_id: jennifer.id, * name: 'Catto', * species: 'cat', * }) * .returning('id') * .executeTakeFirstOrThrow() * * await trxAfterJennifer * .insertInto('toy') * .values({ name: 'Bone', price: 1.99, pet_id: catto.id }) * .execute() * } catch (error) { * await trxAfterJennifer.rollbackToSavepoint('after_jennifer').execute() * } * * await trxAfterJennifer.releaseSavepoint('after_jennifer').execute() * * await trx.insertInto('audit').values({ action: 'added Jennifer' }).execute() * * await trx.commit().execute() * } catch (error) { * await trx.rollback().execute() * } * ``` */ startTransaction(): ControlledTransactionBuilder; /** * Provides a kysely instance bound to a single database connection. * * ### Examples * * ```ts * await db * .connection() * .execute(async (db) => { * // `db` is an instance of `Kysely` that's bound to a single * // database connection. All queries executed through `db` use * // the same connection. * await doStuff(db) * }) * * async function doStuff(kysely: typeof db) { * // ... * } * ``` */ connection(): ConnectionBuilder; /** * Returns a copy of this Kysely instance with the given plugin installed. */ withPlugin(plugin: KyselyPlugin): Kysely; /** * Returns a copy of this Kysely instance without any plugins. */ withoutPlugins(): Kysely; /** * @override */ withSchema(schema: string): Kysely; /** * Returns a copy of this Kysely instance with tables added to its * database type. * * This method only modifies the types and doesn't affect any of the * executed queries in any way. * * ### Examples * * The following example adds and uses a temporary table: * * ```ts * await db.schema * .createTable('temp_table') * .temporary() * .addColumn('some_column', 'integer') * .execute() * * const tempDb = db.withTables<{ * temp_table: { * some_column: number * } * }>() * * await tempDb * .insertInto('temp_table') * .values({ some_column: 100 }) * .execute() * ``` */ withTables>>(): Kysely>; /** * Releases all resources and disconnects from the database. * * You need to call this when you are done using the `Kysely` instance. */ destroy(): Promise; /** * Returns true if this `Kysely` instance is a transaction. * * You can also use `db instanceof Transaction`. */ get isTransaction(): boolean; /** * @internal * @private */ getExecutor(): QueryExecutor; /** * Executes a given compiled query or query builder. * * See {@link https://github.com/kysely-org/kysely/blob/master/site/docs/recipes/0004-splitting-query-building-and-execution.md#execute-compiled-queries splitting build, compile and execute code recipe} for more information. */ executeQuery(query: CompiledQuery | Compilable, queryId?: QueryId): Promise>; [Symbol.asyncDispose](): Promise; } export declare class Transaction extends Kysely { #private; constructor(props: KyselyProps); /** * Returns true if this `Kysely` instance is a transaction. * * You can also use `db instanceof Transaction`. */ get isTransaction(): true; /** * Creates a {@link TransactionBuilder} that can be used to run queries inside a transaction. * * The returned {@link TransactionBuilder} can be used to configure the transaction. The * {@link TransactionBuilder.execute} method can then be called to run the transaction. * {@link TransactionBuilder.execute} takes a function that is run inside the * transaction. If the function throws an exception, * 1. the exception is caught, * 2. the transaction is rolled back, and * 3. the exception is thrown again. * Otherwise the transaction is committed. * * The callback function passed to the {@link TransactionBuilder.execute | execute} * method gets the transaction object as its only argument. The transaction is * of type {@link Transaction} which inherits {@link Kysely}. Any query * started through the transaction object is executed inside the transaction. * * To run a controlled transaction, allowing you to commit and rollback manually, * use {@link startTransaction} instead. * * ### Examples * * * * This example inserts two rows in a transaction. If an exception is thrown inside * the callback passed to the `execute` method, * 1. the exception is caught, * 2. the transaction is rolled back, and * 3. the exception is thrown again. * Otherwise the transaction is committed. * * ```ts * const catto = await db.transaction().execute(async (trx) => { * const jennifer = await trx.insertInto('person') * .values({ * first_name: 'Jennifer', * last_name: 'Aniston', * age: 40, * }) * .returning('id') * .executeTakeFirstOrThrow() * * return await trx.insertInto('pet') * .values({ * owner_id: jennifer.id, * name: 'Catto', * species: 'cat', * is_favorite: false, * }) * .returningAll() * .executeTakeFirst() * }) * ``` * * Setting the isolation level: * * ```ts * import type { Kysely } from 'kysely' * * await db * .transaction() * .setIsolationLevel('serializable') * .execute(async (trx) => { * await doStuff(trx) * }) * * async function doStuff(kysely: typeof db) { * // ... * } * ``` */ transaction(): TransactionBuilder; /** * Provides a kysely instance bound to a single database connection. * * ### Examples * * ```ts * await db * .connection() * .execute(async (db) => { * // `db` is an instance of `Kysely` that's bound to a single * // database connection. All queries executed through `db` use * // the same connection. * await doStuff(db) * }) * * async function doStuff(kysely: typeof db) { * // ... * } * ``` */ connection(): ConnectionBuilder; /** * Releases all resources and disconnects from the database. * * You need to call this when you are done using the `Kysely` instance. */ destroy(): Promise; /** * Returns a copy of this Kysely instance with the given plugin installed. */ withPlugin(plugin: KyselyPlugin): Transaction; /** * Returns a copy of this Kysely instance without any plugins. */ withoutPlugins(): Transaction; /** * @override */ withSchema(schema: string): Transaction; /** * Returns a copy of this Kysely instance with tables added to its * database type. * * This method only modifies the types and doesn't affect any of the * executed queries in any way. * * ### Examples * * The following example adds and uses a temporary table: * * ```ts * await db.schema * .createTable('temp_table') * .temporary() * .addColumn('some_column', 'integer') * .execute() * * const tempDb = db.withTables<{ * temp_table: { * some_column: number * } * }>() * * await tempDb * .insertInto('temp_table') * .values({ some_column: 100 }) * .execute() * ``` */ withTables>>(): Transaction>; } export interface KyselyProps { readonly config: KyselyConfig; readonly driver: Driver; readonly executor: QueryExecutor; readonly dialect: Dialect; } export declare function isKyselyProps(obj: unknown): obj is KyselyProps; export interface KyselyConfig { readonly dialect: Dialect; readonly plugins?: KyselyPlugin[]; /** * A list of log levels to log or a custom logger function. * * Currently there's only two levels: `query` and `error`. * This will be expanded based on user feedback later. * * ### Examples * * Setting up built-in logging for preferred log levels: * * ```ts * import * as Sqlite from 'better-sqlite3' * import { Kysely, SqliteDialect } from 'kysely' * import type { Database } from 'type-editor' // imaginary module * * const db = new Kysely({ * dialect: new SqliteDialect({ * database: new Sqlite(':memory:'), * }), * log: ['query', 'error'] * }) * ``` * * Setting up custom logging: * * ```ts * import * as Sqlite from 'better-sqlite3' * import { Kysely, SqliteDialect } from 'kysely' * import type { Database } from 'type-editor' // imaginary module * * const db = new Kysely({ * dialect: new SqliteDialect({ * database: new Sqlite(':memory:'), * }), * log(event): void { * if (event.level === 'query') { * console.log(event.query.sql) * console.log(event.query.parameters) * } * } * }) * ``` */ readonly log?: LogConfig; } export declare class ConnectionBuilder { #private; constructor(props: ConnectionBuilderProps); execute(callback: (db: Kysely) => Promise): Promise; } interface ConnectionBuilderProps extends KyselyProps { } export declare class TransactionBuilder { #private; constructor(props: TransactionBuilderProps); setAccessMode(accessMode: AccessMode): TransactionBuilder; setIsolationLevel(isolationLevel: IsolationLevel): TransactionBuilder; execute(callback: (trx: Transaction) => Promise): Promise; } interface TransactionBuilderProps extends KyselyProps { readonly accessMode?: AccessMode; readonly isolationLevel?: IsolationLevel; } export declare class ControlledTransactionBuilder { #private; constructor(props: TransactionBuilderProps); setAccessMode(accessMode: AccessMode): ControlledTransactionBuilder; setIsolationLevel(isolationLevel: IsolationLevel): ControlledTransactionBuilder; execute(): Promise>; } export declare class ControlledTransaction extends Transaction { #private; constructor(props: ControlledTransactionProps); get isCommitted(): boolean; get isRolledBack(): boolean; /** * Commits the transaction. * * See {@link rollback}. * * ### Examples * * ```ts * import type { Kysely } from 'kysely' * import type { Database } from 'type-editor' // imaginary module * * const trx = await db.startTransaction().execute() * * try { * await doSomething(trx) * * await trx.commit().execute() * } catch (error) { * await trx.rollback().execute() * } * * async function doSomething(kysely: Kysely) {} * ``` */ commit(): Command; /** * Rolls back the transaction. * * See {@link commit} and {@link rollbackToSavepoint}. * * ### Examples * * ```ts * import type { Kysely } from 'kysely' * import type { Database } from 'type-editor' // imaginary module * * const trx = await db.startTransaction().execute() * * try { * await doSomething(trx) * * await trx.commit().execute() * } catch (error) { * await trx.rollback().execute() * } * * async function doSomething(kysely: Kysely) {} * ``` */ rollback(): Command; /** * Creates a savepoint with a given name. * * See {@link rollbackToSavepoint} and {@link releaseSavepoint}. * * For a type-safe experience, you should use the returned instance from now on. * * ### Examples * * ```ts * import type { Kysely } from 'kysely' * import type { Database } from 'type-editor' // imaginary module * * const trx = await db.startTransaction().execute() * * await insertJennifer(trx) * * const trxAfterJennifer = await trx.savepoint('after_jennifer').execute() * * try { * await doSomething(trxAfterJennifer) * } catch (error) { * await trxAfterJennifer.rollbackToSavepoint('after_jennifer').execute() * } * * async function insertJennifer(kysely: Kysely) {} * async function doSomething(kysely: Kysely) {} * ``` */ savepoint(savepointName: SN extends S ? never : SN): Command>; /** * Rolls back to a savepoint with a given name. * * See {@link savepoint} and {@link releaseSavepoint}. * * You must use the same instance returned by {@link savepoint}, or * escape the type-check by using `as any`. * * ### Examples * * ```ts * import type { Kysely } from 'kysely' * import type { Database } from 'type-editor' // imaginary module * * const trx = await db.startTransaction().execute() * * await insertJennifer(trx) * * const trxAfterJennifer = await trx.savepoint('after_jennifer').execute() * * try { * await doSomething(trxAfterJennifer) * } catch (error) { * await trxAfterJennifer.rollbackToSavepoint('after_jennifer').execute() * } * * async function insertJennifer(kysely: Kysely) {} * async function doSomething(kysely: Kysely) {} * ``` */ rollbackToSavepoint(savepointName: SN): RollbackToSavepoint extends string[] ? Command>> : never; /** * Releases a savepoint with a given name. * * See {@link savepoint} and {@link rollbackToSavepoint}. * * You must use the same instance returned by {@link savepoint}, or * escape the type-check by using `as any`. * * ### Examples * * ```ts * import type { Kysely } from 'kysely' * import type { Database } from 'type-editor' // imaginary module * * const trx = await db.startTransaction().execute() * * await insertJennifer(trx) * * const trxAfterJennifer = await trx.savepoint('after_jennifer').execute() * * try { * await doSomething(trxAfterJennifer) * } catch (error) { * await trxAfterJennifer.rollbackToSavepoint('after_jennifer').execute() * } * * await trxAfterJennifer.releaseSavepoint('after_jennifer').execute() * * await doSomethingElse(trx) * * async function insertJennifer(kysely: Kysely) {} * async function doSomething(kysely: Kysely) {} * async function doSomethingElse(kysely: Kysely) {} * ``` */ releaseSavepoint(savepointName: SN): ReleaseSavepoint extends string[] ? Command>> : never; /** * Returns a copy of this Kysely instance with the given plugin installed. */ withPlugin(plugin: KyselyPlugin): ControlledTransaction; /** * Returns a copy of this Kysely instance without any plugins. */ withoutPlugins(): ControlledTransaction; /** * @override */ withSchema(schema: string): ControlledTransaction; /** * Returns a copy of this Kysely instance with tables added to its * database type. * * This method only modifies the types and doesn't affect any of the * executed queries in any way. * * ### Examples * * The following example adds and uses a temporary table: * * ```ts * await db.schema * .createTable('temp_table') * .temporary() * .addColumn('some_column', 'integer') * .execute() * * const tempDb = db.withTables<{ * temp_table: { * some_column: number * } * }>() * * await tempDb * .insertInto('temp_table') * .values({ some_column: 100 }) * .execute() * ``` */ withTables>>(): ControlledTransaction, S>; } interface ControlledTransactionProps extends KyselyProps { readonly connection: ControlledConnection; } export declare class Command { #private; constructor(cb: () => Promise); /** * Executes the command. */ execute(): Promise; } export {};