pgsql-test 0.0.1 → 2.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Dan Lynch <pyramation@gmail.com>
+
+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

@@ -1,61 +1,257 @@
 # pgsql-test
 
-<p align="center">
-  <img src="https://user-images.githubusercontent.com/545047/188804067-28e67e5e-0214-4449-ab04-2e0c564a6885.svg" width="80"><br />
-    PostgreSQL Testing in TypeScript
+<p align="center" width="100%">
+  <img height="250" src="https://github.com/user-attachments/assets/d0456af5-b6e9-422e-a45d-2574d5be490f" />
 </p>
 
-## install
+<p align="center" width="100%">
+  <a href="https://github.com/launchql/launchql-2.0/actions/workflows/run-tests.yaml">
+    <img height="20" src="https://github.com/launchql/launchql-2.0/actions/workflows/run-tests.yaml/badge.svg" />
+  </a>
+  <a href="https://github.com/launchql/launchql-2.0/blob/main/LICENSE-MIT">
+    <img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/>
+  </a>
+  <a href="https://www.npmjs.com/package/pgsql-test">
+    <img height="20" src="https://img.shields.io/github/package-json/v/launchql/launchql-2.0?filename=packages%2Fpgsql-test%2Fpackage.json"/>
+  </a>
+</p>
+
+
+`pgsql-test` provides an isolated PostgreSQL testing environment with per-test transaction rollback, ideal for integration tests involving SQL, roles, simulations, and complex migrations. With automatic rollbacks and isolated contexts, it eliminates test interference while delivering tight feedback loops for happier developers. We made database testing simple so you can focus on writing good tests instead of fighting your environment.
+
+## Install
 
 ```sh
 npm install pgsql-test
 ```
-## Table of contents
 
-- [pgsql-test](#pgsql-test)
-  - [Install](#install)
-  - [Table of contents](#table-of-contents)
-- [Developing](#developing)
-- [Credits](#credits)
+## Features
 
-## Developing
+* ⚡ Quick-start setup with `getConnections()`
+* 🧹 Easy teardown and cleanup
+* 🔄 Per-test isolation using transactions and savepoints
+* 🛡️ Role-based context for RLS testing
+* 🌱 Flexible seed support via `.sql` files and programmatic functions
+* 🧪 Auto-generated test databases with `UUID` suffix
+* 📦 Built for tools like `sqitch`, supporting full schema initialization workflows
+* 🧰 Designed for `Jest`, `Mocha`, or any async test runner
 
-When first cloning the repo:
 
-```sh
-yarn
-# build the prod packages. When devs would like to navigate to the source code, this will only navigate from references to their definitions (.d.ts files) between packages.
-yarn build
+## Table of Contents
+
+1. [Install](#install)
+2. [Features](#features)
+3. [Quick Start](#quick-start)
+4. [getConnections() Overview](#getconnections-overview)
+5. [PgTestClient API Overview](#pgtestclient-api-overview)
+6. [Usage Examples](#usage-examples)
+   * [Basic Setup](#basic-setup)
+   * [Role-Based Context](#role-based-context)
+   * [SQL File Seeding](#sql-file-seeding)
+   * [Programmatic Seeding](#programmatic-seeding)
+   * [Composed Seeding](#composed-seeding)
+7. [Environment Overrides](#environment-overrides)
+8. [Disclaimer](#disclaimer)
+
+
+## ✨ Quick Start
+
+```ts
+import { getConnections } from 'pgsql-test';
+
+let db, teardown;
+
+beforeAll(async () => {
+  ({ db, teardown } = await getConnections());
+  await db.query(`SELECT 1`); // ✅ Ready to run queries
+});
+
+afterAll(() => teardown());
 ```
 
-Or if you want to make your dev process smoother, you can run:
+## `getConnections()` Overview
 
-```sh
-yarn
-# build the dev packages with .map files, this enables navigation from references to their source code between packages.
-yarn build:dev
+The `getConnections()` helper sets up a fresh PostgreSQL test database and returns a structured object with:
+
+* `pg`: a `PgTestClient` connected as the root or superuser — useful for administrative setup or introspection
+* `db`: a `PgTestClient` connected as the app-level user — used for running tests with RLS and granted permissions
+* `admin`: a `DbAdmin` utility for managing database state, extensions, roles, and templates
+* `teardown()`: a function that shuts down the test environment and database pool
+* `manager`: a shared connection pool manager (`PgTestConnector`) behind both clients
+
+Together, these allow fast, isolated, role-aware test environments with per-test rollback and full control over setup and teardown.
+
+The `PgTestClient` returned by `getConnections()` is a fully-featured wrapper around `pg.Pool`. It provides:
+
+* Automatic transaction and savepoint management for test isolation
+* Easy switching of role-based contexts for RLS testing
+* A clean, high-level API for integration testing PostgreSQL systems
+
+## `PgTestClient` API Overview
+
+The `PgTestClient` returned by `getConnections()` wraps a `pg.Client` and provides convenient helpers for query execution, test isolation, and context switching.
+
+### Common Methods
+
+* `query(sql, values?)` – Run a raw SQL query and get the `QueryResult`
+* `beforeEach()` – Begins a transaction and sets a savepoint (called at the start of each test)
+* `afterEach()` – Rolls back to the savepoint and commits the outer transaction (cleans up test state)
+* `setContext({ key: value })` – Sets PostgreSQL config variables (like `role`) to simulate RLS contexts
+* `any`, `one`, `oneOrNone`, `many`, `manyOrNone`, `none`, `result` – Typed query helpers for specific result expectations
+
+These methods make it easier to build expressive and isolated integration tests with strong typing and error handling.
+
+The `PgTestClient` returned by `getConnections()` is a fully-featured wrapper around `pg.Pool`. It provides:
+
+* Automatic transaction and savepoint management for test isolation
+* Easy switching of role-based contexts for RLS testing
+* A clean, high-level API for integration testing PostgreSQL systems
+
+## Usage Examples
+
+### ⚡ Basic Setup
+
+```ts
+import { getConnections } from 'pgsql-test';
+
+let db; // A fully wrapped PgTestClient using pg.Pool with savepoint-based rollback per test
+let teardown;
+
+beforeAll(async () => {
+  ({ db, teardown } = await getConnections());
+
+  await db.query(`
+    CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT);
+    CREATE TABLE posts (id SERIAL PRIMARY KEY, user_id INT REFERENCES users(id), content TEXT);
+
+    INSERT INTO users (name) VALUES ('Alice'), ('Bob');
+    INSERT INTO posts (user_id, content) VALUES (1, 'Hello world!'), (2, 'Graphile is cool!');
+  `);
+});
+
+afterAll(() => teardown());
+
+beforeEach(() => db.beforeEach());
+afterEach(() => db.afterEach());
+
+test('user count starts at 2', async () => {
+  const res = await db.query('SELECT COUNT(*) FROM users');
+  expect(res.rows[0].count).toBe('2');
+});
+```
+
+### 🔐 Role-Based Context
+
+```ts
+describe('authenticated role', () => {
+  beforeEach(async () => {
+    db.setContext({ role: 'authenticated' });
+    await db.beforeEach();
+  });
+
+  afterEach(() => db.afterEach());
+
+  it('runs as authenticated', async () => {
+    const res = await db.query(`SELECT current_setting('role', true) AS role`);
+    expect(res.rows[0].role).toBe('authenticated');
+  });
+});
+```
+
+### 🔌 SQL File Seeding
+
+Use `.sql` files to set up your database state before tests:
+
+```ts
+import path from 'path';
+import { getConnections, seed } from 'pgsql-test';
+
+const sql = (f: string) => path.join(__dirname, 'sql', f);
+
+let db;
+let teardown;
+
+beforeAll(async () => {
+  ({ db, teardown } = await getConnections({}, seed.sqlfile([
+    sql('schema.sql'),
+    sql('fixtures.sql')
+  ])));
+});
+
+afterAll(async () => {
+  await teardown();
+});
+```
+
+### 🧠 Programmatic Seeding
+
+Use JavaScript functions to insert seed data:
+
+```ts
+import { getConnections, seed } from 'pgsql-test';
+
+let db;
+let teardown;
+
+beforeAll(async () => {
+  ({ db, teardown } = await getConnections({}, seed.fn(async ({ pg }) => {
+    await pg.query(`
+      INSERT INTO users (name) VALUES ('Seeded User');
+    `);
+  })));
+});
+```
+
+### 🧬 Composed Seeding
+
+Combine multiple seeders with `seed.compose()`:
+
+```ts
+import path from 'path';
+import { getConnections, seed } from 'pgsql-test';
+
+const sql = (f: string) => path.join(__dirname, 'sql', f);
+
+let db;
+let teardown;
+
+beforeAll(async () => {
+  ({ db, teardown } = await getConnections({}, seed.compose([
+    seed.sqlfile([
+      sql('schema.sql'),
+      sql('roles.sql')
+    ]),
+    seed.fn(async ({ pg }) => {
+      await pg.query(`INSERT INTO users (name) VALUES ('Composed');`);
+    })
+  ])));
+});
 ```
 
-## Interchain JavaScript Stack 
+---
 
-A unified toolkit for building applications and smart contracts in the Interchain ecosystem ⚛️
+These examples show how flexible `pgsql-test` is for composing repeatable and transactional test database environments.
 
-| Category              | Tools                                                                                                                  | Description                                                                                           |
-|----------------------|------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------|
-| **Chain Information**   | [**Chain Registry**](https://github.com/hyperweb-io/chain-registry), [**Utils**](https://www.npmjs.com/package/@chain-registry/utils), [**Client**](https://www.npmjs.com/package/@chain-registry/client) | Everything from token symbols, logos, and IBC denominations for all assets you want to support in your application. |
-| **Wallet Connectors**| [**Interchain Kit**](https://github.com/hyperweb-io/interchain-kit)<sup>beta</sup>, [**Cosmos Kit**](https://github.com/hyperweb.io/cosmos-kit) | Experience the convenience of connecting with a variety of web3 wallets through a single, streamlined interface. |
-| **Signing Clients**          | [**InterchainJS**](https://github.com/hyperweb-io/interchainjs)<sup>beta</sup>, [**CosmJS**](https://github.com/cosmos/cosmjs) | A single, universal signing interface for any network |
-| **SDK Clients**              | [**Telescope**](https://github.com/hyperweb.io/telescope)                                                          | Your Frontend Companion for Building with TypeScript with Cosmos SDK Modules. |
-| **Starter Kits**     | [**Create Interchain App**](https://github.com/hyperweb-io/create-interchain-app)<sup>beta</sup>, [**Create Cosmos App**](https://github.com/hyperweb.io/create-cosmos-app) | Set up a modern Interchain app by running one command. |
-| **UI Kits**          | [**Interchain UI**](https://github.com/hyperweb.io/interchain-ui)                                                   | The Interchain Design System, empowering developers with a flexible, easy-to-use UI kit. |
-| **Testing Frameworks**          | [**Starship**](https://github.com/hyperweb.io/starship)                                                             | Unified Testing and Development for the Interchain. |
-| **TypeScript Smart Contracts** | [**Create Hyperweb App**](https://github.com/hyperweb-io/create-hyperweb-app)                              | Build and deploy full-stack blockchain applications with TypeScript |
-| **CosmWasm Contracts** | [**CosmWasm TS Codegen**](https://github.com/CosmWasm/ts-codegen)                                                   | Convert your CosmWasm smart contracts into dev-friendly TypeScript classes. |
 
-## Credits
 
-🛠 Built by Hyperweb (formerly Cosmology) — if you like our tools, please checkout and contribute to [our github ⚛️](https://github.com/hyperweb-io)
+## Environment Overrides
 
+`pgsql-test` respects the following env vars for DB connectivity:
+
+* `PGHOST`
+* `PGPORT`
+* `PGUSER`
+* `PGPASSWORD`
+
+Override them in your test runner or CI config:
+
+```yaml
+env:
+  PGHOST: localhost
+  PGPORT: 5432
+  PGUSER: postgres
+  PGPASSWORD: password
+```
 
 ## Disclaimer
 

package/admin.d.ts

@@ -0,0 +1,24 @@
+import { PgConfig } from '@launchql/types';
+import { SeedAdapter } from './seed';
+export declare class DbAdmin {
+    private config;
+    private verbose;
+    constructor(config: PgConfig, verbose?: boolean);
+    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): Promise<void>;
+    loadSql(file: string, dbName: string): void;
+    streamSql(sql: string, dbName: string): Promise<void>;
+    createSeededTemplate(templateName: string, adapter: SeedAdapter): Promise<void>;
+}

package/admin.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DbAdmin = void 0;
+const child_process_1 = require("child_process");
+const types_1 = require("@launchql/types");
+const fs_1 = require("fs");
+const stream_1 = require("./stream");
+class DbAdmin {
+    config;
+    verbose;
+    constructor(config, verbose = false) {
+        this.config = config;
+        this.verbose = verbose;
+        this.config = (0, types_1.getPgEnvOptions)(config);
+    }
+    getEnv() {
+        return {
+            PGHOST: this.config.host,
+            PGPORT: String(this.config.port),
+            PGUSER: this.config.user,
+            PGPASSWORD: this.config.password,
+        };
+    }
+    run(command) {
+        (0, child_process_1.execSync)(command, {
+            stdio: this.verbose ? 'inherit' : 'pipe',
+            env: {
+                ...process.env,
+                ...this.getEnv(),
+            },
+        });
+    }
+    safeDropDb(name) {
+        try {
+            this.run(`dropdb "${name}"`);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (!message.includes('does not exist')) {
+                console.warn(`⚠️  Could not drop database ${name}: ${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 { }
+        this.safeDropDb(template);
+    }
+    async grantRole(role, user, dbName) {
+        const db = dbName ?? this.config.database;
+        const sql = `GRANT ${role} TO ${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);
+    }
+    async createUserRole(user, password, dbName) {
+        const sql = `
+  DO $$
+  BEGIN
+    IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = '${user}') THEN
+      CREATE ROLE ${user} LOGIN PASSWORD '${password}';
+      GRANT anonymous TO ${user};
+      GRANT authenticated TO ${user};
+    END IF;
+  END $$;
+    `.trim();
+        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);
+    }
+    async createSeededTemplate(templateName, adapter) {
+        const seedDb = this.config.database;
+        this.create(seedDb);
+        await adapter.seed({
+            admin: this,
+            config: this.config,
+            pg: null // sorry!
+        });
+        this.cleanupTemplate(templateName);
+        this.createTemplateFromBase(seedDb, templateName);
+        this.drop(seedDb);
+    }
+}
+exports.DbAdmin = DbAdmin;

package/connect.d.ts

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

package/connect.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getConnections = exports.getPgRootAdmin = void 0;
+const admin_1 = require("./admin");
+const types_1 = require("@launchql/types");
+const migrate_1 = require("@launchql/migrate");
+const manager_1 = require("./manager");
+const crypto_1 = require("crypto");
+const server_utils_1 = require("@launchql/server-utils");
+let manager;
+const getPgRootAdmin = (connOpts = {}) => {
+    const opts = (0, types_1.getPgEnvOptions)({
+        database: connOpts.rootDb
+    });
+    const admin = new admin_1.DbAdmin(opts);
+    return admin;
+};
+exports.getPgRootAdmin = getPgRootAdmin;
+const getConnOopts = (cn = {}) => {
+    const connect = (0, types_1.getConnEnvOptions)(cn.db);
+    const config = (0, types_1.getPgEnvOptions)({
+        database: `${connect.prefix}${(0, crypto_1.randomUUID)()}`,
+        ...cn.pg
+    });
+    return {
+        pg: config,
+        db: connect
+    };
+};
+const getConnections = async (cn = {}, seedAdapter) => {
+    cn = getConnOopts(cn);
+    const config = cn.pg;
+    const connOpts = cn.db;
+    const root = (0, exports.getPgRootAdmin)(connOpts);
+    await root.createUserRole(connOpts.connection.user, connOpts.connection.password, connOpts.rootDb);
+    const admin = new admin_1.DbAdmin(config);
+    const proj = new migrate_1.LaunchQLProject(connOpts.cwd);
+    if (proj.isInModule()) {
+        admin.create(config.database);
+        admin.installExtensions(connOpts.extensions);
+        const opts = (0, types_1.getEnvOptions)({
+            pg: config
+        });
+        if (connOpts.deployFast) {
+            await (0, migrate_1.deployFast)({
+                opts,
+                name: proj.getModuleName(),
+                database: config.database,
+                dir: proj.modulePath,
+                usePlan: true,
+                verbose: false
+            });
+        }
+        else {
+            await (0, migrate_1.deploy)(opts, proj.getModuleName(), config.database, proj.modulePath);
+        }
+    }
+    else {
+        // Create the test database
+        if (process.env.TEST_DB) {
+            config.database = process.env.TEST_DB;
+        }
+        else if (connOpts.template) {
+            admin.createFromTemplate(connOpts.template, config.database);
+        }
+        else {
+            admin.create(config.database);
+            admin.installExtensions(connOpts.extensions);
+        }
+    }
+    await admin.grantConnect(connOpts.connection.user, config.database);
+    // Main admin client (optional unless needed elsewhere)
+    manager = manager_1.PgTestConnector.getInstance();
+    const pg = manager.getClient(config);
+    if (seedAdapter) {
+        await seedAdapter.seed({
+            admin,
+            config: config,
+            pg: manager.getClient(config)
+        });
+    }
+    // App user connection
+    const db = manager.getClient({
+        ...config,
+        user: connOpts.connection.user,
+        password: connOpts.connection.password
+    });
+    db.setContext({ role: 'anonymous' });
+    const teardown = async () => {
+        await (0, server_utils_1.teardownPgPools)();
+        await manager.closeAll();
+    };
+    return { pg, db, teardown, manager, admin };
+};
+exports.getConnections = getConnections;