pgsql-test 2.0.4 → 2.0.6

package/README.md

@@ -79,6 +79,16 @@ afterAll(() => teardown());
 
 ## `getConnections()` Overview
 
+```ts
+import { getConnections } from 'pgsql-test';
+
+// Complete object destructuring
+const { pg, db, admin, teardown, manager } = await getConnections();
+
+// Most common pattern
+const { db, teardown } = await getConnections();
+```
+
 The `getConnections()` helper sets up a fresh PostgreSQL test database and returns a structured object with:
 
 * `pg`: a `PgTestClient` connected as the root or superuser — useful for administrative setup or introspection
@@ -97,6 +107,19 @@ The `PgTestClient` returned by `getConnections()` is a fully-featured wrapper ar
 
 ## `PgTestClient` API Overview
 
+```ts
+let pg: PgTestClient;
+let teardown: () => Promise<void>;
+
+beforeAll(async () => {
+  ({ pg, teardown } = await getConnections());
+});
+
+beforeEach(() => pg.beforeEach());
+afterEach(() => pg.afterEach());
+afterAll(() => teardown());
+```
+
 The `PgTestClient` returned by `getConnections()` wraps a `pg.Client` and provides convenient helpers for query execution, test isolation, and context switching.
 
 ### Common Methods
@@ -150,6 +173,25 @@ test('user count starts at 2', async () => {
 
 ### 🔐 Role-Based Context
 
+
+The `pgsql-test` framework provides powerful tools to simulate authentication contexts during tests, which is particularly useful when testing Row-Level Security (RLS) policies.
+
+#### Setting Test Context
+
+Use `setContext()` to simulate different user roles and JWT claims:
+
+```ts
+db.setContext({
+  role: 'authenticated',
+  'jwt.claims.user_id': '123',
+  'jwt.claims.org_id': 'acme'
+});
+```
+
+This applies the settings using `SET LOCAL` statements, ensuring they persist only for the current transaction and maintain proper isolation between tests.
+
+#### Testing Role-Based Access
+
 ```ts
 describe('authenticated role', () => {
   beforeEach(async () => {
@@ -166,6 +208,22 @@ describe('authenticated role', () => {
 });
 ```
 
+#### Database Connection Options
+
+For non-superuser testing, use the connection options described in the [options](#getconnections-options) section. The `db.connection` property allows you to customize the non-privileged user account for your tests.
+
+Use `setContext()` to simulate Role-Based Access Control (RBAC) during tests. This is useful when testing Row-Level Security (RLS) policies. Your actual server should manage role/user claims via secure tokens (e.g., setting `current_setting('jwt.claims.user_id')`), but this interface helps emulate those behaviors in test environments.
+
+#### Common Testing Scenarios
+
+This approach enables testing various access patterns:
+- Authenticated vs. anonymous user access
+- Per-user data filtering
+- Admin privilege bypass behavior
+- Custom claim-based restrictions (organization membership, admin status)
+
+> **Note:** While this interface helps simulate RBAC for testing, your production server should manage user/role claims via secure authentication tokens, typically by setting values like `current_setting('jwt.claims.user_id')` through proper authentication middleware.
+
 ### 🔌 SQL File Seeding
 
 Use `.sql` files to set up your database state before tests:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgsql-test",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "author": "Dan Lynch <pyramation@gmail.com>",
   "description": "PostgreSQL Testing in TypeScript",
   "main": "index.js",
@@ -42,5 +42,5 @@
     "pg": "^8.16.0",
     "pg-copy-streams": "^6.0.6"
   },
-  "gitHead": "b347f01f28aa33c195f78d911eab8757777b0c88"
+  "gitHead": "9ca7885acaf53b419b6c589f739011e047dd6954"
 }