pgsql-test 2.0.3 → 2.0.5

package/README.md

@@ -47,7 +47,7 @@ Part of the [LaunchQL](https://github.com/launchql) ecosystem, `pgsql-test` is b
 1. [Install](#install)
 2. [Features](#features)
 3. [Quick Start](#-quick-start)
-4. [getConnections() Overview](#getconnections-overview)
+4. [`getConnections()` Overview](#getconnections-overview)
 5. [PgTestClient API Overview](#pgtestclient-api-overview)
 6. [Usage Examples](#usage-examples)
    * [Basic Setup](#-basic-setup)
@@ -58,7 +58,7 @@ Part of the [LaunchQL](https://github.com/launchql) ecosystem, `pgsql-test` is b
    * [JSON Seeding](#️-json-seeding)
    * [Sqitch Seeding](#️-sqitch-seeding)
    * [LaunchQL Seeding](#-launchql-seeding)
-7. [Environment Overrides](#environment-overrides)
+7. [`getConnections() Options` ](#getconnections-options)
 8. [Disclaimer](#disclaimer)
 
 
@@ -150,6 +150,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 +185,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:
@@ -379,23 +414,51 @@ LaunchQL provides the best of both worlds:
 
 By maintaining Sqitch compatibility while supercharging performance, LaunchQL enables you to keep your existing migration patterns while enjoying the speed benefits of our TypeScript engine.
 
-## Environment Overrides
+## `getConnections` Options
+
+This table documents the available options for the `getConnections` function. The options are passed as a combination of `pg` and `db` configuration objects.
+
+### `db` Options (PgTestConnectionOptions)
 
-`pgsql-test` respects the following env vars for DB connectivity:
+| Option                   | Type       | Default          | Description                                                                 |
+| ------------------------ | ---------- | ---------------- | --------------------------------------------------------------------------- |
+| `db.extensions`          | `string[]` | `[]`             | Array of PostgreSQL extensions to include in the test database              |
+| `db.cwd`                 | `string`   | `process.cwd()`  | Working directory used for LaunchQL/Sqitch projects                         |
+| `db.connection.user`     | `string`   | `'app_user'`     | User for simulating RLS via `setContext()`                                  |
+| `db.connection.password` | `string`   | `'app_password'` | Password for RLS test user                                                  |
+| `db.connection.role`     | `string`   | `'anonymous'`    | Default role used during `setContext()`                                     |
+| `db.template`            | `string`   | `undefined`      | Template database used for faster test DB creation                          |
+| `db.rootDb`              | `string`   | `'postgres'`     | Root database used for administrative operations (e.g., creating databases) |
+| `db.prefix`              | `string`   | `'db-'`          | Prefix used when generating test database names                             |
 
-* `PGHOST`
-* `PGPORT`
-* `PGUSER`
-* `PGPASSWORD`
+### `pg` Options (PgConfig)
 
-Override them in your test runner or CI config:
+Environment variables will override these options when available:
 
-```yaml
-env:
-  PGHOST: localhost
-  PGPORT: 5432
-  PGUSER: postgres
-  PGPASSWORD: password
+* `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, `PGDATABASE`
+
+| Option        | Type     | Default       | Description                                     |
+| ------------- | -------- | ------------- | ----------------------------------------------- |
+| `pg.user`     | `string` | `'postgres'`  | Superuser for PostgreSQL                        |
+| `pg.password` | `string` | `'password'`  | Password for the PostgreSQL superuser           |
+| `pg.host`     | `string` | `'localhost'` | Hostname for PostgreSQL                         |
+| `pg.port`     | `number` | `5423`        | Port for PostgreSQL                             |
+| `pg.database` | `string` | `'postgres'`  | Default database used when connecting initially |
+
+### Usage
+
+```ts
+const { conn, db, teardown } = await getConnections({
+  pg: { user: 'postgres', password: 'secret' },
+  db: {
+    extensions: ['uuid-ossp'],
+    cwd: '/path/to/project',
+    connection: { user: 'test_user', password: 'secret', role: 'authenticated' },
+    template: 'test_template',
+    prefix: 'test_',
+    rootDb: 'postgres'
+  }
+});
 ```
 
 ## Disclaimer

package/connect.d.ts

@@ -1,12 +1,12 @@
 import { DbAdmin } from './admin';
-import { TestConnectionOptions, PgConfig } from '@launchql/types';
+import { PgTestConnectionOptions, PgConfig } from '@launchql/types';
 import { PgTestConnector } from './manager';
 import { SeedAdapter } from './seed/types';
 import { PgTestClient } from './test-client';
-export declare const getPgRootAdmin: (connOpts?: TestConnectionOptions) => DbAdmin;
+export declare const getPgRootAdmin: (connOpts?: PgTestConnectionOptions) => DbAdmin;
 export interface GetConnectionOpts {
     pg?: Partial<PgConfig>;
-    db?: Partial<TestConnectionOptions>;
+    db?: Partial<PgTestConnectionOptions>;
 }
 export interface GetConnectionResult {
     pg: PgTestClient;

package/connect.js

@@ -27,7 +27,7 @@ const getConnOopts = (cn = {}) => {
         db: connect
     };
 };
-const getConnections = async (cn = {}, seedAdapters = []) => {
+const getConnections = async (cn = {}, seedAdapters = [seed_1.seed.launchql()]) => {
     cn = getConnOopts(cn);
     const config = cn.pg;
     const connOpts = cn.db;

package/esm/connect.js

@@ -23,7 +23,7 @@ const getConnOopts = (cn = {}) => {
         db: connect
     };
 };
-export const getConnections = async (cn = {}, seedAdapters = []) => {
+export const getConnections = async (cn = {}, seedAdapters = [seed.launchql()]) => {
     cn = getConnOopts(cn);
     const config = cn.pg;
     const connOpts = cn.db;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgsql-test",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "author": "Dan Lynch <pyramation@gmail.com>",
   "description": "PostgreSQL Testing in TypeScript",
   "main": "index.js",
@@ -34,13 +34,13 @@
     "@types/pg-copy-streams": "^1.2.5"
   },
   "dependencies": {
-    "@launchql/migrate": "^2.0.13",
-    "@launchql/server-utils": "^2.0.6",
-    "@launchql/types": "^2.0.5",
+    "@launchql/migrate": "^2.0.14",
+    "@launchql/server-utils": "^2.0.7",
+    "@launchql/types": "^2.0.6",
     "chalk": "^4.1.0",
     "deepmerge": "^4.3.1",
     "pg": "^8.16.0",
     "pg-copy-streams": "^6.0.6"
   },
-  "gitHead": "5a6be2ac585f936256fe95f9d3ff0690bd768d87"
+  "gitHead": "5697261a8f6e252d38b02b806272a19c5cd7a578"
 }

package/seed/types.d.ts

@@ -1,8 +1,8 @@
-import { PgConfig, TestConnectionOptions } from "@launchql/types";
+import { PgConfig, PgTestConnectionOptions } from "@launchql/types";
 import { DbAdmin } from "../admin";
 import { PgTestClient } from "../test-client";
 export interface SeedContext {
-    connect: TestConnectionOptions;
+    connect: PgTestConnectionOptions;
     admin: DbAdmin;
     config: PgConfig;
     pg: PgTestClient;