@treecrdt/sync-server-postgres-node
v0.1.7
Published
Minimal TreeCRDT v0 sync server backed by a Postgres backend module.
Readme
TreeCRDT Sync Server (Node, Postgres)
Minimal TreeCRDT v0 sync server backed by a Postgres backend module.
Setup
From the repo root:
# Install workspace dependencies and create workspace links.
pnpm install
# Build all workspace packages, including the Postgres sync-server path.
pnpm buildRun
From the repo root:
# Start a disposable local Postgres instance in Docker on localhost:5432.
pnpm sync-server:postgres:db:start
# Start the TreeCRDT sync server on ws://localhost:8787 using that Postgres DB.
pnpm sync-server:postgres:localThe local database helper starts a disposable Postgres at:
postgres://postgres:[email protected]:5432/postgresStop it later with:
pnpm sync-server:postgres:db:stopIf you want a custom connection string instead:
TREECRDT_POSTGRES_URL=postgres://postgres:[email protected]:5432/postgres \
pnpm sync-server:postgresEnvironment variables:
TREECRDT_POSTGRES_URL(required)TREECRDT_POSTGRES_HOST,TREECRDT_POSTGRES_PORT,TREECRDT_POSTGRES_DB,TREECRDT_POSTGRES_USER,TREECRDT_POSTGRES_PASSWORD(optional alternative toTREECRDT_POSTGRES_URL)TREECRDT_POSTGRES_BACKEND_MODULE(default:./packages/treecrdt-postgres-napi/dist/index.js)PORT(default:8787)HOST(default:0.0.0.0)TREECRDT_IDLE_CLOSE_MS(default:30000)TREECRDT_MAX_PAYLOAD_BYTES(default:10485760)TREECRDT_SYNC_AUTH_TOKEN(optional static token, accepted asAuthorization: Bearer ...or?token=...)TREECRDT_DOC_ID_PATTERN(optional regex; deny docs that do not match)TREECRDT_ALLOW_DOC_CREATE(default:true; whenfalse, unknowndocIdvalues are denied)TREECRDT_PG_NOTIFY_ENABLED(default:true; enables LISTEN/NOTIFY fanout across server instances)TREECRDT_PG_NOTIFY_CHANNEL(default:treecrdt_sync_doc_updates)TREECRDT_RATE_LIMIT_MAX_UPGRADES(default:0, disabled; per-IP upgrades per window)TREECRDT_RATE_LIMIT_WINDOW_MS(default:60000)TREECRDT_LOG_LEVEL(debug,info,warn,error, orsilent). The default isinfo, including whenNODE_ENVis unset.TREECRDT_LOG_PRETTY(optional).trueprints human-readable lines. The default is JSON. If the pretty printer is not installed, the CLI still writes JSON.
Logs go through pino. debug includes doc open, peer fanout, ignored notifies, and each sync message the server sends or receives (sync message sent / sync message received, with the message type and counts). Message logs omit op payloads, signatures, tokens, and the Postgres URL. info includes listen, connect, disconnect, and denied upgrades. warn and error cover failed health checks, apply failures, and hook errors. Library callers of startSyncServer can pass log to enable logging.
If Postgres LISTEN fails, the server becomes unready and shuts down by default. A library caller can pass onPgNotifyFatal to take responsibility for shutdown. The CLI uses this callback to exit so a supervisor can restart the process.
Health check:
GET http://localhost:8787/health
Status endpoint:
GET http://localhost:8787/statusReturns JSON debug metadata for the running server, including readiness, package version, git SHA when available, protocol version, startup time, and key runtime settings.
WebSocket endpoint:
ws://localhost:8787/sync?docId=YOUR_DOC_ID
Client apps (TypeScript)
To connect a browser or Node client to a server like this one, the repo provides @treecrdt/sync (packages/treecrdt-sync): discovery-based URL resolution, WebSocket transport, and a SQLite-backed SyncBackend via @treecrdt/sync-sqlite. Lower-level control uses @treecrdt/sync-protocol and @treecrdt/discovery directly.
Notes
- One
docIdper WebSocket connection. - The backend module must export
createPostgresNapiSyncBackendFactory(url). - Multi-instance fanout uses Postgres LISTEN/NOTIFY on the configured channel.
- Run
pnpm discovery-server:localwhen you want a separate local bootstrap endpoint forresolveDoc.
