bgio-postgres

library1.0.16jsnpmunverified

PostgreSQL storage adapter for boardgame.io, version 1.0.16. Uses Sequelize ORM under the hood to persist game state to PostgreSQL (or other SQL databases with JSON support). Designed for boardgame.io >=0.40.0, ships TypeScript types, and requires Node >=20. Different from the built-in in-memory or flat-file stores by providing a scalable, persistent database backend suitable for production multiplayer games. Release cadence is irregular; latest update is stable but the package is relatively small with limited maintenance.

database

npm install bgio-postgres

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BGIO-POSTGRES

bgio-postgres

databasejavascriptv1.0.16

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.

PostgresStore

✓ import { PostgresStore } from 'bgio-postgres'

✗ const PostgresStore = require('bgio-postgres')

ESM-only; named export. CommonJS require will fail because package is type: module.

PostgresStore (with URI)

✓ const db = new PostgresStore('postgresql://user:pass@host/db')

✗ const db = new PostgresStore({ uri: 'postgresql://user:pass@host/db' })

First argument can be a URI string or an options object. Passing uri as a property inside an object is not supported.

Sequelize options passthrough

✓ const db = new PostgresStore(uri, { logging: false })

✗ const db = new PostgresStore(uri, { logging: false }, extraArg)

Only two arguments: first is URI or options, second is optional Sequelize options. Additional arguments are ignored.

Shows how to create a PostgresStore instance with a connection URI and use it with boardgame.io server.

import { Server } from 'boardgame.io/server'; import { PostgresStore } from 'bgio-postgres'; import { myGame } from './game'; const db = new PostgresStore( process.env.DATABASE_URL ?? 'postgresql://localhost:5432/boardgameio' ); const server = Server({ games: [myGame], db }); server.run(8000);

Debug

Known issues

breakingRequires Node >=20; lower versions cause runtime errors.

fix

Upgrade Node to version 20 or higher.

affects: >=1.0.0

breakingPeer dependency boardgame.io >=0.40.0; older versions incompatible.

fix

Upgrade boardgame.io to version 0.40.0 or higher.

affects: >=1.0.0

deprecatedUsing Sequelize v6; future updates may require migration.

fix

Monitor for v2 breaking changes if Sequelize v7 becomes default.

affects: >=1.0.0

gotchaPassing a URI as the first argument and an options object as second is supported, but the options object merges with the internal Sequelize constructor; conflict in 'host' or 'port' may produce errors if both URI and options specify them.

fix

Either use URI alone or options alone; do not mix URI with options that override connection parameters.

affects: >=1.0.0

gotchaJSON data type is used for game state; not all databases support it. MySQL and SQLite work, but other dialects may fail.

fix

Ensure your database engine supports JSON (Postgres, MySQL, SQLite). For others, test thoroughly.

affects: >=1.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/bgio-postgres/src/index.js not supported.

Package is ESM-only; using CommonJS require() fails.

fix

Use import syntax or set type: module in package.json. For Node <20, upgrade Node.

SequelizeValidationError: String or number is required for host

Passing an options object without a host field when using URI as first argument (or vice versa) causes missing host.

fix

Provide either a full URI as first argument or an options object with all required fields (database, username, password, host).

Error: Cannot find module 'boardgame.io'

Peer dependency boardgame.io is not installed.

fix

Install boardgame.io: npm install boardgame.io@>=0.40.0

Upgrade

Version history

1.0.16latest on npm

Audit

Dependencies

boardgame.iorequiredpeer dependency for Server and game types

sequelizerequiredORM used internally for database connectivity

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/janKir/bgio-postgres ↗

packagebgio-postgres ↗

homepagehttps://github.com/janKir/bgio-postgres#readme ↗