Skip to content
Migrating from NextAuth.js v4? Read our migration guide.
API reference
@auth/kysely-adapter

@auth/kysely-adapter

Official Kysely adapter for Auth.js / NextAuth.js.

Installation

npm install kysely @auth/kysely-adapter

KyselyAuth<DB, T>

Wrapper over the original Kysely class in order to validate the passed in database interface. A regular Kysely instance may also be used, but wrapping it ensures the database interface implements the fields that Auth.js requires. When used with kysely-codegen, the Codegen type can be passed as the second generic argument. The generated types will be used, and KyselyAuth will only verify that the correct fields exist.

Extends

  • Kysely<DB>

Type parameters

Type parameterValue
DB extends T-
TDatabase

Constructors

new KyselyAuth(args)

new KyselyAuth<DB, T>(args): KyselyAuth<DB, T>
Parameters
ParameterType
argsKyselyConfig
Returns

KyselyAuth<DB, T>

Inherited from

Kysely<DB>.constructor

new KyselyAuth(args)

new KyselyAuth<DB, T>(args): KyselyAuth<DB, T>
Parameters
ParameterType
argsKyselyProps
Returns

KyselyAuth<DB, T>

Inherited from

Kysely<DB>.constructor

Properties

#private

private #private: any;
Inherited from

Kysely.#private

#private

private #private: any;
Inherited from

Kysely.#private

Accessors

dynamic

get dynamic(): DynamicModule

Returns a the DynamicModule module.

The DynamicModule module can be used to bypass strict typing and passing in dynamic values for the queries.

Returns

DynamicModule

fn

get fn(): FunctionModule<DB, keyof DB>

Returns a FunctionModule that can be used to write type safe function calls.

const { count } = db.fn
 
await db.selectFrom('person')
  .innerJoin('pet', 'pet.owner_id', 'person.id')
  .select([
    'person.id',
    count('pet.id').as('pet_count')
  ])
  .groupBy('person.id')
  .having(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

FunctionModule<DB, keyof DB>

introspection

get introspection(): DatabaseIntrospector

Returns a DatabaseIntrospector | database introspector.

Returns

DatabaseIntrospector

isTransaction

get isTransaction(): boolean

Returns true if this Kysely instance is a transaction.

You can also use db instanceof Transaction.

Returns

boolean

schema

get schema(): SchemaModule

Returns the SchemaModule module for building database schema.

Returns

SchemaModule

Methods

connection()

connection(): ConnectionBuilder<DB>

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)
  })
Returns

ConnectionBuilder<DB>

Inherited from

Kysely.connection

deleteFrom()

deleteFrom(from)
deleteFrom<TR>(from): DeleteQueryBuilder<DB, ExtractTableAlias<DB, TR>, DeleteResult>

Creates a delete query.

See the DeleteQueryBuilder.where method for examples on how to specify a where clause for the delete operation.

The return value of the query is an instance of DeleteResult.

Examples

Deleting person with id 1:

const result = await db
  .deleteFrom('person')
  .where('person.id', '=', 1)
  .executeTakeFirst()
 
console.log(result.numDeletedRows)

The generated SQL (PostgreSQL):

delete from "person" where "person"."id" = $1

Some databases such as MySQL support deleting from multiple tables:

const result = await db
  .deleteFrom(['person', 'pet'])
  .using('person')
  .innerJoin('pet', 'pet.owner_id', '=', 'person.id')
  .where('person.id', '=', 1)
  .executeTakeFirst()

The generated SQL (MySQL):

delete from `person`, `pet`
using `person`
inner join `pet` on `pet`.`owner_id` = `person`.`id`
where `person`.`id` = ?
Type parameters
Type parameter
TR extends string
Parameters
ParameterType
fromTR[]
Returns

DeleteQueryBuilder<DB, ExtractTableAlias<DB, TR>, DeleteResult>

Inherited from

Kysely.deleteFrom

deleteFrom(tables)
deleteFrom<TR>(tables): DeleteQueryBuilder<From<DB, TR>, ExtractAliasFromTableExpression<DB, TR>, DeleteResult>
Type parameters
Type parameter
TR extends string | AliasedExpression<any, any>
Parameters
ParameterType
tablesTR[]
Returns

DeleteQueryBuilder<From<DB, TR>, ExtractAliasFromTableExpression<DB, TR>, DeleteResult>

Inherited from

Kysely.deleteFrom

deleteFrom(from)
deleteFrom<TR>(from): DeleteQueryBuilder<DB, ExtractTableAlias<DB, TR>, DeleteResult>
Type parameters
Type parameter
TR extends string
Parameters
ParameterType
fromTR
Returns

DeleteQueryBuilder<DB, ExtractTableAlias<DB, TR>, DeleteResult>

Inherited from

Kysely.deleteFrom

deleteFrom(table)
deleteFrom<TR>(table): DeleteQueryBuilder<From<DB, TR>, ExtractAliasFromTableExpression<DB, TR>, DeleteResult>
Type parameters
Type parameter
TR extends string | AliasedExpression<any, any>
Parameters
ParameterType
tableTR
Returns

DeleteQueryBuilder<From<DB, TR>, ExtractAliasFromTableExpression<DB, TR>, DeleteResult>

Inherited from

Kysely.deleteFrom

destroy()

destroy(): Promise<void>

Releases all resources and disconnects from the database.

You need to call this when you are done using the Kysely instance.

Returns

Promise<void>

Inherited from

Kysely.destroy

executeQuery()

executeQuery<R>(query, queryId?): Promise<QueryResult<R>>

Executes a given compiled query or query builder.

See splitting build, compile and execute code recipe for more information.

Type parameters
Type parameter
R
Parameters
ParameterType
queryCompiledQuery<R> | Compilable<R>
queryId?QueryId
Returns

Promise<QueryResult<R>>

Inherited from

Kysely.executeQuery

insertInto()

insertInto<T>(table): InsertQueryBuilder<DB, T, InsertResult>

Creates an insert query.

The return value of this query is an instance of InsertResult. InsertResult has the InsertResult.insertId | insertId field that holds the auto incremented id of the inserted row if the db returned one.

See the InsertQueryBuilder.values | values method for more info and examples. Also see the ReturningInterface.returning | returning method for a way to return columns on supported databases like PostgreSQL.

Examples

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:

const { id } = await db
  .insertInto('person')
  .values({
    first_name: 'Jennifer',
    last_name: 'Aniston'
  })
  .returning('id')
  .executeTakeFirst()
Type parameters
Type parameter
T extends string
Parameters
ParameterType
tableT
Returns

InsertQueryBuilder<DB, T, InsertResult>

Inherited from

Kysely.insertInto

replaceInto()

replaceInto<T>(table): InsertQueryBuilder<DB, T, InsertResult>

Creates a replace query.

A MySQL-only statement similar to InsertQueryBuilder.onDuplicateKeyUpdate that deletes and inserts values on collision instead of updating existing rows.

The return value of this query is an instance of InsertResult. InsertResult has the InsertResult.insertId | insertId field that holds the auto incremented id of the inserted row if the db returned one.

See the InsertQueryBuilder.values | values method for more info and examples.

Examples

const result = await db
  .replaceInto('person')
  .values({
    first_name: 'Jennifer',
    last_name: 'Aniston'
  })
  .executeTakeFirst()
 
console.log(result.insertId)
Type parameters
Type parameter
T extends string
Parameters
ParameterType
tableT
Returns

InsertQueryBuilder<DB, T, InsertResult>

Inherited from

Kysely.replaceInto

selectFrom()

selectFrom(from)
selectFrom<TE>(from): SelectQueryBuilder<DB, ExtractTableAlias<DB, TE>, {}>

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.

Examples

Create a select query for one table:

db.selectFrom('person').selectAll()

The generated SQL (PostgreSQL):

select * from "person"

Create a select query for one table with an alias:

const persons = await db.selectFrom('person as p')
  .select(['p.id', 'first_name'])
  .execute()
 
console.log(persons[0].id)

The generated SQL (PostgreSQL):

select "p"."id", "first_name" from "person" as "p"

Create a select query from a subquery:

const persons = await db.selectFrom(
    (eb) => eb.selectFrom('person').select('person.id as identifier').as('p')
  )
  .select('p.identifier')
  .execute()
 
console.log(persons[0].identifier)

The generated SQL (PostgreSQL):

select "p"."identifier",
from (
  select "person"."id" as "identifier" from "person"
) as p

Create a select query from raw sql:

import { sql } from 'kysely'
 
const items = await db
  .selectFrom(sql<{ one: number }>`(select 1 as one)`.as('q'))
  .select('q.one')
  .execute()
 
console.log(items[0].one)

The generated SQL (PostgreSQL):

select "q"."one",
from (
  select 1 as one
) as q

When you use the sql tag you need to also provide the result type of the raw snippet / query so that Kysely can figure out what columns are available for the rest of the query.

The selectFrom method also accepts an array for multiple tables. All the above examples can also be used in an array.

import { sql } from 'kysely'
 
const items = await db.selectFrom([
    'person as p',
    db.selectFrom('pet').select('pet.species').as('a'),
    sql<{ one: number }>`(select 1 as one)`.as('q')
  ])
  .select(['p.id', 'a.species', 'q.one'])
  .execute()

The generated SQL (PostgreSQL):

select "p".id, "a"."species", "q"."one"
from
  "person" as "p",
  (select "pet"."species" from "pet") as a,
  (select 1 as one) as "q"
Type parameters
Type parameter
TE extends string
Parameters
ParameterType
fromTE[]
Returns

SelectQueryBuilder<DB, ExtractTableAlias<DB, TE>, {}>

Inherited from

Kysely.selectFrom

selectFrom(from)
selectFrom<TE>(from): SelectQueryBuilder<From<DB, TE>, ExtractAliasFromTableExpression<DB, TE>, {}>
Type parameters
Type parameter
TE extends string | AliasedExpression<any, any> | AliasedExpressionFactory<DB, keyof DB>
Parameters
ParameterType
fromTE[]
Returns

SelectQueryBuilder<From<DB, TE>, ExtractAliasFromTableExpression<DB, TE>, {}>

Inherited from

Kysely.selectFrom

selectFrom(from)
selectFrom<TE>(from): SelectQueryBuilder<DB, ExtractTableAlias<DB, TE>, {}>
Type parameters
Type parameter
TE extends string
Parameters
ParameterType
fromTE
Returns

SelectQueryBuilder<DB, ExtractTableAlias<DB, TE>, {}>

Inherited from

Kysely.selectFrom

selectFrom(from)
selectFrom<TE>(from): SelectQueryBuilder<DB & PickTableWithAlias<DB, TE>, ExtractTableAlias<DB, TE>, {}>
Type parameters
Type parameter
TE extends ${string} as ${string}
Parameters
ParameterType
fromTE
Returns

SelectQueryBuilder<DB & PickTableWithAlias<DB, TE>, ExtractTableAlias<DB, TE>, {}>

Inherited from

Kysely.selectFrom

selectFrom(from)
selectFrom<TE>(from): SelectQueryBuilder<From<DB, TE>, ExtractAliasFromTableExpression<DB, TE>, {}>
Type parameters
Type parameter
TE extends string | AliasedExpression<any, any> | AliasedExpressionFactory<DB, keyof DB>
Parameters
ParameterType
fromTE
Returns

SelectQueryBuilder<From<DB, TE>, ExtractAliasFromTableExpression<DB, TE>, {}>

Inherited from

Kysely.selectFrom

transaction()

transaction(): TransactionBuilder<DB>

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 TransactionBuilder.execute | 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

const catto = await db.transaction().execute(async (trx) => {
  const jennifer = await trx.insertInto('person')
    .values({
      first_name: 'Jennifer',
      last_name: 'Aniston',
    })
    .returning('id')
    .executeTakeFirstOrThrow()
 
  await someFunction(trx, jennifer)
 
  return await trx.insertInto('pet')
    .values({
      user_id: jennifer.id,
      name: 'Catto',
      species: 'cat'
    })
    .returning('*')
    .executeTakeFirst()
})

Setting the isolation level:

await db
  .transaction()
  .setIsolationLevel('serializable')
  .execute(async (trx) => {
    await doStuff(trx)
  })
Returns

TransactionBuilder<DB>

Inherited from

Kysely.transaction

updateTable()

updateTable(table)
updateTable<TR>(table): UpdateQueryBuilder<DB, ExtractTableAlias<DB, TR>, ExtractTableAlias<DB, TR>, UpdateResult>

Creates an update query.

See the UpdateQueryBuilder.where method for examples on how to specify a where clause for the update operation.

See the UpdateQueryBuilder.set method for examples on how to specify the updates.

The return value of the query is an UpdateResult.

Examples

const result = await db
  .updateTable('person')
  .set({ first_name: 'Jennifer' })
  .where('person.id', '=', 1)
  .executeTakeFirst()
 
console.log(result.numUpdatedRows)
Type parameters
Type parameter
TR extends string
Parameters
ParameterType
tableTR
Returns

UpdateQueryBuilder<DB, ExtractTableAlias<DB, TR>, ExtractTableAlias<DB, TR>, UpdateResult>

Inherited from

Kysely.updateTable

updateTable(table)
updateTable<TR>(table): UpdateQueryBuilder<DB & PickTableWithAlias<DB, TR>, ExtractTableAlias<DB, TR>, ExtractTableAlias<DB, TR>, UpdateResult>
Type parameters
Type parameter
TR extends ${string} as ${string}
Parameters
ParameterType
tableTR
Returns

UpdateQueryBuilder<DB & PickTableWithAlias<DB, TR>, ExtractTableAlias<DB, TR>, ExtractTableAlias<DB, TR>, UpdateResult>

Inherited from

Kysely.updateTable

updateTable(table)
updateTable<TR>(table): UpdateQueryBuilder<From<DB, TR>, ExtractAliasFromTableExpression<DB, TR>, ExtractAliasFromTableExpression<DB, TR>, UpdateResult>
Type parameters
Type parameter
TR extends string | AliasedExpression<any, any>
Parameters
ParameterType
tableTR
Returns

UpdateQueryBuilder<From<DB, TR>, ExtractAliasFromTableExpression<DB, TR>, ExtractAliasFromTableExpression<DB, TR>, UpdateResult>

Inherited from

Kysely.updateTable

with()

with<N, E>(name, expression): QueryCreatorWithCommonTableExpression<DB, N, E>

Creates a with query (Common Table Expression).

Examples

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.

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()
Type parameters
Type parameter
N extends string
E extends CommonTableExpression<DB, N>
Parameters
ParameterType
nameN
expressionE
Returns

QueryCreatorWithCommonTableExpression<DB, N, E>

Inherited from

Kysely.with

withPlugin()

withPlugin(plugin): Kysely<DB>

Returns a copy of this Kysely instance with the given plugin installed.

Parameters
ParameterType
pluginKyselyPlugin
Returns

Kysely<DB>

Inherited from

Kysely.withPlugin

withRecursive()

withRecursive<N, E>(name, expression): QueryCreatorWithCommonTableExpression<DB, N, E>

Creates a recursive with query (Common Table Expression).

See the with method for examples and more documentation.

Type parameters
Type parameter
N extends string
E extends RecursiveCommonTableExpression<DB, N>
Parameters
ParameterType
nameN
expressionE
Returns

QueryCreatorWithCommonTableExpression<DB, N, E>

Inherited from

Kysely.withRecursive

withSchema()

withSchema(schema): 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.

See this recipe 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):

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):

select "p"."name" from "mammals"."pet" as "p"
Parameters
ParameterType
schemastring
Returns

QueryCreator<DB>

Inherited from

Kysely.withSchema

withTables()

withTables<T>(): Kysely<DB & T>

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:

Type parameters
Type parameter
T extends Record<string, Record<string, any>>
Returns

Kysely<DB & T>

Inherited from

Kysely.withTables

Example
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()

withoutPlugins()

withoutPlugins(): Kysely<DB>

Returns a copy of this Kysely instance without any plugins.

Returns

Kysely<DB>

Inherited from

Kysely.withoutPlugins

Database

Properties

Account

Account: AdapterAccount;

Session

Session: AdapterSession;

User

User: AdapterUser;

VerificationToken

VerificationToken: VerificationToken;

Codegen

type Codegen: { [K in keyof Database]: { [J in keyof Database[K]]: unknown } };

format

const format: {
  from: T;
  to: T;
};

Type declaration

from()

Type parameters
Type parameter
T
Parameters
ParameterType
object?Record<string, any>
Returns

T

to()

Type parameters
Type parameter
T
Parameters
ParameterType
objectRecord<string, any>
Returns

T

KyselyAdapter()

KyselyAdapter(db): Adapter

Parameters

ParameterType
dbKysely<Database>

Returns

Adapter

Client@auth/mikro-orm-adapter

About Auth.js

Download

Acknowledgements

Auth.js © Balázs Orbán and Team - 2024