demux-js-postgres
Installation
yarn add demux-postgres
yarn add massive
npm install demux-postgres --save
npm install massive --save
Usage
MassiveActionHandler
The MassiveActionHandler
uses massive-js to interact with a Postgres database for storing internal demux state and state calculated by Updaters. Rollback of state due to forks is supported by committing all database writes to per-block databases transactions, and utilizing Cyan Audit to reverse those transactions in reverse order when needed.
Setup
In order to instantiate a MassiveActionHandler
, four arguments are needed:
-
handlerVersions
: This is an array of HandlerVersion
s. For more information, see the demux-js
documentation.
-
massiveInstance
: A connected massive database connection object. demux-js-postgress requires that you have a Postgres server running version 9.6 or greater. For more information on how to configure and instantiate this object, see the massivejs documentation.
-
dbSchema
: The name of the schema we will operate in.
-
migrationSequences
: (See next section below)
Migrations
The MassiveActionHandler
will manage all of the Postgres migrations relevant to demux operations. In addition to setting up all internal requirements (idempotently creating the specified dbSchema
and required internal tables, installing/activating Cyan Audit), you may create additional migrations that run either at initial setup, or are triggered by an action at some point in the future. This is done by writing your migrations as SQL files, loading them via the Migration
constructor, and collecting them into an array of MigrationSequence
s:
create_todo_table.sql
CREATE TABLE ${schema~}.todo (
id int PRIMARY KEY,
name text NOT NULL
);
migrationSequences.js
import { Migration } from "demux-postgres"
const createTodoTable = new Migration(
"createTodoTable",
"myschema",
"create_todo_table.sql",
)
module.exports = [{
migrations: [createTodoTable],
sequenceName: "init"
}]
You can then use this object for the migrationSequences
argument of the MassiveActionHandler
constructor.
Once you have instantiated the MassiveActionHandler
, you can set up your database via the setupDatabase()
method. If you have a MigrationSequence
with the name "init"
, then this migration sequence will run after all other internal database setup is finished.
It can be useful to trigger migrations from actions (for example, when a contract updates), much in the same way it is useful to update HandlerVersions. You may do this from an Updater's apply
function via db.migrate(<MigrationSequence.sequenceName>)
:
async function migrateDatabase(db, payload) {
await db.migrate(payload.sequenceName)
}
This is also important for maintaining determinism of data (e.g. during replays) if schema changes are needed.
Example
const { BaseActionWatcher } = require("demux")
const { MassiveActionHandler } = require("demux-postgres")
const { NodeosActionReader } = require("demux-eos")
const massive = require("massive")
const handlerVersions = require("./handlerVersions")
const migrationSequences = require("./migrationSequences")
const dbConfig = { ... }
massive(dbConfig).then((db) => {
const actionReader = new NodeosActionReader("http://my-node-endpoint", 0)
const actionHandler = new MassiveActionHandler(
handlerVersions,
db,
dbConfig.schema,
migrationSequences
)
const actionWatcher = new BaseActionWatcher(actionReader, actionHander, 500)
actionWatcher.watch()
})