Yjs PostgreSQL Persistence

Common errors

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

  cause 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

  cause 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)

  cause 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`.

Warnings

• gotcha This 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.
• breaking The 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.
• gotcha The 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.
• gotcha Properly 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.

Install

• npm install y-postgresql npm
• yarn add y-postgresql yarn
• pnpm add y-postgresql pnpm

Imports

• PostgresqlPersistence
  wrong:

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

  correct:

  import { PostgresqlPersistence } from '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`.

Quickstart

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);