y-postgresql

library1.0.1jsnpmunverified

y-postgresql is a community-maintained PostgreSQL database adapter designed to provide persistent storage for Yjs documents, commonly used in conjunction with a `y-websocket` server for real-time collaborative applications. As of version `1.0.1`, it offers features for storing Yjs updates and retrieving full document states from PostgreSQL. The package differentiates itself by providing a robust, battle-tested persistence solution for PostgreSQL users within the Yjs ecosystem, handling the serialization and deserialization of Yjs document updates directly. While it is not officially supported by the Yjs core team, it maintains compatibility with recent Yjs versions and provides configurable options like table naming, flush size for merging updates, and indexing for performance tuning. Release cadence is independent of Yjs core, typically driven by community contributions and specific feature requirements or bug fixes related to PostgreSQL integration.

database

npm install y-postgresql

github ↗package ↗

INSTALL

IMPORT

SIG · Y-POSTGRESQL

y-postgresql

databasejavascriptv1.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

PostgresqlPersistence

✓ import { PostgresqlPersistence } from 'y-postgresql';

✗ const PostgresqlPersistence = require('y-postgresql');

The library is primarily ESM-first, requiring Node.js 16+ for direct `import` statements. Attempting to `require` it in a CommonJS context without proper transpilation or configuration will fail.

PostgresqlPersistenceOptions

✓ import type { PostgresqlPersistenceOptions } from 'y-postgresql';

Type import for configuring the persistence instance, useful for TypeScript projects.

PostgresqlConnectionOptions

✓ import type { PostgresqlConnectionOptions } from 'y-postgresql';

Type import for configuring the underlying PostgreSQL connection, based on `pg.PoolConfig`.

This example sets up a basic `y-websocket` server and integrates `y-postgresql` for persistent storage of Yjs documents in a PostgreSQL database, demonstrating connection, state binding, and update storage.

import 'dotenv/config'; import http from 'http'; import { WebSocketServer } from 'ws'; import * as Y from 'yjs'; // Assuming these utilities are available from y-websocket or a local setup import { setPersistence, setupWSConnection } from './websocket/utils.js'; import { PostgresqlPersistence } from 'y-postgresql'; const server = http.createServer((request, response) => { response.writeHead(200, { 'Content-Type': 'text/plain' }); response.end('okay'); }); const wss = new WebSocketServer({ server }); wss.on('connection', setupWSConnection); // Use the y-websocket setup utility async function startPersistence() { const pgdb = await PostgresqlPersistence.build( { host: process.env.PG_HOST ?? 'localhost', port: parseInt(process.env.PG_PORT ?? '5432', 10), database: process.env.PG_DATABASE ?? 'yjs_db', user: process.env.PG_USER ?? 'postgres', password: process.env.PG_PASSWORD ?? '', }, { tableName: 'yjs-documents', useIndex: true, flushSize: 200 }, ); setPersistence({ bindState: async (docName, ydoc) => { const persistedYdoc = await pgdb.getYDoc(docName); Y.applyUpdate(ydoc, Y.encodeStateAsUpdate(persistedYdoc)); ydoc.on('update', async (update: Uint8Array) => { pgdb.storeUpdate(docName, update); }); }, writeState: async (docName, ydoc) => { // Optional: Ensure all updates are flushed before document destroy return new Promise((resolve) => resolve()); }, }); server.listen(process.env.PORT ?? 8080, () => { console.log(`y-websocket server with y-postgresql persistence listening on port: ${process.env.PORT ?? 8080}`); }); } startPersistence().catch(console.error);

Debug

Known issues

gotchaThis package is not officially supported by the Yjs team, meaning ongoing maintenance and compatibility with future Yjs versions are not guaranteed by the core Yjs developers.

fix

Review the source code and consider the long-term maintenance implications before relying on it for critical applications. Contributions and community support are essential.

affects: >=1.0.0

breakingThe package requires Node.js version 16 or newer. Running on older Node.js versions will result in runtime errors due to reliance on newer JavaScript features and module resolution.

fix

Upgrade your Node.js environment to version 16 or higher.

affects: >=1.0.0

gotchaThe default `useIndex: false` for the PostgreSQL table means that read operations, especially `getYDoc`, might become slow for applications with many documents or large update histories, as no index is created on the `docname` column.

fix

For better read performance, especially with a large number of documents, consider setting `useIndex: true` in the `PostgresqlPersistence.build` options. Be aware that this might slightly increase write times.

affects: >=1.0.0

gotchaProperly implementing the `bindState` and `writeState` methods within the `setPersistence` callback is crucial for ensuring data durability. Forgetting to listen to `ydoc.on('update', ...)` within `bindState` can lead to data loss if the server crashes before updates are flushed.

fix

Always ensure that `ydoc.on('update', async (update: Uint8Array) => { pgdb.storeUpdate(docName, update); })` is correctly implemented within `bindState` to persist granular updates as they occur.

affects: >=1.0.0

Errors

Common errors & fixes

Cannot find module 'y-postgresql' or its corresponding type declarations.

Incorrect module resolution for an ESM-only package in a CommonJS context, or missing Node.js 16+ environment. Could also be a TypeScript configuration issue.

fix

Ensure your `tsconfig.json` has `"module": "NodeNext"` or `"ESNext"` and `"moduleResolution": "NodeNext"`. Also, confirm Node.js version 16 or newer is in use. For JavaScript, ensure your file uses `.mjs` extension or your `package.json` has `"type": "module"`.

TypeError: PostgresqlPersistence.build is not a function

Attempting to instantiate `PostgresqlPersistence` directly with `new` instead of using the asynchronous static `build` factory method.

fix

Always use `await PostgresqlPersistence.build(...)` to create an instance, as it is an asynchronous factory method, not a direct constructor.

Error: connect ECONNREFUSED ::1:5432 (or similar database connection error)

The PostgreSQL database server is not running, is inaccessible from the application's host, or the connection parameters (host, port, user, password, database) are incorrect.

fix

Verify that your PostgreSQL server is running and accessible from the application. Double-check all connection options passed to `PostgresqlPersistence.build`, especially environment variables like `PG_HOST`, `PG_PORT`, `PG_USER`, `PG_PASSWORD`, and `PG_DATABASE`.

Upgrade

Version history

1.0.1latest on npm

Audit

Dependencies

yjsrequiredCore collaborative editing library that y-postgresql provides persistence for.

Agent activity

29 hits · last 30 days

node