express-mysql-session
Advanced tools
A MySQL session store for express.js. Compatible with express-session.
Add to your application via npm:
npm install express-mysql-session --save
This will install express-mysql-session and add it to your application's package.json file.
Potential gotchas and other important information goes here.
This module creates a database table to save session data. This data is stored in a MySQL text field with the utf8mb4 collation - added in MySQL 5.5.3. The reason for this is to fully support the utf8 character set. If you absolutely must use an older version of MySQL, create your sessions table before initializing the MySQLStore.
This module will work with MariaDB, but you must follow the usage examples in this readme found here and here. The mariadb module is not supported - please use the mysql2 module instead to create a connection or pool to your MariaDB instance.
Use with your express session middleware, like this:
const express = require('express');
const app = module.exports = express();
const session = require('express-session');
const MySQLStore = require('express-mysql-session')(session);
const options = {
host: 'localhost',
port: 3306,
user: 'session_test',
password: 'password',
database: 'session_test'
};
const sessionStore = new MySQLStore(options);
app.use(session({
key: 'session_cookie_name',
secret: 'session_cookie_secret',
store: sessionStore,
resave: false,
saveUninitialized: false
}));
// Optionally use onReady() to get a promise that resolves when store is ready.
sessionStore.onReady().then(() => {
// MySQL session store ready for use.
console.log('MySQLStore ready');
}).catch(error => {
// Something went wrong.
console.error(error);
});
The session store will internally create a mysql2 connection pool.
The sessions database table should be automatically created, when using default options. If for whatever reason the table is not created, you can find the schema here.
To pass in an existing MySQL database connection or pool, you would do something like this:
const mysql = require('mysql2/promise');
const session = require('express-session');
const MySQLStore = require('express-mysql-session')(session);
const options = {
host: 'localhost',
port: 3306,
user: 'db_user',
password: 'password',
database: 'db_name'
};
const connection = mysql.createConnection(options); // or mysql.createPool(options);
const sessionStore = new MySQLStore({}/* session store options */, connection);
To cleanly close the session store:
sessionStore.close().then(() => {
// Successfuly closed the MySQL session store.
console.log('MySQLStore closed');
}).catch(error => {
// Something went wrong.
console.error(error);
});
Here is a list of all available options:
const options = {
// Host name for database connection:
host: 'localhost',
// Port number for database connection:
port: 3306,
// Database user:
user: 'session_test',
// Password for the above database user:
password: 'password',
// Database name:
database: 'session_test',
// Whether or not to automatically check for and clear expired sessions:
clearExpired: true,
// How frequently expired sessions will be cleared; milliseconds:
checkExpirationInterval: 900000,
// The maximum age of a valid session; milliseconds:
expiration: 86400000,
// Whether or not to create the sessions database table, if one does not already exist:
createDatabaseTable: true,
// Whether or not to end the database connection when the store is closed.
// The default value of this option depends on whether or not a connection was passed to the constructor.
// If a connection object is passed to the constructor, the default value for this option is false.
endConnectionOnClose: true,
// Whether or not to disable touch:
disableTouch: false,
charset: 'utf8mb4_bin',
schema: {
tableName: 'sessions',
columnNames: {
session_id: 'session_id',
expires: 'expires',
data: 'data'
}
}
};
Additionally, the following options will be passed thru to the mysql2 module's createPool method:
waitForConnections, connectionLimit, maxIdle, idleTimeout, queueLimitIt is possible to use a custom schema for your sessions database table. This can be useful if you want to have extra columns (e.g. "user_id"), indexes, foreign keys, etc. You could also change the type of the "data" column to a smaller or larger text type (e.g. "TINYTEXT", "LONGTEXT", "BLOB") or native "JSON" type.
Set the createDatabaseTable option to FALSE so that the session store does not automatically create a sessions table.
Use the schema option to provide the custom table and column names to the session store.
const session = require('express-session');
const MySQLStore = require('express-mysql-session')(session);
const options = {
host: 'localhost',
port: 3306,
user: 'session_test',
password: 'password',
database: 'session_test',
createDatabaseTable: false,
schema: {
tableName: 'custom_sessions_table_name',
columnNames: {
session_id: 'custom_session_id_column_name',
expires: 'custom_expires_column_name',
data: 'custom_data_column_name'
}
}
};
const sessionStore = new MySQLStore(options);
express-mysql-session uses the debug module to output debug messages to the console. To output all debug messages, run your node app with the DEBUG environment variable:
DEBUG=express-mysql-session* node your-app.js
This will output log messages as well as error messages from express-mysql-session.
There are a number of ways you can contribute:
Before you contribute code, please read through at least some of the source code for the project. I would appreciate it if any pull requests for source code changes follow the coding style of the rest of the project.
Now if you're still interested, you'll need to get your local environment configured.
First, you'll need to pull down the code from GitHub:
git clone https://github.com/chill117/express-mysql-session.git
Second, you'll need to install the project dependencies as well as the dev dependencies. To do this, simply run the following from the directory you created in step 1:
npm ci
Now, you'll need to set up a local test database:
{
host: 'localhost',
port: 3306,
user: 'session_test',
password: 'password',
database: 'session_test'
};
The test database settings are located in test/config.js
Alternatively, you can provide custom database configurations via environment variables:
DB_HOST="localhost"
DB_PORT="3306"
DB_USER="session_test"
DB_PASS="password"
DB_NAME="session_test"
Alternatively, use docker to run a temporary instance of MySQL database:
sudo docker run -it --rm \
-e MYSQL_RANDOM_ROOT_PASSWORD=yes \
-e MYSQL_DATABASE=session_test \
-e MYSQL_USER=session_test \
-e MYSQL_PASSWORD=password \
-p 3306:3306 mysql:5.7
This project includes an automated regression test suite. To run the tests:
npm test
See changelog.md
This software is MIT licensed:
A short, permissive software license. Basically, you can do whatever you want as long as you include the original copyright and license notice in any copy of the software/source. There are many variations of this license in use.
FAQs
A MySQL session store for express.js
We found that express-mysql-session demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.