pgreflex

library0.0.19jsnpmunverified

pgreflex (v0.0.19) is a reactive Postgres library that integrates with tRPC and Drizzle ORM to automatically reflect database changes in the frontend. It uses PostgreSQL logical replication via the pg_output plugin to listen to WAL changes and sends invalidations to tRPC procedures. Inspired by Convex, it provides granular, automatic invalidation without manual cache management. Requires REPLICA IDENTITY FULL for correct updates. Currently in early development with rapid releases; performance overhead is sub-1ms in same datacenter. Differentiators: works with any Postgres + tRPC + Drizzle stack, and aims for Neon DB compatibility.

database realtime

npm install pgreflex

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PGREFLEX

pgreflex

databasejavascriptv0.0.19

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.

createPgReflexServer

✓ import { createPgReflexServer } from 'pgreflex';

✗ const { createPgReflexServer } = require('pgreflex');

ESM-only package; CommonJS require will fail. Package is TypeScript-native.

default

✓ import pgreflex from 'pgreflex';

Default export exists but is undocumented; prefer named exports.

createPgReflexMiddleware

✓ import { createPgReflexMiddleware } from 'pgreflex';

✗ import { createMiddleware } from 'pgreflex';

Exact naming; no shorthand.

type PgReflexOptions

✓ import type { PgReflexOptions } from 'pgreflex';

Types are exported for TypeScript users.

Creates a reactive tRPC server that automatically invalidates queries when database changes occur via Postgres logical replication.

import { createPgReflexServer } from 'pgreflex'; import { drizzle } from 'drizzle-orm/node-postgres'; import { Pool } from 'pg'; import { initTRPC } from '@trpc/server'; const pool = new Pool({ connectionString: process.env.DATABASE_URL ?? '' }); const db = drizzle(pool); const t = initTRPC.create(); const reflex = createPgReflexServer({ pool, drizzle: db, t, publication: 'pgreflex_pub', slotName: 'pgreflex_slot', }); const appRouter = t.router({ users: t.procedure .use(reflex.middleware) .query(async ({ ctx }) => { return ctx.db.select().from(users).execute(); }), }); export type AppRouter = typeof appRouter;

Debug

Known issues

gotchaREPLICA IDENTITY FULL required for UPDATE and DELETE capture.

fix

ALTER TABLE <table> REPLICA IDENTITY FULL;

affects: >=0.0.1

deprecatedDefault export may be removed in future versions.

fix

Use named exports exclusively.

affects: >=0.0.1

breakingRequires PostgreSQL with logical replication enabled and wal_level=logical.

fix

Set wal_level=logical in postgresql.conf and restart Postgres.

affects: >=0.0.1

gotchaPublication and replication slot must exist before starting server, or server will attempt to create them (requires superuser privileges).

fix

Ensure either the Postgres user has replication privileges or create resources manually.

affects: >=0.0.1

gotchaAll queries inside reactive procedures must be from a single Drizzle instance passed to createPgReflexServer.

fix

Use the same db instance for all queries in the middleware.

affects: >=0.0.1

Errors

Common errors & fixes

Error: REPLICA IDENTITY FULL is required for table "users"

Table does not have REPLICA IDENTITY set to FULL for UPDATE/DELETE tracking.

fix

Run: ALTER TABLE "users" REPLICA IDENTITY FULL;

Error: logical replication requires wal_level >= logical

PostgreSQL wal_level configuration is not set to logical.

fix

Set wal_level = logical in postgresql.conf and restart the server.

Error: must be superuser or replication role to create replication slot

Postgres user lacks privileges to create replication slots.

fix

Grant REPLICATION privilege: ALTER USER your_user WITH REPLICATION; or create slot manually.

Upgrade

Version history

0.0.19latest on npm

Audit

Dependencies

@trpc/serverrequiredPeer dependency for tRPC integration

drizzle-ormrequiredPeer dependency for Drizzle ORM integration

Agent activity

28 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/moritzuehling/pgreflex ↗

packagepgreflex ↗

homepagehttps://github.com/moritzuehling/pgreflex ↗