pg-query-context 2.1.4 → 2.1.6

package/README.md

@@ -12,6 +12,81 @@
    <a href="https://www.npmjs.com/package/pg-query-context"><img height="20" src="https://img.shields.io/github/package-json/v/launchql/launchql?filename=packages%2Fpg-query-context%2Fpackage.json"/></a>
 </p>
 
+# pg-query-context
+
+A small utility for executing PostgreSQL queries within a session context using [`pg`](https://www.npmjs.com/package/pg). It allows you to temporarily set PostgreSQL session variables (`set_config`) for RLS (Row-Level Security) and other scoped operations.
+
+## Installation
+
+```bash
+npm install pg-query-context
+```
+
+## Features
+
+* Sets session-level context (e.g., role, user ID) using `set_config`.
+* Automatically wraps execution in a transaction (`BEGIN`/`COMMIT`).
+* Automatically rolls back on error.
+* Supports both `Pool` and `Client` from `pg`.
+
+## Usage
+
+```ts
+import pgQueryContext from 'pg-query-context';
+import { Pool } from 'pg';
+
+const pool = new Pool();
+
+const result = await pgQueryContext({
+  client: pool,
+  context: {
+    'role': 'authenticated',
+    'myapp.user_id': '123e4567-e89b-12d3-a456-426614174000'
+  },
+  query: 'SELECT * FROM app_private.do_something_secure($1)',
+  variables: ['input-value']
+});
+
+console.log(result.rows);
+```
+
+## API
+
+### `pgQueryContext(options: ExecOptions): Promise<QueryResult>`
+
+#### Options
+
+| Name        | Type                     | Required | Description                                            |
+| ----------- | ------------------------ | -------- | ------------------------------------------------------ |
+| `client`    | `Pool` or `ClientBase`   | ✅        | The PostgreSQL client or pool to use                   |
+| `context`   | `Record<string, string>` | ❌        | Key-value session variables to be set via `set_config` |
+| `query`     | `string`                 | ✅        | SQL query to run                                       |
+| `variables` | `any[]`                  | ❌        | Parameterized query variables                          |
+
+## Example with `express`
+
+```ts
+app.post('/secure-endpoint', async (req, res) => {
+  const authToken = req.headers.authorization;
+
+  const result = await pgQueryContext({
+    client: pool,
+    context: {
+      'role': 'authenticated',
+      'myapp.token': authToken,
+    },
+    query: 'SELECT * FROM app_private.verify_token($1)',
+    variables: [authToken],
+  });
+
+  if (!result.rows.length) {
+    return res.status(401).json({ error: 'Unauthorized' });
+  }
+
+  res.json({ user: result.rows[0] });
+});
+```
+
 ## Related LaunchQL Tooling
 
 ### 🧪 Testing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pg-query-context",
-  "version": "2.1.4",
+  "version": "2.1.6",
   "author": "Dan Lynch <pyramation@gmail.com>",
   "description": "pg query context",
   "main": "index.js",
@@ -35,5 +35,12 @@
   "devDependencies": {
     "@types/pg": "^8.15.2"
   },
-  "gitHead": "36e9eb71ef72f72d21e9557fb190da1900f31b87"
+  "keywords": [
+    "postgresql",
+    "query",
+    "context",
+    "pg",
+    "graphile"
+  ],
+  "gitHead": "cc4675c134273a66b11a881d084d04362f6837af"
 }