Database

A database is required for storing your users and sessions. Lucia connects to your database via an adapter, which provides a set of basic, standardized querying methods that Lucia can use.

Database adapters#

There are 2 types of adapters provided by Lucia: Regular adapters, and session adapters. As the name implies, session adapters only handles queries to the session table. This is useful for when you want to store your sessions in a different database than your users, such as Redis and other memory stores.

We currently provide the following adapters:

• better-sqlite3
• libSQL
• Cloudflare D1
• Mongoose
• mysql2
• pg
• postgres
• PlanetScale serverless
• Prisma
• Redis
• Unstorage

SDKs such as @vercel/postgres and @neondatabase/serverless provide drop-in replacements for existing drivers. You can also use query builders like Drizzle ORM and Kysely since they rely on underlying drivers that we provide adapters for. Refer to these guides:

• Using @vercel/postgres
• Using Drizzle ORM
• Using Kysely

Database model#

Lucia requires 3 tables to work, which are then connected to Lucia via a database adapter. This is only the basic model and the specifics depend on the adapter. Lucia does not support default database values.

User table#

The id column must be a string type, and as such, cannot be auto-incremented integer. It can be a UUID type, but keep in mind that the default user ids generated by Lucia are not UUIDs or ObjectIDs. You cannot use default (auto-generated) database values (such as UUIDs and ObjectIDs) and IDs must be generated at runtime.

type UserSchema = {
	id: string;
} & Lucia.DatabaseUserAttributes;

In addition to the required fields shown below, you can add any additional fields to the table, in which case they should be declared in type Lucia.DatabaseUserAttributes. If you’re using an database driver adapter such as pg(), these fields must match your database columns. Keep this in mind if you’re using an ORM such as Drizzle. Lucia does not support default (auto-generated) database values.

declare namespace Lucia {
	// ...
	type DatabaseUserAttributes = {
		// required fields (i.e. id) should not be defined here
		username: string;
	};
}

Session table#

The id column must be a string type, and as such, cannot be auto-incremented integer. It can be a UUID type, but keep in mind that the default session ids generated by Lucia are not UUIDs or ObjectIDs. You cannot use default (auto-generated) database values (such as UUIDs and ObjectIDs) and IDs must be generated at runtime.

type SessionSchema = {
	id: string;
	active_expires: number;
	idle_expires: number;
	user_id: string;
} & Lucia.DatabaseSessionAttributes;

In addition to the required fields shown below, you can add any additional fields to the table, in which case they should be declared in type Lucia.DatabaseSessionAttributes. If you’re using an database driver adapter such as pg(), these fields must match your database columns. Keep this in mind if you’re using an ORM such as Drizzle. Lucia does not support default (auto-generated) database values.

declare namespace Lucia {
	// ...
	type DatabaseSessionAttributes = {
		// required fields (i.e. id) should not be defined here
		username: string;
		display_name: string;
	};
}

Key table#

The id column must be a regular string type. IDs are generated by Lucia and cannot be configured. It cannot be an auto-incremented integer, UUID, or ObjectID, nor could it be auto-generated by the database.

type KeySchema = {
	id: string;
	user_id: string;
	hashed_password: string | null;
};