pgsql-client 0.0.1 → 1.1.1

package/esm/admin.js

@@ -0,0 +1,126 @@
+import { generateCreateUserWithGrantsSQL, generateGrantRoleSQL } from '@pgpmjs/core';
+import { Logger } from '@pgpmjs/logger';
+import { execSync } from 'child_process';
+import { existsSync } from 'fs';
+import { getPgEnvOptions } from 'pg-env';
+import { getRoleName } from './roles';
+import { streamSql as stream } from './stream';
+const log = new Logger('db-admin');
+export class DbAdmin {
+    config;
+    verbose;
+    roleConfig;
+    constructor(config, verbose = false, roleConfig) {
+        this.config = 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 {
+            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 = 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 = getRoleName('anonymous', this.roleConfig);
+        const authRole = getRoleName('authenticated', this.roleConfig);
+        const adminRole = getRoleName('administrator', this.roleConfig);
+        const sql = generateCreateUserWithGrantsSQL(user, password, [anonRole, authRole, adminRole], useLocksForRoles);
+        await this.streamSql(sql, dbName);
+    }
+    loadSql(file, dbName) {
+        if (!existsSync(file)) {
+            throw new Error(`Missing SQL file: ${file}`);
+        }
+        this.run(`psql -f ${file} ${dbName}`);
+    }
+    async streamSql(sql, dbName) {
+        await stream({
+            ...this.config,
+            database: dbName
+        }, sql);
+    }
+}

package/esm/client.js

@@ -0,0 +1,126 @@
+import { Client } from 'pg';
+import { getRoleName } from './roles';
+import { generateContextStatements } from './context-utils';
+export class PgClient {
+    config;
+    client;
+    opts;
+    ctxStmts = '';
+    contextSettings = {};
+    _ended = false;
+    connectPromise = null;
+    constructor(config, opts = {}) {
+        this.opts = opts;
+        this.config = config;
+        this.client = new 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 = 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 ?? 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 = getRoleName('anonymous', this.opts);
+        const nulledSettings = {};
+        Object.keys(this.contextSettings).forEach(key => {
+            nulledSettings[key] = null;
+        });
+        nulledSettings.role = defaultRole;
+        this.ctxStmts = 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;
+    }
+}

package/esm/context-utils.js

@@ -0,0 +1,25 @@
+/**
+ * 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 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');
+}

package/esm/index.js

@@ -1,36 +1,5 @@
-function setContext(ctx) {
-    return Object.keys(ctx || {}).reduce((m, el) => {
-        m.push(`SELECT set_config('${el}', '${ctx[el]}', true);`);
-        return m;
-    }, []);
-}
-async function execContext(client, ctx) {
-    const local = setContext(ctx);
-    for (const query of local) {
-        await client.query(query);
-    }
-}
-export default async ({ client, context = {}, query = '', variables = [] }) => {
-    const isPool = 'connect' in client;
-    const shouldRelease = isPool;
-    let pgClient = null;
-    try {
-        pgClient = isPool ? await client.connect() : client;
-        await pgClient.query('BEGIN');
-        await execContext(pgClient, context);
-        const result = await pgClient.query(query, variables);
-        await pgClient.query('COMMIT');
-        return result;
-    }
-    catch (error) {
-        if (pgClient) {
-            await pgClient.query('ROLLBACK').catch(() => { });
-        }
-        throw error;
-    }
-    finally {
-        if (shouldRelease && pgClient && 'release' in pgClient) {
-            pgClient.release();
-        }
-    }
-};
+export * from './admin';
+export * from './client';
+export * from './context-utils';
+export * from './roles';
+export { streamSql } from './stream';

package/esm/roles.js

@@ -0,0 +1,32 @@
+/**
+ * Default role mapping configuration
+ */
+export const DEFAULT_ROLE_MAPPING = {
+    anonymous: 'anonymous',
+    authenticated: 'authenticated',
+    administrator: 'administrator',
+    default: 'anonymous'
+};
+/**
+ * Get resolved role mapping with defaults
+ */
+export const getRoleMapping = (options) => {
+    return {
+        ...DEFAULT_ROLE_MAPPING,
+        ...(options?.roles || {})
+    };
+};
+/**
+ * Get role name by key with fallback to default mapping
+ */
+export const getRoleName = (roleKey, options) => {
+    const mapping = getRoleMapping(options);
+    return mapping[roleKey];
+};
+/**
+ * Get default role name
+ */
+export const getDefaultRole = (options) => {
+    const mapping = getRoleMapping(options);
+    return mapping.default;
+};

package/esm/stream.js

@@ -0,0 +1,96 @@
+import { spawn } from 'child_process';
+import { getSpawnEnvWithPg } from 'pg-env';
+import { Readable } from 'stream';
+function setArgs(config) {
+    const args = [
+        '-U', config.user,
+        '-h', config.host,
+        '-d', config.database
+    ];
+    if (config.port) {
+        args.push('-p', String(config.port));
+    }
+    return args;
+}
+// Converts a string to a readable stream (replaces streamify-string)
+function stringToStream(text) {
+    const stream = new Readable({
+        read() {
+            this.push(text);
+            this.push(null);
+        }
+    });
+    return stream;
+}
+/**
+ * Executes SQL statements by streaming them to psql.
+ *
+ * IMPORTANT: PostgreSQL stderr handling
+ * -------------------------------------
+ * PostgreSQL sends different message types to stderr, not just errors:
+ *   - ERROR: Actual SQL errors (should fail)
+ *   - WARNING: Potential issues (informational)
+ *   - NOTICE: Informational messages (should NOT fail)
+ *   - INFO: Informational messages (should NOT fail)
+ *   - DEBUG: Debug messages (should NOT fail)
+ *
+ * Example scenario that previously caused false failures:
+ * When running SQL like:
+ *   GRANT administrator TO app_user;
+ *
+ * If app_user is already a member of administrator, PostgreSQL outputs:
+ *   NOTICE: role "app_user" is already a member of role "administrator"
+ *
+ * This is NOT an error - the GRANT succeeded (it's idempotent). But because
+ * this message goes to stderr, the old implementation would reject the promise
+ * and fail the test, even though nothing was wrong.
+ *
+ * Solution:
+ * 1. Buffer stderr instead of rejecting immediately on any output
+ * 2. Use ON_ERROR_STOP=1 so psql exits with non-zero code on actual SQL errors
+ * 3. Only reject if the exit code is non-zero, using buffered stderr as the error message
+ *
+ * This way, NOTICE/WARNING messages are collected but don't cause failures,
+ * while actual SQL errors still properly fail with meaningful error messages.
+ */
+export async function streamSql(config, sql) {
+    const args = [
+        ...setArgs(config),
+        // ON_ERROR_STOP=1 makes psql exit with a non-zero code when it encounters
+        // an actual SQL error. Without this, psql might continue executing subsequent
+        // statements and exit with code 0 even if some statements failed.
+        '-v', 'ON_ERROR_STOP=1'
+    ];
+    return new Promise((resolve, reject) => {
+        const sqlStream = stringToStream(sql);
+        // Buffer stderr instead of rejecting immediately. This allows us to collect
+        // all output (including harmless NOTICE messages) and only use it for error
+        // reporting if the process actually fails.
+        let stderrBuffer = '';
+        const proc = spawn('psql', args, {
+            env: getSpawnEnvWithPg(config)
+        });
+        sqlStream.pipe(proc.stdin);
+        // Collect stderr output. We don't reject here because stderr may contain
+        // harmless NOTICE/WARNING messages that shouldn't cause test failures.
+        proc.stderr.on('data', (data) => {
+            stderrBuffer += data.toString();
+        });
+        // Determine success/failure based on exit code, not stderr content.
+        // Exit code 0 = success (even if there were NOTICE messages on stderr)
+        // Exit code non-zero = actual error occurred
+        proc.on('close', (code) => {
+            if (code !== 0) {
+                // Include the buffered stderr in the error message for debugging
+                reject(new Error(stderrBuffer || `psql exited with code ${code}`));
+            }
+            else {
+                resolve();
+            }
+        });
+        // Handle spawn errors (e.g., psql not found)
+        proc.on('error', (error) => {
+            reject(error);
+        });
+    });
+}

package/index.d.ts

@@ -1,9 +1,5 @@
-import { ClientBase, Pool, QueryResult } from 'pg';
-interface ExecOptions {
-    client: Pool | ClientBase;
-    context?: Record<string, string>;
-    query: string;
-    variables?: any[];
-}
-declare const _default: ({ client, context, query, variables }: ExecOptions) => Promise<QueryResult>;
-export default _default;
+export * from './admin';
+export * from './client';
+export * from './context-utils';
+export * from './roles';
+export { streamSql } from './stream';

package/index.js

@@ -1,38 +1,23 @@
 "use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-function setContext(ctx) {
-    return Object.keys(ctx || {}).reduce((m, el) => {
-        m.push(`SELECT set_config('${el}', '${ctx[el]}', true);`);
-        return m;
-    }, []);
-}
-async function execContext(client, ctx) {
-    const local = setContext(ctx);
-    for (const query of local) {
-        await client.query(query);
-    }
-}
-exports.default = async ({ client, context = {}, query = '', variables = [] }) => {
-    const isPool = 'connect' in client;
-    const shouldRelease = isPool;
-    let pgClient = null;
-    try {
-        pgClient = isPool ? await client.connect() : client;
-        await pgClient.query('BEGIN');
-        await execContext(pgClient, context);
-        const result = await pgClient.query(query, variables);
-        await pgClient.query('COMMIT');
-        return result;
-    }
-    catch (error) {
-        if (pgClient) {
-            await pgClient.query('ROLLBACK').catch(() => { });
-        }
-        throw error;
-    }
-    finally {
-        if (shouldRelease && pgClient && 'release' in pgClient) {
-            pgClient.release();
-        }
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
     }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.streamSql = void 0;
+__exportStar(require("./admin"), exports);
+__exportStar(require("./client"), exports);
+__exportStar(require("./context-utils"), exports);
+__exportStar(require("./roles"), exports);
+var stream_1 = require("./stream");
+Object.defineProperty(exports, "streamSql", { enumerable: true, get: function () { return stream_1.streamSql; } });

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "pgsql-client",
-  "version": "0.0.1",
+  "version": "1.1.1",
   "author": "Constructive <developers@constructive.io>",
-  "description": "pgsql client",
+  "description": "PostgreSQL client utilities with query helpers, RLS context management, and database administration",
   "main": "index.js",
   "module": "esm/index.js",
   "types": "index.d.ts",
@@ -19,18 +19,37 @@
   "bugs": {
     "url": "https://github.com/constructive-io/constructive/issues"
   },
-  "dependencies": {
-    "pg": "^8.16.3"
+  "keywords": [
+    "postgres",
+    "postgresql",
+    "client",
+    "pg",
+    "rls",
+    "row-level-security",
+    "database",
+    "admin",
+    "query-helpers",
+    "constructive"
+  ],
+  "scripts": {
+    "clean": "makage clean",
+    "prepack": "npm run build",
+    "build": "makage build",
+    "build:dev": "makage build --dev",
+    "lint": "eslint . --fix",
+    "test": "jest --passWithNoTests",
+    "test:watch": "jest --watch"
   },
   "devDependencies": {
     "@types/pg": "^8.16.0",
     "makage": "^0.1.9"
   },
-  "keywords": [
-    "postgresql",
-    "query",
-    "context",
-    "pg",
-    "graphile"
-  ]
+  "dependencies": {
+    "@pgpmjs/core": "^4.5.1",
+    "@pgpmjs/logger": "^1.3.5",
+    "@pgpmjs/types": "^2.12.8",
+    "pg": "^8.16.3",
+    "pg-env": "^1.2.4"
+  },
+  "gitHead": "6883e3b93da28078483bc6aa25862613ef4405b2"
 }

package/roles.d.ts

@@ -0,0 +1,17 @@
+import { PgTestConnectionOptions, RoleMapping } from '@pgpmjs/types';
+/**
+ * Default role mapping configuration
+ */
+export declare const DEFAULT_ROLE_MAPPING: Required<RoleMapping>;
+/**
+ * Get resolved role mapping with defaults
+ */
+export declare const getRoleMapping: (options?: PgTestConnectionOptions) => Required<RoleMapping>;
+/**
+ * Get role name by key with fallback to default mapping
+ */
+export declare const getRoleName: (roleKey: keyof Omit<RoleMapping, "default">, options?: PgTestConnectionOptions) => string;
+/**
+ * Get default role name
+ */
+export declare const getDefaultRole: (options?: PgTestConnectionOptions) => string;

package/roles.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDefaultRole = exports.getRoleName = exports.getRoleMapping = exports.DEFAULT_ROLE_MAPPING = void 0;
+/**
+ * Default role mapping configuration
+ */
+exports.DEFAULT_ROLE_MAPPING = {
+    anonymous: 'anonymous',
+    authenticated: 'authenticated',
+    administrator: 'administrator',
+    default: 'anonymous'
+};
+/**
+ * Get resolved role mapping with defaults
+ */
+const getRoleMapping = (options) => {
+    return {
+        ...exports.DEFAULT_ROLE_MAPPING,
+        ...(options?.roles || {})
+    };
+};
+exports.getRoleMapping = getRoleMapping;
+/**
+ * Get role name by key with fallback to default mapping
+ */
+const getRoleName = (roleKey, options) => {
+    const mapping = (0, exports.getRoleMapping)(options);
+    return mapping[roleKey];
+};
+exports.getRoleName = getRoleName;
+/**
+ * Get default role name
+ */
+const getDefaultRole = (options) => {
+    const mapping = (0, exports.getRoleMapping)(options);
+    return mapping.default;
+};
+exports.getDefaultRole = getDefaultRole;

package/stream.d.ts

@@ -0,0 +1,33 @@
+import { PgConfig } from 'pg-env';
+/**
+ * Executes SQL statements by streaming them to psql.
+ *
+ * IMPORTANT: PostgreSQL stderr handling
+ * -------------------------------------
+ * PostgreSQL sends different message types to stderr, not just errors:
+ *   - ERROR: Actual SQL errors (should fail)
+ *   - WARNING: Potential issues (informational)
+ *   - NOTICE: Informational messages (should NOT fail)
+ *   - INFO: Informational messages (should NOT fail)
+ *   - DEBUG: Debug messages (should NOT fail)
+ *
+ * Example scenario that previously caused false failures:
+ * When running SQL like:
+ *   GRANT administrator TO app_user;
+ *
+ * If app_user is already a member of administrator, PostgreSQL outputs:
+ *   NOTICE: role "app_user" is already a member of role "administrator"
+ *
+ * This is NOT an error - the GRANT succeeded (it's idempotent). But because
+ * this message goes to stderr, the old implementation would reject the promise
+ * and fail the test, even though nothing was wrong.
+ *
+ * Solution:
+ * 1. Buffer stderr instead of rejecting immediately on any output
+ * 2. Use ON_ERROR_STOP=1 so psql exits with non-zero code on actual SQL errors
+ * 3. Only reject if the exit code is non-zero, using buffered stderr as the error message
+ *
+ * This way, NOTICE/WARNING messages are collected but don't cause failures,
+ * while actual SQL errors still properly fail with meaningful error messages.
+ */
+export declare function streamSql(config: PgConfig, sql: string): Promise<void>;