pgsql-client 0.0.1 → 1.1.1

package/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Dan Lynch <pyramation@gmail.com>
+Copyright (c) 2025 Constructive <developers@constructive.io>
+Copyright (c) 2020-present, Interweb, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -8,13 +8,25 @@
   <a href="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml">
     <img height="20" src="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml/badge.svg" />
   </a>
-   <a href="https://github.com/constructive-io/constructive/blob/main/LICENSE"><img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/></a>
-   <a href="https://www.npmjs.com/package/pgsql-client"><img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/constructive?filename=postgres%2Fpgsql-client%2Fpackage.json"/></a>
+  <a href="https://github.com/constructive-io/constructive/blob/main/LICENSE">
+    <img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/>
+  </a>
+  <a href="https://www.npmjs.com/package/pgsql-client">
+    <img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/constructive?filename=postgres%2Fpgsql-client%2Fpackage.json"/>
+  </a>
 </p>
 
-# pgsql-client
+PostgreSQL client utilities with query helpers, RLS context management, and database administration.
+
+## Overview
 
-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.
+`pgsql-client` provides a set of utilities for working with PostgreSQL databases:
+
+- **DbAdmin**: Database administration operations (create, drop, templates, extensions, grants)
+- **PgClient**: Query helpers with RLS context management
+- **Role utilities**: Role name mapping for anonymous, authenticated, and administrator roles
+- **Context utilities**: Generate SQL for setting PostgreSQL session context variables
+- **Stream utilities**: Stream SQL to psql process
 
 ## Installation
 
@@ -22,71 +34,99 @@ A small utility for executing PostgreSQL queries within a session context using
 npm install pgsql-client
 ```
 
-## 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 'pgsql-client';
-import { Pool } from 'pg';
+### DbAdmin
 
-const pool = new Pool();
+```typescript
+import { DbAdmin } from 'pgsql-client';
 
-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']
+const admin = new DbAdmin({
+  host: 'localhost',
+  port: 5432,
+  user: 'postgres',
+  password: 'password',
+  database: 'mydb'
 });
 
-console.log(result.rows);
-```
+// Create a database
+admin.create('mydb');
 
-## API
+// Install extensions
+admin.installExtensions(['uuid-ossp', 'pgcrypto'], 'mydb');
 
-### `pgQueryContext(options: ExecOptions): Promise<QueryResult>`
+// Drop a database
+admin.drop('mydb');
+```
 
-#### Options
+### PgClient
 
-| 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                          |
+```typescript
+import { PgClient } from 'pgsql-client';
 
-## Example with `express`
+const client = new PgClient({
+  host: 'localhost',
+  port: 5432,
+  user: 'app_user',
+  password: 'password',
+  database: 'mydb'
+});
 
-```ts
-app.post('/secure-endpoint', async (req, res) => {
-  const authToken = req.headers.authorization;
+// Query helpers
+const users = await client.any('SELECT * FROM users');
+const user = await client.one('SELECT * FROM users WHERE id = $1', [userId]);
+const maybeUser = await client.oneOrNone('SELECT * FROM users WHERE email = $1', [email]);
 
-  const result = await pgQueryContext({
-    client: pool,
-    context: {
-      'role': 'authenticated',
-      'myapp.token': authToken,
-    },
-    query: 'SELECT * FROM app_private.verify_token($1)',
-    variables: [authToken],
-  });
+// Set RLS context
+client.setContext({ role: 'authenticated', 'jwt.claims.user_id': userId });
 
-  if (!result.rows.length) {
-    return res.status(401).json({ error: 'Unauthorized' });
-  }
+// Or use the auth helper
+client.auth({ role: 'authenticated', userId: userId });
 
-  res.json({ user: result.rows[0] });
-});
+// Close the connection
+await client.close();
 ```
 
+## API
+
+### DbAdmin
+
+- `create(dbName?)` - Create a database
+- `drop(dbName?)` - Drop a database
+- `createFromTemplate(template, dbName?)` - Create database from template
+- `installExtensions(extensions, dbName?)` - Install PostgreSQL extensions
+- `connectionString(dbName?)` - Generate connection string
+- `createTemplateFromBase(base, template)` - Create template database
+- `cleanupTemplate(template)` - Clean up template database
+- `grantRole(role, user, dbName?)` - Grant role to user
+- `grantConnect(role, dbName?)` - Grant connect privilege
+- `createUserRole(user, password, dbName)` - Create user with roles
+- `loadSql(file, dbName)` - Load SQL file
+- `streamSql(sql, dbName)` - Stream SQL to database
+
+### PgClient
+
+- `query(sql, values?)` - Execute query with context
+- `any(sql, values?)` - Return all rows
+- `one(sql, values?)` - Return exactly one row (throws if not exactly one)
+- `oneOrNone(sql, values?)` - Return one row or null
+- `many(sql, values?)` - Return many rows (throws if none)
+- `manyOrNone(sql, values?)` - Return rows or empty array
+- `none(sql, values?)` - Execute without returning rows
+- `result(sql, values?)` - Return full QueryResult
+- `begin()` - Begin transaction
+- `commit()` - Commit transaction
+- `savepoint(name?)` - Create savepoint
+- `rollback(name?)` - Rollback to savepoint
+- `setContext(ctx)` - Set session context variables
+- `auth(options?)` - Set authentication context
+- `clearContext()` - Clear context and reset to anonymous
+- `close()` - Close connection
+
+## License
+
+MIT
+
 ---
 
 ## Education and Tutorials
@@ -114,12 +154,17 @@ Common issues and solutions for pgpm, PostgreSQL, and testing.
 
 ## Related Constructive Tooling
 
+### 📦 Package Management
+
+* [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+
 ### 🧪 Testing
 
 * [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [pgsql-seed](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-seed): **🌱 PostgreSQL seeding utilities** for CSV, JSON, SQL data loading, and pgpm deployment.
 * [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
 * [graphile-test](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
-* [pgsql-client](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-client): **🔒 Session context injection** to add session-local context (e.g., `SET LOCAL`) into queries—ideal for setting `role`, `jwt.claims`, and other session settings.
+* [pg-query-context](https://github.com/constructive-io/constructive/tree/main/postgres/pg-query-context): **🔒 Session context injection** to add session-local context (e.g., `SET LOCAL`) into queries—ideal for setting `role`, `jwt.claims`, and other session settings.
 
 ### 🧠 Parsing & AST
 
@@ -130,28 +175,6 @@ Common issues and solutions for pgpm, PostgreSQL, and testing.
 * [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
 * [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
 
-### 🚀 API & Dev Tools
-
-* [@constructive-io/graphql-server](https://github.com/constructive-io/constructive/tree/main/graphql/server): **⚡ Express-based API server** powered by PostGraphile to expose a secure, scalable GraphQL API over your Postgres database.
-* [@constructive-io/graphql-explorer](https://github.com/constructive-io/constructive/tree/main/graphql/explorer): **🔎 Visual API explorer** with GraphiQL for browsing across all databases and schemas—useful for debugging, documentation, and API prototyping.
-
-### 🔁 Streaming & Uploads
-
-* [etag-hash](https://github.com/constructive-io/constructive/tree/main/streaming/etag-hash): **🏷️ S3-compatible ETags** created by streaming and hashing file uploads in chunks.
-* [etag-stream](https://github.com/constructive-io/constructive/tree/main/streaming/etag-stream): **🔄 ETag computation** via Node stream transformer during upload or transfer.
-* [uuid-hash](https://github.com/constructive-io/constructive/tree/main/streaming/uuid-hash): **🆔 Deterministic UUIDs** generated from hashed content, great for deduplication and asset referencing.
-* [uuid-stream](https://github.com/constructive-io/constructive/tree/main/streaming/uuid-stream): **🌊 Streaming UUID generation** based on piped file content—ideal for upload pipelines.
-* [@constructive-io/s3-streamer](https://github.com/constructive-io/constructive/tree/main/streaming/s3-streamer): **📤 Direct S3 streaming** for large files with support for metadata injection and content validation.
-* [@constructive-io/upload-names](https://github.com/constructive-io/constructive/tree/main/streaming/upload-names): **📂 Collision-resistant filenames** utility for structured and unique file names for uploads.
-
-### 🧰 CLI & Codegen
-
-* [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
-* [@constructive-io/cli](https://github.com/constructive-io/constructive/tree/main/packages/cli): **🖥️ Command-line toolkit** for managing Constructive projects—supports database scaffolding, migrations, seeding, code generation, and automation.
-* [@constructive-io/graphql-codegen](https://github.com/constructive-io/constructive/tree/main/graphql/codegen): **✨ GraphQL code generation** (types, operations, SDK) from schema/endpoint introspection.
-* [@constructive-io/query-builder](https://github.com/constructive-io/constructive/tree/main/packages/query-builder): **🏗️ SQL constructor** providing a robust TypeScript-based query builder for dynamic generation of `SELECT`, `INSERT`, `UPDATE`, `DELETE`, and stored procedure calls—supports advanced SQL features like `JOIN`, `GROUP BY`, and schema-qualified queries.
-* [@constructive-io/graphql-query](https://github.com/constructive-io/constructive/tree/main/graphql/query): **🧩 Fluent GraphQL builder** for PostGraphile schemas. ⚡ Schema-aware via introspection, 🧩 composable and ergonomic for building deeply nested queries.
-
 ## Credits
 
 **🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**

package/admin.d.ts

@@ -0,0 +1,24 @@
+import { PgTestConnectionOptions } from '@pgpmjs/types';
+import { PgConfig } from 'pg-env';
+export declare class DbAdmin {
+    protected config: PgConfig;
+    protected verbose: boolean;
+    protected roleConfig?: PgTestConnectionOptions;
+    constructor(config: PgConfig, verbose?: boolean, roleConfig?: PgTestConnectionOptions);
+    private getEnv;
+    private run;
+    private safeDropDb;
+    drop(dbName?: string): void;
+    dropTemplate(dbName: string): void;
+    create(dbName?: string): void;
+    createFromTemplate(template: string, dbName?: string): void;
+    installExtensions(extensions: string[] | string, dbName?: string): void;
+    connectionString(dbName?: string): string;
+    createTemplateFromBase(base: string, template: string): void;
+    cleanupTemplate(template: string): void;
+    grantRole(role: string, user: string, dbName?: string): Promise<void>;
+    grantConnect(role: string, dbName?: string): Promise<void>;
+    createUserRole(user: string, password: string, dbName: string, useLocksForRoles?: boolean): Promise<void>;
+    loadSql(file: string, dbName: string): void;
+    streamSql(sql: string, dbName: string): Promise<void>;
+}

package/admin.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DbAdmin = void 0;
+const core_1 = require("@pgpmjs/core");
+const logger_1 = require("@pgpmjs/logger");
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const pg_env_1 = require("pg-env");
+const roles_1 = require("./roles");
+const stream_1 = require("./stream");
+const log = new logger_1.Logger('db-admin');
+class DbAdmin {
+    config;
+    verbose;
+    roleConfig;
+    constructor(config, verbose = false, roleConfig) {
+        this.config = (0, pg_env_1.getPgEnvOptions)(config);
+        this.verbose = verbose;
+        this.roleConfig = roleConfig;
+    }
+    getEnv() {
+        return {
+            PGHOST: this.config.host,
+            PGPORT: String(this.config.port),
+            PGUSER: this.config.user,
+            PGPASSWORD: this.config.password
+        };
+    }
+    run(command) {
+        try {
+            (0, child_process_1.execSync)(command, {
+                stdio: this.verbose ? 'inherit' : 'pipe',
+                env: {
+                    ...process.env,
+                    ...this.getEnv()
+                }
+            });
+            if (this.verbose)
+                log.success(`Executed: ${command}`);
+        }
+        catch (err) {
+            log.error(`Command failed: ${command}`);
+            if (this.verbose)
+                log.error(err.message);
+            throw err;
+        }
+    }
+    safeDropDb(name) {
+        try {
+            this.run(`dropdb "${name}"`);
+        }
+        catch (err) {
+            if (!err.message.includes('does not exist')) {
+                log.warn(`Could not drop database ${name}: ${err.message}`);
+            }
+        }
+    }
+    drop(dbName) {
+        this.safeDropDb(dbName ?? this.config.database);
+    }
+    dropTemplate(dbName) {
+        this.run(`psql -c "UPDATE pg_database SET datistemplate='false' WHERE datname='${dbName}'"`);
+        this.drop(dbName);
+    }
+    create(dbName) {
+        const db = dbName ?? this.config.database;
+        this.run(`createdb -U ${this.config.user} -h ${this.config.host} -p ${this.config.port} "${db}"`);
+    }
+    createFromTemplate(template, dbName) {
+        const db = dbName ?? this.config.database;
+        this.run(`createdb -U ${this.config.user} -h ${this.config.host} -p ${this.config.port} -e "${db}" -T "${template}"`);
+    }
+    installExtensions(extensions, dbName) {
+        const db = dbName ?? this.config.database;
+        const extList = typeof extensions === 'string' ? extensions.split(',') : extensions;
+        for (const extension of extList) {
+            this.run(`psql --dbname "${db}" -c 'CREATE EXTENSION IF NOT EXISTS "${extension}" CASCADE;'`);
+        }
+    }
+    connectionString(dbName) {
+        const { user, password, host, port } = this.config;
+        const db = dbName ?? this.config.database;
+        return `postgres://${user}:${password}@${host}:${port}/${db}`;
+    }
+    createTemplateFromBase(base, template) {
+        this.run(`createdb -T "${base}" "${template}"`);
+        this.run(`psql -c "UPDATE pg_database SET datistemplate = true WHERE datname = '${template}';"`);
+    }
+    cleanupTemplate(template) {
+        try {
+            this.run(`psql -c "UPDATE pg_database SET datistemplate = false WHERE datname = '${template}'"`);
+        }
+        catch {
+            log.warn(`Skipping failed UPDATE of datistemplate for ${template}`);
+        }
+        this.safeDropDb(template);
+    }
+    async grantRole(role, user, dbName) {
+        const db = dbName ?? this.config.database;
+        const sql = (0, core_1.generateGrantRoleSQL)(role, user);
+        await this.streamSql(sql, db);
+    }
+    async grantConnect(role, dbName) {
+        const db = dbName ?? this.config.database;
+        const sql = `GRANT CONNECT ON DATABASE "${db}" TO ${role};`;
+        await this.streamSql(sql, db);
+    }
+    // ONLY granting admin role for testing purposes, normally the db connection for apps won't have admin role
+    // DO NOT USE THIS FOR PRODUCTION
+    async createUserRole(user, password, dbName, useLocksForRoles = false) {
+        const anonRole = (0, roles_1.getRoleName)('anonymous', this.roleConfig);
+        const authRole = (0, roles_1.getRoleName)('authenticated', this.roleConfig);
+        const adminRole = (0, roles_1.getRoleName)('administrator', this.roleConfig);
+        const sql = (0, core_1.generateCreateUserWithGrantsSQL)(user, password, [anonRole, authRole, adminRole], useLocksForRoles);
+        await this.streamSql(sql, dbName);
+    }
+    loadSql(file, dbName) {
+        if (!(0, fs_1.existsSync)(file)) {
+            throw new Error(`Missing SQL file: ${file}`);
+        }
+        this.run(`psql -f ${file} ${dbName}`);
+    }
+    async streamSql(sql, dbName) {
+        await (0, stream_1.streamSql)({
+            ...this.config,
+            database: dbName
+        }, sql);
+    }
+}
+exports.DbAdmin = DbAdmin;

package/client.d.ts

@@ -0,0 +1,42 @@
+import { Client, QueryResult } from 'pg';
+import { PgConfig } from 'pg-env';
+import { AuthOptions, PgTestConnectionOptions, PgTestClientContext } from '@pgpmjs/types';
+export type PgClientOpts = {
+    deferConnect?: boolean;
+    trackConnect?: (p: Promise<any>) => void;
+} & Partial<PgTestConnectionOptions>;
+export declare class PgClient {
+    config: PgConfig;
+    client: Client;
+    protected opts: PgClientOpts;
+    protected ctxStmts: string;
+    protected contextSettings: PgTestClientContext;
+    protected _ended: boolean;
+    protected connectPromise: Promise<void> | null;
+    constructor(config: PgConfig, opts?: PgClientOpts);
+    protected ensureConnected(): Promise<void>;
+    close(): Promise<void>;
+    begin(): Promise<void>;
+    savepoint(name?: string): Promise<void>;
+    rollback(name?: string): Promise<void>;
+    commit(): Promise<void>;
+    setContext(ctx: Record<string, string | null>): void;
+    /**
+     * Set authentication context for the current session.
+     * Configures role and user ID using cascading defaults from options -> opts.auth -> RoleMapping.
+     */
+    auth(options?: AuthOptions): void;
+    /**
+     * Clear all session context variables and reset to default anonymous role.
+     */
+    clearContext(): void;
+    any<T = any>(query: string, values?: any[]): Promise<T[]>;
+    one<T = any>(query: string, values?: any[]): Promise<T>;
+    oneOrNone<T = any>(query: string, values?: any[]): Promise<T | null>;
+    many<T = any>(query: string, values?: any[]): Promise<T[]>;
+    manyOrNone<T = any>(query: string, values?: any[]): Promise<T[]>;
+    none(query: string, values?: any[]): Promise<void>;
+    result(query: string, values?: any[]): Promise<QueryResult>;
+    ctxQuery(): Promise<void>;
+    query<T = any>(query: string, values?: any[]): Promise<QueryResult<T>>;
+}

package/client.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PgClient = void 0;
+const pg_1 = require("pg");
+const roles_1 = require("./roles");
+const context_utils_1 = require("./context-utils");
+class PgClient {
+    config;
+    client;
+    opts;
+    ctxStmts = '';
+    contextSettings = {};
+    _ended = false;
+    connectPromise = null;
+    constructor(config, opts = {}) {
+        this.opts = opts;
+        this.config = config;
+        this.client = new pg_1.Client({
+            host: this.config.host,
+            port: this.config.port,
+            database: this.config.database,
+            user: this.config.user,
+            password: this.config.password
+        });
+        if (!opts.deferConnect) {
+            this.connectPromise = this.client.connect();
+            if (opts.trackConnect)
+                opts.trackConnect(this.connectPromise);
+        }
+    }
+    async ensureConnected() {
+        if (this.connectPromise) {
+            try {
+                await this.connectPromise;
+            }
+            catch { }
+        }
+    }
+    async close() {
+        if (!this._ended) {
+            this._ended = true;
+            await this.ensureConnected();
+            await this.client.end();
+        }
+    }
+    async begin() {
+        await this.client.query('BEGIN;');
+    }
+    async savepoint(name = 'lqlsavepoint') {
+        await this.client.query(`SAVEPOINT "${name}";`);
+    }
+    async rollback(name = 'lqlsavepoint') {
+        await this.client.query(`ROLLBACK TO SAVEPOINT "${name}";`);
+    }
+    async commit() {
+        await this.client.query('COMMIT;');
+    }
+    setContext(ctx) {
+        Object.assign(this.contextSettings, ctx);
+        this.ctxStmts = (0, context_utils_1.generateContextStatements)(this.contextSettings);
+    }
+    /**
+     * Set authentication context for the current session.
+     * Configures role and user ID using cascading defaults from options -> opts.auth -> RoleMapping.
+     */
+    auth(options = {}) {
+        const role = options.role ?? this.opts.auth?.role ?? (0, roles_1.getRoleName)('authenticated', this.opts);
+        const userIdKey = options.userIdKey ?? this.opts.auth?.userIdKey ?? 'jwt.claims.user_id';
+        const userId = options.userId ?? this.opts.auth?.userId ?? null;
+        this.setContext({
+            role,
+            [userIdKey]: userId !== null ? String(userId) : null
+        });
+    }
+    /**
+     * Clear all session context variables and reset to default anonymous role.
+     */
+    clearContext() {
+        const defaultRole = (0, roles_1.getRoleName)('anonymous', this.opts);
+        const nulledSettings = {};
+        Object.keys(this.contextSettings).forEach(key => {
+            nulledSettings[key] = null;
+        });
+        nulledSettings.role = defaultRole;
+        this.ctxStmts = (0, context_utils_1.generateContextStatements)(nulledSettings);
+        this.contextSettings = { role: defaultRole };
+    }
+    async any(query, values) {
+        const result = await this.query(query, values);
+        return result.rows;
+    }
+    async one(query, values) {
+        const rows = await this.any(query, values);
+        if (rows.length !== 1) {
+            throw new Error('Expected exactly one result');
+        }
+        return rows[0];
+    }
+    async oneOrNone(query, values) {
+        const rows = await this.any(query, values);
+        return rows[0] || null;
+    }
+    async many(query, values) {
+        const rows = await this.any(query, values);
+        if (rows.length === 0)
+            throw new Error('Expected many rows, got none');
+        return rows;
+    }
+    async manyOrNone(query, values) {
+        return this.any(query, values);
+    }
+    async none(query, values) {
+        await this.query(query, values);
+    }
+    async result(query, values) {
+        return this.query(query, values);
+    }
+    async ctxQuery() {
+        if (this.ctxStmts) {
+            await this.client.query(this.ctxStmts);
+        }
+    }
+    // NOTE: all queries should call ctxQuery() before executing the query
+    async query(query, values) {
+        await this.ctxQuery();
+        const result = await this.client.query(query, values);
+        return result;
+    }
+}
+exports.PgClient = PgClient;

package/context-utils.d.ts

@@ -0,0 +1,8 @@
+import type { PgTestClientContext } from '@pgpmjs/types';
+/**
+ * Generate SQL statements to set PostgreSQL session context variables
+ * Uses SET LOCAL ROLE for the 'role' key and set_config() for other variables
+ * @param context - Context settings to apply
+ * @returns SQL string with SET LOCAL ROLE and set_config() statements
+ */
+export declare function generateContextStatements(context: PgTestClientContext): string;

package/context-utils.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateContextStatements = generateContextStatements;
+/**
+ * Generate SQL statements to set PostgreSQL session context variables
+ * Uses SET LOCAL ROLE for the 'role' key and set_config() for other variables
+ * @param context - Context settings to apply
+ * @returns SQL string with SET LOCAL ROLE and set_config() statements
+ */
+function generateContextStatements(context) {
+    return Object.entries(context)
+        .map(([key, val]) => {
+        if (key === 'role') {
+            if (val === null || val === undefined) {
+                return 'SET LOCAL ROLE NONE;';
+            }
+            const escapedRole = val.replace(/"/g, '""');
+            return `SET LOCAL ROLE "${escapedRole}";`;
+        }
+        // Use set_config for other context variables
+        if (val === null || val === undefined) {
+            return `SELECT set_config('${key}', NULL, true);`;
+        }
+        const escapedVal = val.replace(/'/g, "''");
+        return `SELECT set_config('${key}', '${escapedVal}', true);`;
+    })
+        .join('\n');
+}