demux-postgres

library4.0.1jsnpmunverified

Action handler implementation for demux-js, providing Postgres database integration for blockchain event processing. Current stable version 4.0.1, maintained as part of EOSIO demux ecosystem. Releases are infrequent, with v4 focusing on TypeScript and updated demux peer dependency. Key differentiator: directly maps blockchain actions to Postgres state updates via SQL statements, offering persistence and queryability compared to in-memory handlers.

database

npm install demux-postgres

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · DEMUX-POSTGRES

demux-postgres

databasejavascriptv4.0.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PostgresActionHandler

✓ import { PostgresActionHandler } from 'demux-postgres'

✗ const { PostgresActionHandler } = require('demux-postgres')

ESM-only since v4; TypeScript types included. CommonJS require may still work but recommended to use import.

PostgresActionWatcher

✓ import { PostgresActionWatcher } from 'demux-postgres'

Named export; used for watching blockchain state changes.

PostgresDatabaseInitialization

✓ import { PostgresDatabaseInitialization } from 'demux-postgres'

✗ import { PostgresDatabaseInitialization } from 'demux-postgres/src/initialize'

Default export warning: do NOT import from source path, use package root.

Initialize PostgresActionHandler with a pg.Pool connection, then integrate with BaseActionWatcher for blockchain action processing.

import { PostgresActionHandler } from 'demux-postgres'; import { BaseActionWatcher } from 'demux'; const handler = new PostgresActionHandler({ dbSchema: 'public', migrationTable: 'migrations', handlerVersion: new HandlerVersion({ versionName: 'v1', effects: [myEffect], migrator: myMigrator, }), updater: async (db, action) => { await db.query(`UPDATE accounts SET balance = $1 WHERE id = $2`, [action.payload.balance, action.payload.id]); }, db: new pg.Pool({ connectionString: process.env.DATABASE_URL }), }); const watcher = new BaseActionWatcher({ actionHandler: handler, pollInterval: 1000 }); watcher.watch();

Debug

Known issues

breakingv4 dropped CommonJS support; ESM-only. Old require() calls will throw.

fix

Use import syntax and ensure package.json type: module or .mjs extension.

affects: >=4.0.0

deprecatedDeprecated: PostgresDatabaseInitialization is no longer needed after v3; use handler.migrate() instead.

fix

Remove PostgresDatabaseInitialization calls, call handler.migrate() on the handler instance.

affects: >=4.0.0

gotchaThe 'db' config expects a pg.Pool instance, not a client; connecting with a single client may cause connection exhaustion.

fix

Use new pg.Pool() and pass the pool object; do not use pg.Client.

affects: >=1.0.0

breakingHandlerVersion constructor changed in v4: requires versionName and effects properties.

fix

Update HandlerVersion instantiation to pass object with versionName and effects.

affects: >=4.0.0

gotchaMigration table name defaults to 'migrations' but schema must exist; auto-creation of schema is not performed.

fix

Create schema before running migrations, or set migrationTable to include schema (e.g., 'public.migrations').

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'demux'

Missing peer dependency demux.

fix

npm install demux@4.0.0

TypeError: handler.migrate is not a function

Using deprecated PostgresDatabaseInitialization instead of handler.migrate().

fix

Replace initializer import with handler.migrate() call.

Error: Must use import to load ES Module: demux-postgres

Trying to require() the ESM-only package in a CommonJS context.

fix

Set type: module in package.json or use .mjs extension, and use import.

TypeError: pg.Pool is not a constructor

Incorrect import of pg module (e.g., import pg from 'pg' vs import { Pool } from 'pg').

fix

Use 'import { Pool } from 'pg'' or 'const { Pool } = require('pg')' if using CJS.

Upgrade

Version history

4.0.1latest on npm

Audit

Dependencies

demuxrequiredpeer dependency required for handler interface and state management

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/EOSIO/demux-js-postgres ↗

packagedemux-postgres ↗

homepagehttps://github.com/EOSIO/demux-js-postgres#readme ↗