Kysely
The main Kysely class.
You should create one instance of Kysely
per database using the Kysely
constructor. Each Kysely
instance maintains it's own connection pool.
Examples
This example assumes your database has tables person
and pet
:
import { Kysely, Generated, PostgresDialect } from 'kysely'
interface PersonTable {
id: Generated<number>
first_name: string
last_name: string
}
interface PetTable {
id: Generated<number>
owner_id: number
name: string
species: 'cat' | 'dog'
}
interface Database {
person: PersonTable,
pet: PetTable
}
const db = new Kysely<Database>({
dialect: new PostgresDialect({
host: 'localhost',
database: 'kysely_test',
})
})
§Implements
§Properties
Returns the SchemaModule module for building database schema.
Returns a the DynamicModule module.
The DynamicModule module can be used to bypass strict typing and passing in dynamic values for the queries.
Returns a {@link DatabaseIntrospector | database introspector}.
Returns a FunctionModule that can be used to write type safe function calls.
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()
The generated SQL (PostgreSQL):
select "person"."id", count("pet"."id") as "pet_count"
from "person"
inner join "pet" on "pet"."owner_id" = "person"."id"
group by "person"."id"
having count("pet"."id") > $1
Returns true if this Kysely
instance is a transaction.
You can also use db instanceof Transaction
.
§Methods
Creates a case
statement/operator.
See {@link ExpressionBuilder.case} for more information.
Provides a kysely instance bound to a single database connection.
Examples
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)
})
Releases all resources and disconnects from the database.
You need to call this when you are done using the Kysely
instance.
Executes a given compiled query or query builder.
See splitting build, compile and execute code recipe for more information.
Creates a TransactionBuilder that can be used to run queries inside a transaction.
The returned TransactionBuilder can be used to configure the transaction. The TransactionBuilder.execute method can then be called to run the transaction. TransactionBuilder.execute takes a function that is run inside the transaction. If the function throws, the transaction is rolled back. Otherwise the transaction is committed.
The callback function passed to the execute method gets the transaction object as its only argument. The transaction is of type Transaction which inherits Kysely. Any query started through the transaction object is executed inside the transaction.
Examples
This example inserts two rows in a transaction. If an error is thrown inside
the callback passed to the execute
method, the transaction is rolled back.
Otherwise it's committed.
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:
await db
.transaction()
.setIsolationLevel('serializable')
.execute(async (trx) => {
await doStuff(trx)
})
Returns a copy of this Kysely instance with the given plugin installed.
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:
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()