prisma-session-store
An express session store implementation, for the Prisma (2) Framework.
Want the flexibility and scalability of a Prisma GraphQL data layer, along with the optionality and maturity of the Express ecosystem - but concerned about JWT or Paseto tokens for session management (see cautions posted here, here, here, here, and here)?
prisma-session-store
simplifies access to tried-and-true express session management via Prisma's database client.
Based on: memorystore, by roccomuso
Usage
JavaScript (CommonJS)
const expressSession = require('express-session');
const { PrismaSessionStore } = require('@quixo3/prisma-session-store');
...
app.use(
expressSession({
cookie: {
maxAge: 7 * 24 * 60 * 60 * 1000 // ms
},
secret: 'a santa at nasa',
store: new PrismaSessionStore(
prisma,
{
checkPeriod: 2 * 60 * 1000, //ms
dbRecordIdIsSessionId: true,
dbRecordIdFunction: undefined,
}
)
})
);
...
TypeScript
import expressSession from 'express-session';
import { PrismaSessionStore } from '@quixo3/prisma-session-store';
...
app.use(
expressSession({
cookie: {
maxAge: 7 * 24 * 60 * 60 * 1000 // ms
},
secret: 'a santa at nasa',
store: new PrismaSessionStore(
prisma,
{
checkPeriod: 2 * 60 * 1000, //ms
dbRecordIdIsSessionId: true,
dbRecordIdFunction: undefined,
}
)
})
);
...
Setup
Install
Install @quixo3/prisma-session-store
(and express-session
, if not already installed):
NPM
$ npm install @quixo3/prisma-session-store express-session
yarn
$ yarn add @quixo3/prisma-session-store express-session
Prisma
Model
From your prisma.schema file, include a session model:
model Session {
id String @id
sid String @unique
data String
expiresAt DateTime
}
Don't forget to run prisma generate
to generate your PrismaClient.
Types - GraphQL Nexus
If you are using @nexus/schema you can define your Session type:
...
{
name: 'Session',
definition(t) {
t.model.id();
t.model.sid();
t.model.data();
t.model.expiresAt();
}
}
...
Database
If you are using Prisma's migrations you can simply run prisma migrate dev
to migrate your database.
If you are using something other then prisma
then you will need to manage the migrations yourself and you check the Prisma Documentation on the subject if you need help.
MySQL
If you are using MySQL as your datasource provider you may also need change the type of your data column to be TEXT:
USE your-database
ALTER TABLE Session MODIFY data TEXT;
Prisma String
properties are mapped to VARCHAR(191)
by default. Session data can be larger than 191 characters so updating the type to TEXT
prevents errors when creating and updating sessions. If you know your session data will not exceed 191 characters you can skip this step or if you know your maximum size you can use VARCHAR(YOUR_MAX_SIZE)
If you are using a version of Prisma that supports migrating with native types you can use a type annotation in your schema.prisma
file instead of manually modifying your data column.
2.0.0
Migrating from versions following Following version 2.0.0
, the Session
expires
field was renamed to expiresAt
to match Prisma's naming convention for date fields.
1.0.0
Migrating from versions prior to In 1.0.0
the public API of this library was reworked. Previously the default export that was a
factory to build the PrismaSessionStore
class. In 1.0.0
a named export of the class
PrismaSessionStore
was put in place of the default export. So after updating you will need to
change your import and remove your call to the factory.
JavaScript
Before
const PrismaSessionStore = require('@quixo3/prisma-session-store')(
expressSession
);
After
const { PrismaSessionStore } = require('@quixo3/prisma-session-store');
TypeScript
Before
import prismaSessionStore from '@quixo3/prisma-session-store';
const PrismaSessionStore = prismaSessionStore(expressSession);
After
import { PrismaSessionStore } from '@quixo3/prisma-session-store';
Options
-
dbRecordIdIsSessionId
A flag indicating to use the session ID as the Prisma Record ID -
dbRecordIdFunction
A function to generate the Prisma Record ID for a given session ID
Note: If both dbRecordIdFunction and dbRecordIdIsSessionId are undefined then a random CUID will be used instead.
-
checkPeriod
Interval, in ms, at which PrismaSessionStore will automatically remove expired sessions. Disabled by default; set to something reasonable. -
ttl
"Time to live", in ms; defines session expiration time. Defaults to session.maxAge (if set), or one day (if not set). May alternatively be set to a function, of the form(options, session, sessionID) => number
. -
dispose
Called on sessions when they are dropped. Handy if you want to close file descriptors or do other cleanup tasks when sessions are no longer accessible. Called withkey, value
. It's called before actually removing the item from the internal cache, so if you want to immediately put it back in, you'll have to do that in anextTick
orsetTimeout
callback or it won't do anything. -
stale
By default, if you set amaxAge
, it'll only actually pull stale items out of the cache when youget(key)
. (That is, it's not pre-emptively doing asetTimeout
or anything.) If you setstale:true
, it'll return the stale value before deleting it. If you don't set this, then it'll returnundefined
when you try to get a stale entry, as if it had already been deleted. -
noDisposeOnSet
By default, if you set adispose()
method, then it'll be called whenever aset()
operation overwrites an existing key. If you set this option,dispose()
will only be called when a key falls out of the cache, not when it is overwritten. -
serializer
An object containingstringify
andparse
methods compatible with Javascript'sJSON
to override the serializer used. -
sessionModelName
By default, the session table is calledsessions
and the associated model issession
, but you can provide a custom model name. This should be the camelCase version of the name.
Three new options were added apart from the work that was already done by memorystore, two of them relate to logging and allow you to inject your own logger object giving you flexibility to log outputs to something like NestJS or whenever you would like, even saving them to disk if that's what you want. And the third is used for testing to round the TTL so that it can be compared do another generated ttl during the assertion.
-
logger
Where logs should be outputted to, by defaultconsole
. If set tofalse
then logging will be disabled -
loggerLevel
Determines which logging methods to enable, by defaulterror
only -
roundTTL
the amount of milliseconds to round down the TTL so that it will match another TTL generated later. Mostly used for test stability.
Methods
prisma-session-store
implements all the required, recommended and optional methods of the express-session store, plus a few more:
startInterval()
andstopInterval()
methods to start/clear the automatic check for expired.prune()
that you can use to manually remove only the expired entries from the store.shutdown()
that can be used to stop any intervals and disconnect from prisma.
Author
Krispin Leydon (kleydon), based heavily on memorystore, by roccomuso, refactored to TypeScript by wSedlacek
License
MIT