pgrls-test

library0.6.3jsnpmunverified

Code-first RLS testing for Postgres — TypeScript port of pgrls.testing (Python). Current stable version is 0.6.3, with a release cadence of minor versions every few months. Implements the cross-language Layer 1 protocol (PROTOCOL_VERSION 1). Key differentiators: per-test transactions with role and JWT-claims switching, five RLS-specific assertion helpers (assertRows, assertRejected, etc.), and works with both pg and postgres.js drivers without forking or replacing your existing Postgres client. ESM-only, requires Node.js >=20, and ships TypeScript types.

testing database

npm install pgrls-test

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PGRLS-TEST

pgrls-test

testingjavascriptv0.6.3

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.

PgrlsTestClient

✓ import { PgrlsTestClient } from 'pgrls-test'

✗ import PgrlsTestClient from 'pgrls-test'

Named export only; no default export. ESM-only, no CommonJS support.

pgDriver

✓ import { pgDriver } from 'pgrls-test'

✗ const { pgDriver } = require('pgrls-test')

Named export; ESM-only since v0.6. Requires pg peer dependency.

postgresJsDriver

✓ import { postgresJsDriver } from 'pgrls-test'

✗ const postgresJsDriver = require('pgrls-test').postgresJsDriver

Named export; ESM-only. Requires postgres.js peer dependency.

Demonstrates per-test transaction, seeding, role switching with JWT claims, and two RLS-specific assertions using the pg driver.

import { Client } from 'pg'; import { PgrlsTestClient, pgDriver } from 'pgrls-test'; const pg = new Client({ connectionString: process.env.DATABASE_URL ?? '' }); await pg.connect(); const client = new PgrlsTestClient(pgDriver(pg)); try { await client.transaction(async () => { await client.seed('public.users', [ { id: 1, tenant_id: 'tenant-a' }, { id: 2, tenant_id: 'tenant-b' }, ]); await client.asRole( 'app_authenticated', { claims: { sub: 'user-1', tenant_id: 'tenant-a' } }, async () => { await client.assertRows( 'SELECT id FROM public.users', { count: 1 }, ); await client.assertRejected( "INSERT INTO public.users (id, tenant_id) VALUES (3, 'tenant-c')", ); }, ); }); } finally { await pg.end(); }

Debug

Known issues

breakingThe `close()` method on PgrlsTestClient now releases pinned connections for postgres.js driver; previously you had to manage pool manually.

fix

Call `client.close()` after test block for postgres.js driver.

affects: >=0.6.2

deprecatedThe `postgresJsDriver` adapter no longer requires `{ max: 1 }` pool config; now uses `sql.reserve()` internally.

fix

Remove `{ max: 1 }` from postgres() call; ensure call `client.close()` to release the pinned connection.

affects: >=0.6.2

gotchaESM-only: package exports only ES modules; require() will throw.

fix

Use dynamic import() or ensure project is ESM ("type": "module" in package.json).

affects: >=0.6.0

gotchaRequires Node.js >=20; older versions may fail due to ESM features.

fix

Upgrade Node.js to version 20 or later.

affects: >=0.6.0

gotchaMust call `client.transaction()` to wrap assertions; assertions outside a transaction will silently no-op.

fix

Always wrap assertion logic in a transaction block.

affects: >=0.1.0

gotchaThe `pgDriver` function expects a `pg.Client` instance, not a `pg.Pool`. Using a pool directly may cause unexpected behavior across connections.

fix

Use `pool.connect()` to obtain a dedicated client for the test client.

affects: >=0.1.0

Errors

Common errors & fixes

SyntaxError: Cannot use import statement outside a module

Using require or non-ESM Node.js environment

fix

Add "type": "module" to package.json or use .mjs extension.

Error: No pg driver found. Install 'pg' or 'postgres' as a peer dependency.

Missing required driver package

fix

npm install --save-dev pg or npm install --save-dev postgres

Error: client.assertRows must be called inside a transaction

Assertion called outside transaction block

fix

Wrap the call in client.transaction(async () => { ... })

TypeError: postgresJsDriver is not a function

Incorrect import or wrong driver

fix

Ensure correct import: import { postgresJsDriver } from 'pgrls-test'

Upgrade

Version history

0.6.3latest on npm

Audit

Dependencies

pgoptionalOptional peer dependency for node-postgres driver

postgresoptionalOptional peer dependency for postgres.js driver

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/pgrls/pgrls ↗

packagepgrls-test ↗

homepagehttps://github.com/pgrls/pgrls ↗