pgsql-seed 0.0.1

package/esm/manager.js

@@ -0,0 +1,138 @@
+import { Logger } from '@pgpmjs/logger';
+import { Pool } from 'pg';
+import { getPgEnvOptions } from 'pg-env';
+import { DbAdmin } from './admin';
+import { PgTestClient } from './test-client';
+const log = new Logger('test-connector');
+const SYS_EVENTS = ['SIGTERM'];
+const end = (pool) => {
+    try {
+        if (pool.ended || pool.ending) {
+            log.warn('⚠️ pg pool already ended or ending');
+            return;
+        }
+        pool.end();
+    }
+    catch (err) {
+        log.error('❌ pg pool termination error:', err);
+    }
+};
+export class PgTestConnector {
+    static instance;
+    clients = new Set();
+    pgPools = new Map();
+    seenDbConfigs = new Map();
+    pendingConnects = new Set();
+    config;
+    verbose = false;
+    shuttingDown = false;
+    constructor(config, verbose = false) {
+        this.verbose = verbose;
+        this.config = config;
+        SYS_EVENTS.forEach((event) => {
+            process.on(event, () => {
+                log.info(`⏹ Received ${event}, closing all connections...`);
+                this.closeAll();
+            });
+        });
+    }
+    static getInstance(config, verbose = false) {
+        if (!PgTestConnector.instance) {
+            PgTestConnector.instance = new PgTestConnector(config, verbose);
+        }
+        return PgTestConnector.instance;
+    }
+    poolKey(config) {
+        return `${config.user}@${config.host}:${config.port}/${config.database}`;
+    }
+    dbKey(config) {
+        return `${config.host}:${config.port}/${config.database}`;
+    }
+    beginTeardown() {
+        this.shuttingDown = true;
+    }
+    registerConnect(p) {
+        this.pendingConnects.add(p);
+        p.finally(() => this.pendingConnects.delete(p));
+    }
+    async awaitPendingConnects() {
+        const arr = Array.from(this.pendingConnects);
+        if (arr.length) {
+            await Promise.allSettled(arr);
+        }
+    }
+    getPool(config) {
+        const key = this.poolKey(config);
+        if (!this.pgPools.has(key)) {
+            const pool = new Pool(config);
+            this.pgPools.set(key, pool);
+            log.info(`📘 Created new pg pool: ${key}`);
+        }
+        return this.pgPools.get(key);
+    }
+    getClient(config, opts = {}) {
+        if (this.shuttingDown) {
+            throw new Error('PgTestConnector is shutting down; no new clients allowed');
+        }
+        const client = new PgTestClient(config, {
+            trackConnect: (p) => this.registerConnect(p),
+            ...opts
+        });
+        this.clients.add(client);
+        const key = this.dbKey(config);
+        this.seenDbConfigs.set(key, config);
+        log.info(`🔌 New PgTestClient connected to ${config.database}`);
+        return client;
+    }
+    async closeAll() {
+        this.beginTeardown();
+        await this.awaitPendingConnects();
+        log.info('🧹 Closing all PgTestClients...');
+        await Promise.all(Array.from(this.clients).map(async (client) => {
+            try {
+                await client.close();
+                log.success(`✅ Closed client for ${client.config.database}`);
+            }
+            catch (err) {
+                log.error(`❌ Error closing PgTestClient for ${client.config.database}:`, err);
+            }
+        }));
+        this.clients.clear();
+        log.info('🧯 Disposing pg pools...');
+        for (const [key, pool] of this.pgPools.entries()) {
+            log.debug(`🧯 Disposing pg pool [${key}]`);
+            end(pool);
+        }
+        this.pgPools.clear();
+        log.info('🗑️ Dropping seen databases...');
+        await Promise.all(Array.from(this.seenDbConfigs.values()).map(async (config) => {
+            try {
+                const rootPg = getPgEnvOptions(this.config);
+                const admin = new DbAdmin({ ...config, user: rootPg.user, password: rootPg.password }, this.verbose);
+                admin.drop();
+                log.warn(`🧨 Dropped database: ${config.database}`);
+            }
+            catch (err) {
+                log.error(`❌ Failed to drop database ${config.database}:`, err);
+            }
+        }));
+        this.seenDbConfigs.clear();
+        log.success('✅ All PgTestClients closed, pools disposed, databases dropped.');
+        this.pendingConnects.clear();
+        this.shuttingDown = false;
+    }
+    close() {
+        this.closeAll();
+    }
+    drop(config) {
+        const key = this.dbKey(config);
+        const admin = new DbAdmin(config, this.verbose);
+        admin.drop();
+        log.warn(`🧨 Dropped database: ${config.database}`);
+        this.seenDbConfigs.delete(key);
+    }
+    async kill(client) {
+        await client.close();
+        this.drop(client.config);
+    }
+}

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/seed/adapters.js

@@ -0,0 +1,23 @@
+export function sqlfile(files) {
+    return {
+        seed(ctx) {
+            for (const file of files) {
+                ctx.admin.loadSql(file, ctx.config.database);
+            }
+        }
+    };
+}
+export function fn(fn) {
+    return {
+        seed: fn
+    };
+}
+export function compose(adapters) {
+    return {
+        async seed(ctx) {
+            for (const adapter of adapters) {
+                await adapter.seed(ctx);
+            }
+        }
+    };
+}

package/esm/seed/csv.js

@@ -0,0 +1,108 @@
+import { pipeline } from 'node:stream/promises';
+import { Logger } from '@pgpmjs/logger';
+import { parse } from 'csv-parse';
+import { createReadStream, createWriteStream, existsSync } from 'fs';
+import { from as copyFrom, to as copyTo } from 'pg-copy-streams';
+const log = new Logger('csv');
+/**
+ * Standalone helper function to load CSV files into PostgreSQL tables
+ * @param client - PostgreSQL client instance
+ * @param tables - Map of table names to CSV file paths
+ */
+export async function loadCsvMap(client, tables) {
+    for (const [table, filePath] of Object.entries(tables)) {
+        if (!existsSync(filePath)) {
+            throw new Error(`CSV file not found: ${filePath}`);
+        }
+        log.info(`📥 Seeding "${table}" from ${filePath}`);
+        const columns = await parseCsvHeader(filePath);
+        const quotedColumns = columns.map(col => `"${col.replace(/"/g, '""')}"`);
+        const columnList = quotedColumns.join(', ');
+        const copyCommand = `COPY ${table} (${columnList}) FROM STDIN WITH CSV HEADER`;
+        log.info(`Using columns: ${columnList}`);
+        const stream = client.query(copyFrom(copyCommand));
+        const source = createReadStream(filePath);
+        try {
+            await pipeline(source, stream);
+            log.success(`✅ Successfully seeded "${table}"`);
+        }
+        catch (err) {
+            log.error(`❌ COPY failed for "${table}": ${err.message}`);
+            throw err;
+        }
+    }
+}
+export function csv(tables) {
+    return {
+        async seed(ctx) {
+            for (const [table, filePath] of Object.entries(tables)) {
+                if (!existsSync(filePath)) {
+                    throw new Error(`CSV file not found: ${filePath}`);
+                }
+                log.info(`📥 Seeding "${table}" from ${filePath}`);
+                await copyCsvIntoTable(ctx.pg, table, filePath);
+            }
+        }
+    };
+}
+async function parseCsvHeader(filePath) {
+    const file = createReadStream(filePath);
+    const parser = parse({
+        bom: true,
+        to_line: 1,
+        skip_empty_lines: true,
+    });
+    return new Promise((resolve, reject) => {
+        const cleanup = (err) => {
+            parser.destroy();
+            file.destroy();
+            if (err)
+                reject(err);
+        };
+        parser.on('readable', () => {
+            const row = parser.read();
+            if (!row)
+                return;
+            if (row.length === 0) {
+                cleanup(new Error('CSV header has no columns'));
+                return;
+            }
+            cleanup();
+            resolve(row);
+        });
+        parser.on('error', cleanup);
+        file.on('error', cleanup);
+        file.pipe(parser);
+    });
+}
+export async function copyCsvIntoTable(pg, table, filePath) {
+    const client = pg.client;
+    const columns = await parseCsvHeader(filePath);
+    const quotedColumns = columns.map(col => `"${col.replace(/"/g, '""')}"`);
+    const columnList = quotedColumns.join(', ');
+    const copyCommand = `COPY ${table} (${columnList}) FROM STDIN WITH CSV HEADER`;
+    log.info(`Using columns: ${columnList}`);
+    const stream = client.query(copyFrom(copyCommand));
+    const source = createReadStream(filePath);
+    try {
+        await pipeline(source, stream);
+        log.success(`✅ Successfully seeded "${table}"`);
+    }
+    catch (err) {
+        log.error(`❌ COPY failed for "${table}": ${err.message}`);
+        throw err;
+    }
+}
+export async function exportTableToCsv(pg, table, filePath) {
+    const client = pg.client;
+    const stream = client.query(copyTo(`COPY ${table} TO STDOUT WITH CSV HEADER`));
+    const target = createWriteStream(filePath);
+    try {
+        await pipeline(stream, target);
+        log.success(`✅ Exported "${table}" to ${filePath}`);
+    }
+    catch (err) {
+        log.error(`❌ Failed to export "${table}": ${err.message}`);
+        throw err;
+    }
+}

package/esm/seed/index.js

@@ -0,0 +1,14 @@
+import { compose, fn, sqlfile } from './adapters';
+import { csv } from './csv';
+import { json } from './json';
+import { pgpm } from './pgpm';
+export * from './csv';
+export * from './types';
+export const seed = {
+    pgpm,
+    json,
+    csv,
+    compose,
+    fn,
+    sqlfile
+};

package/esm/seed/json.js

@@ -0,0 +1,36 @@
+/**
+ * Standalone helper function to insert JSON data into PostgreSQL tables
+ * @param client - PostgreSQL client instance
+ * @param data - Map of table names to arrays of row objects
+ */
+export async function insertJson(client, data) {
+    for (const [table, rows] of Object.entries(data)) {
+        if (!Array.isArray(rows) || rows.length === 0)
+            continue;
+        const columns = Object.keys(rows[0]);
+        const placeholders = columns.map((_, i) => `$${i + 1}`).join(', ');
+        const sql = `INSERT INTO ${table} (${columns.join(', ')}) VALUES (${placeholders})`;
+        for (const row of rows) {
+            const values = columns.map((c) => row[c]);
+            await client.query(sql, values);
+        }
+    }
+}
+export function json(data) {
+    return {
+        async seed(ctx) {
+            const { pg } = ctx;
+            for (const [table, rows] of Object.entries(data)) {
+                if (!Array.isArray(rows) || rows.length === 0)
+                    continue;
+                const columns = Object.keys(rows[0]);
+                const placeholders = columns.map((_, i) => `$${i + 1}`).join(', ');
+                const sql = `INSERT INTO ${table} (${columns.join(', ')}) VALUES (${placeholders})`;
+                for (const row of rows) {
+                    const values = columns.map((c) => row[c]);
+                    await pg.query(sql, values);
+                }
+            }
+        }
+    };
+}

package/esm/seed/pgpm.js

@@ -0,0 +1,28 @@
+import { PgpmPackage } from '@pgpmjs/core';
+import { getEnvOptions } from '@pgpmjs/env';
+/**
+ * Standalone helper function to deploy pgpm package
+ * @param config - PostgreSQL configuration
+ * @param cwd - Current working directory (defaults to process.cwd())
+ * @param cache - Whether to enable caching (defaults to false)
+ */
+export async function deployPgpm(config, cwd, cache = false) {
+    const proj = new PgpmPackage(cwd ?? process.cwd());
+    if (!proj.isInModule())
+        return;
+    await proj.deploy(getEnvOptions({
+        pg: config,
+        deployment: {
+            fast: true,
+            usePlan: true,
+            cache
+        }
+    }), proj.getModuleName());
+}
+export function pgpm(cwd, cache = false) {
+    return {
+        async seed(ctx) {
+            await deployPgpm(ctx.config, cwd ?? ctx.connect.cwd, cache);
+        }
+    };
+}

package/esm/seed/sql.js

@@ -0,0 +1,15 @@
+import { existsSync, readFileSync } from 'fs';
+/**
+ * Standalone helper function to load SQL files into PostgreSQL
+ * @param client - PostgreSQL client instance
+ * @param files - Array of SQL file paths to execute
+ */
+export async function loadSqlFiles(client, files) {
+    for (const file of files) {
+        if (!existsSync(file)) {
+            throw new Error(`SQL file not found: ${file}`);
+        }
+        const sql = readFileSync(file, 'utf-8');
+        await client.query(sql);
+    }
+}

package/esm/seed/types.js

@@ -0,0 +1 @@
+export {};

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/esm/test-client.js

@@ -0,0 +1,168 @@
+import { Client } from 'pg';
+import { getRoleName } from './roles';
+import { generateContextStatements } from './context-utils';
+import { insertJson } from './seed/json';
+import { loadCsvMap } from './seed/csv';
+import { loadSqlFiles } from './seed/sql';
+import { deployPgpm } from './seed/pgpm';
+export class PgTestClient {
+    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();
+            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;');
+    }
+    async beforeEach() {
+        await this.begin();
+        await this.savepoint();
+    }
+    async afterEach() {
+        await this.rollback();
+        await this.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
+        });
+    }
+    /**
+     * Commit current transaction to make data visible to other connections, then start fresh transaction.
+     * Maintains test isolation by creating a savepoint and reapplying session context.
+     */
+    async publish() {
+        await this.commit(); // make data visible to other sessions
+        await this.begin(); // fresh tx
+        await this.savepoint(); // keep rollback harness
+        await this.ctxQuery(); // reapply all setContext()
+    }
+    /**
+     * 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;
+    }
+    async loadJson(data) {
+        await this.ctxQuery();
+        await insertJson(this.client, data);
+    }
+    async loadSql(files) {
+        await this.ctxQuery();
+        await loadSqlFiles(this.client, files);
+    }
+    // NON-RLS load/seed methods:
+    async loadCsv(tables) {
+        // await this.ctxQuery(); // no point to call ctxQuery() here
+        // because POSTGRES doesn't support row-level security on COPY FROM...
+        await loadCsvMap(this.client, tables);
+    }
+    async loadPgpm(cwd, cache = false) {
+        // await this.ctxQuery(); // no point to call ctxQuery() here
+        // because deployPgpm() has it's own way of getting the client...
+        // so for now, we'll expose this but it's limited
+        await deployPgpm(this.config, cwd, cache);
+    }
+}