Awesome
koa-pg-session
This module, along with koa-generic-session is deprecated in favour of the official koa-session. If you need to access postgres using koa, please refer to its documentation here: https://github.com/koajs/session#external-session-stores
Introduction
koa-pg-session is an implementation of a session store for koa's generic session module that uses Postgres to hold the session data.
This module is ideal if you're already using Postgres as the database layer for your app, and you want to add a session store without adding another dependency like Redis.
Usage
Install the module and the generic session module using npm install koa-generic-session koa-pg-session
Require these modules in your main koa module:
var session = require('koa-generic-session');
var PgStore = require('koa-pg-session');
Use the session somewhere in your middleware:
var app = require('koa')();
var pgStore = new PgStore("postgres://username:password@host:port/database");
app.use(session({
store: pgStore
}));
Run the setup function:
pgStore.setup().then(function(){
app.listen(3000);
});
And you can then access and modify session data in your koa web app:
//Whenever we visit the server, update a counter variable in the session and render it as JSON
app.use(function *() {
this.body = this.session.counter++;
});
The Setup Function
Note that this function is new since version 2.0. setup()
must be called before session use as it is needed to
connect to the database, create the session table (if required), and schedule the table cleanup.
setup()
returns a promise, allowing you to wait for setup to finish before starting your application
(as above). While doing this is recommended, you don't need to wait for setup: you can just call pgStore.setup()
and proceed with your application code without caring about when it's finished, but you'll need to hope no sessions
will be created in the next few seconds.
Database Table
By default, the module will create a new table in the database called 'session', located in the public schema. This table has the schema:
CREATE TABLE IF NOT EXISTS public.session
id TEXT NOT NULL PRIMARY KEY,
expiry timestamp NOT NULL,
session JSON
);
If a table with this name already exists, it will be connected to, and the module will assume that these three columns exist in the table, and will fail if they do not. However you can create a table with additional columns without issue.
You can also change the name of the table as explained in the constructor options section, meaning that the module will either create a table with a different name/schema, or it will use an already existing table with this name/schema.
API
Constructor
The koa-pg-session module returns a constructor function that takes two parameters, connection
and options
:
var PgStore = require('koa-pg-session');
new PgStore(connection, options);
connection
The first parameter, connection
, can be two entirely different things.
-
The normal option is to treat
connection
as a connection object or connect string that will be passed directly into the pg-promise module. As of the writing of this,connection
can either be a connection string:"postgres://username:password@host:port/database"
Or it can be a connection object, e.g.
{ user: 'postgres', password: 'password', database: 'postgres', host: 'localhost', port: 5432 }
If you are using this option, see the pg module's documentation.
-
The other option, if you have an existing client for your postgres database, is to pass in a function that will transfer the queries to your client. The function must have the signature (query, parameters), where
query
is a string optionally containing dollar sign parameters ($1, $2 for example), andparameters
is an array of values to replace these dollar signs with.This function must return a promise (and if it doesn't already, make sure you promisify it!), as in the example below.
For example if you wanted to use an existing co-pg client (even though this library no longer uses co-pg internally), you could create a PgStore like this:
new PgSession(function(query, args){ return client.queryPromise(query, args) }, {create: true});
options
The second parameter, options
, is an object consisting of all optional keys.
schema
(string): defines the schema in which to create or find the table that we will use to store session data. Defaults topublic
table
(string): defines the name of the sessions table that we will create or find. Defaults tosession
create
(boolean): True if the module is allowed to create a new table to store sessions. Defaults totrue
cleanupTime
(number, in milliseconds): The amount of time between cleaning up the database for old sessions. Defaults to 2700000 (45 minutes)
koa-generic-session options
Additional session customisation is available through the options passed into the koa-generic-session module, which are listed here, for example we can allow empty sessions by using this middleware:
app.use(session({
store: new PgStore("postgres://username:password@host:port/database"),
allowEmpty: true
}))
Testing
You can test the module using npm test
, or just mocha
. The tests are located in test.js in the test directory.
Note that the tests now require an actual postgres server to run, and so you have to create a JS file or JSON file called config.js or config.json that exports a connection object which can be used to connect to this postgres server. The specifications for this object are explained above.
The tests will create a new schema called '__koa_pg_session_test' during the tests in the database you supply, but this will be removed once the tests have finished.