express-sqlite

An SQLite-based session store for use with express-session, using better-sqlite3, with TypeScript support.

Table of contents

• Usage
• SQLiteStore constructor
• Types
  • StoreOptions
• Sessions table structure
• Methods

Usage

import express from "express";
import session from "express-session";
import { SQLiteStore } from "express-sqlite";

const app = express();

// With required arguments only
const store = new SQLiteStore("sessions.db");

// With customized options
const store = new SQLiteStore("sessions.db", {
  tableName: "Sessions",
  databaseOptions: { fileMustExist: false },
  wal: true,
});

app.use(
  session({ store, secret: "your-secret-key", cookie: { secure: true } }),
);

SQLiteStore constructor

class SQLiteStore extends Store {
  constructor(database: StoreDatabase, storeOptions?: StoreOptions) {}
}

Argument	Type	Default value	Description
database	StoreDatabase	Required argument	The SQLite database to store sessions in. Can be specified as a file path, a Buffer, or a BetterSqlite3.Database instance.
storeOptions	StoreOptions	{ tableName: "Sessions", wal: true }	Options for initializing the store.

StoreOptions

Property	Type	Description
databaseOptions	Database.Options	Options passed to better-sqlite3's Database constructor. Additionally, its fileMustExist property also controls whether the directory structure leading to the database file is created by this library, if it doesn't exist.
tableName	string	Name of the table to store sessions in.
wal	boolean	Controls the usage of SQLite's WAL-mode.

Types

Type	Definition	Description
ErrorOnlyCallback	(error?: unknown) => void	Callback function with only the error argument. Used for store methods that don't return any data on success (clear, destroy, set).
SessionDataWithId	SessionData & { id: string }	express-session's SessionData type extended with an id field that holds the session ID. Used for the all method.
StoreDatabase	string | Buffer | BetterSqlite3.Database	A union type for the values that can be used in the SQLiteStore constructor to specify the database used for storing sessions.

Sessions table structure

Column name	Data type	Constraints
id	TEXT	PRIMARY KEY
data	TEXT	NOT NULL

Note

If the table doesn't exist in the database, it's automatically created.

Methods

• all(callback: (error: unknown, sessions?: SessionDataWithId[]) => void): void

  Retrieves all sessions in the store, including their IDs.

• destroy(sid: string, callback?: ErrorOnlyCallback): void

  Removes the session with the given ID (sid), if it exists. No error is thrown if there is no such session.

• clear(callback?: ErrorOnlyCallback): void

  Removes all sessions from the store.

• length(callback: (error: unknown, length?: number) => void): void

  Returns the number of active sessions (length).

• get(sid: string, callback: (error: unknown, session?: SessionData | null) => void): void

  Retrieves a session by its ID (sid). session is null if there is no such session in the store.

• set(sid: string, session: SessionData, callback?: ErrorOnlyCallback): void

  Saves a session with the given ID (sid). If such a session already exists, its data will be overwritten.

Note

If an error occurs in any of the methods, the callback function will only have its error argument defined.