pgsql-test 0.0.1

package/README.md

@@ -0,0 +1,64 @@
+# 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>
+
+## 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)
+
+## Developing
+
+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
+```
+
+Or if you want to make your dev process smoother, you can run:
+
+```sh
+yarn
+# build the dev packages with .map files, this enables navigation from references to their source code between packages.
+yarn build:dev
+```
+
+## Interchain JavaScript Stack 
+
+A unified toolkit for building applications and smart contracts in the Interchain ecosystem ⚛️
+
+| 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)
+
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED “AS IS”, AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/__tests__/postgres-test.connections.test.ts

@@ -0,0 +1,81 @@
+import { getConnections } from '../src/connect';
+import { PgTestClient } from '../src/test-client';
+
+let conn: PgTestClient;
+let db: PgTestClient;
+let teardown: () => Promise<void>;
+
+beforeAll(async () => {
+  ({ conn, db, teardown } = await getConnections());
+
+  // Setup schema + seed ONCE globally
+  await db.query(`
+    CREATE TABLE users (
+      id SERIAL PRIMARY KEY,
+      name TEXT NOT NULL
+    );
+    CREATE TABLE posts (
+      id SERIAL PRIMARY KEY,
+      user_id INT NOT NULL REFERENCES users(id),
+      content TEXT NOT NULL
+    );
+  `);
+
+  await db.query(`
+    INSERT INTO users (name) VALUES ('Alice'), ('Bob');
+    INSERT INTO posts (user_id, content) VALUES
+      (1, 'Hello world!'),
+      (2, 'Graphile is cool!');
+  `);
+});
+
+afterAll(async () => {
+  await teardown();
+});
+
+describe('anonymous', () => {
+  beforeEach(async () => {
+    await db.beforeEach();  // this starts tx + savepoint
+  });
+
+  afterEach(async () => {
+    await db.afterEach();   // this rolls back and commits
+  });
+
+  it('inserts a user but rollback leaves baseline intact', async () => {
+    await db.query(`INSERT INTO users (name) VALUES ('Carol')`);
+    const res = await db.query('SELECT COUNT(*) FROM users');
+    expect(res.rows[0].count).toBe('3');
+  });
+
+  it('should still have 2 users after rollback', async () => {
+    const res = await db.query('SELECT COUNT(*) FROM users');
+    expect(res.rows[0].count).toBe('2');
+  });
+
+  it('runs under anonymous context', async () => {
+    const result = await conn.query('SELECT current_setting(\'role\', true) AS role');
+    console.log(JSON.stringify({result}, null, 2))
+    console.error(JSON.stringify({result}, null, 2))
+    // expect(result.rows[0].role).toBe('anonymous');
+  });
+});
+
+describe('authenticated', () => {
+  beforeEach(async () => {
+    conn.setContext({
+      role: 'authenticated'
+    });
+    await conn.beforeEach();  // required for rollback later
+  });
+
+  afterEach(async () => {
+    await conn.afterEach();   // now safe to rollback
+  });
+
+  it('runs under authenticated context', async () => {
+    const result = await conn.query('SELECT current_setting(\'role\', true) AS role');
+    // expect(result.rows[0].role).toBe('authenticated');
+    console.error('why no JWT')
+  });
+});

package/__tests__/postgres-test.grants.test.ts

@@ -0,0 +1,53 @@
+import { getPgEnvOptions, PgConfig } from '@launchql/types';
+
+import {
+  getConnection,
+  Connection,
+} from '../src';
+import { randomUUID } from 'crypto';
+import { PgTestClient } from '../src/test-client';
+import { DbAdmin } from '../src/admin';
+import { resolve } from 'path';
+
+const sql = (file: string) => resolve(__dirname, '../sql', file);
+
+const TEST_DB_BASE = `postgres_test_${randomUUID()}`; 
+
+function setupBaseDB(config: PgConfig): void {
+  const admin = new DbAdmin(config);
+  admin.create(config.database)
+  admin.loadSql(sql('test.sql'), config.database);
+  admin.loadSql(sql('roles.sql'), config.database);
+  admin.drop(config.database);
+}
+
+const config = getPgEnvOptions({
+    database: TEST_DB_BASE
+});
+
+beforeAll(() => {
+  setupBaseDB(config);
+});
+
+afterAll(() => {
+  Connection.getManager().closeAll();
+});
+
+
+describe('Postgres Test Framework', () => {
+  let db: PgTestClient;
+
+  afterEach(() => {
+    // if (db) closeConnection(db);
+  });
+
+  it('creates a test DB with hot mode (FAST_TEST)', () => {
+    db = getConnection({ hot: true, extensions: ['uuid-ossp'] });
+    expect(db).toBeDefined();
+  });
+
+  it('creates a test DB from scratch (default)', () => {
+    db = getConnection({});
+    expect(db).toBeDefined();
+  });
+});

package/__tests__/postgres-test.records.test.ts

@@ -0,0 +1,66 @@
+import { getConnections } from '../src/connect';
+import { PgTestClient } from '../src/test-client';
+
+let conn: PgTestClient;
+let db: PgTestClient;
+let teardown: () => Promise<void>;
+
+const setupSchemaSQL = `
+  CREATE TABLE users (
+    id SERIAL PRIMARY KEY,
+    name TEXT NOT NULL
+  );
+
+  CREATE TABLE posts (
+    id SERIAL PRIMARY KEY,
+    user_id INT NOT NULL REFERENCES users(id),
+    content TEXT NOT NULL
+  );
+`;
+
+const seedDataSQL = `
+  INSERT INTO users (name) VALUES ('Alice'), ('Bob');
+  INSERT INTO posts (user_id, content) VALUES
+    (1, 'Hello world!'),
+    (2, 'Graphile is cool!');
+`;
+
+beforeAll(async () => {
+  ({ conn, db, teardown } = await getConnections());
+  // create schema + seed *once*
+  await db.query(setupSchemaSQL);
+  await db.query(seedDataSQL);
+});
+
+afterAll(async () => {
+  await teardown();
+});
+
+describe('Postgres Test Framework', () => {
+  beforeEach(async () => {
+    await db.beforeEach();  // BEGIN + SAVEPOINT
+  });
+
+  afterEach(async () => {
+    await db.afterEach();   // ROLLBACK TO SAVEPOINT + COMMIT
+  });
+
+  it('should have 2 users initially', async () => {
+    const { rows } = await db.query('SELECT COUNT(*) FROM users');
+    expect(rows[0].count).toBe('2');
+  });
+
+  it('inserts a user but rollback leaves baseline intact', async () => {
+    await db.query(`INSERT INTO users (name) VALUES ('Carol')`);
+    let res = await db.query('SELECT COUNT(*) FROM users');
+    expect(res.rows[0].count).toBe('3');   // inside this tx
+
+    // after rollback (next test) we’ll still see 2
+  });
+
+  it('still sees 2 users after previous insert test', async () => {
+    const { rows } = await db.query('SELECT COUNT(*) FROM users');
+    expect(rows[0].count).toBe('2');
+  });
+
+});

package/__tests__/postgres-test.template.test.ts

@@ -0,0 +1,52 @@
+import { getPgEnvOptions, PgConfig } from '@launchql/types';
+import path from 'path';
+
+import {
+  getConnection,
+  Connection
+} from '../src';
+import { PgTestClient } from '../src/test-client';
+import { DbAdmin } from '../src/admin';
+
+const sql = (file: string) => path.resolve(__dirname, '../sql', file);
+
+const TEMPLATE_NAME = 'test_template';
+const TEST_DB_BASE = 'postgres_test_db_template';
+
+function setupTemplateDB(config: PgConfig, template: string): void {
+  const admin = new DbAdmin(config);
+  try {
+    admin.drop(config.database);
+  } catch {}
+  admin.create(config.database);
+  admin.loadSql(sql('test.sql'), config.database);
+  admin.loadSql(sql('roles.sql'), config.database);
+  admin.cleanupTemplate(template);
+  admin.createTemplateFromBase(config.database, template);
+  admin.drop(config.database);
+}
+
+const config = getPgEnvOptions({
+    database: TEST_DB_BASE
+});
+
+beforeAll(() => {
+  setupTemplateDB(config, TEMPLATE_NAME);
+});
+
+afterAll(() => {
+  Connection.getManager().closeAll();
+});
+
+describe('Template Database Test', () => {
+  let db: PgTestClient;
+
+  afterEach(() => {
+    // if (db) closeConnection(db);
+  });
+
+  it('creates a test DB from a template', () => {
+    db = getConnection({ template: TEMPLATE_NAME });
+    expect(db).toBeDefined();
+  });
+});

package/__tests__/postgres-test.test.ts

@@ -0,0 +1,36 @@
+import { getPgEnvOptions, PgConfig } from '@launchql/types';
+
+import {
+  getConnection,
+  Connection
+} from '../src';
+import { randomUUID } from 'crypto';
+import { PgTestClient } from '../src/test-client';
+
+const TEST_DB_BASE = `postgres_test_${randomUUID()}`; 
+
+const config = getPgEnvOptions({
+    database: TEST_DB_BASE
+});
+
+afterAll(() => {
+  Connection.getManager().closeAll();
+});
+
+describe('Postgres Test Framework', () => {
+  let db: PgTestClient;
+
+  afterEach(() => {
+    // if (db) closeConnection(db);
+  });
+
+  it('creates a test DB with hot mode (FAST_TEST)', () => {
+    db = getConnection({ hot: true, extensions: ['uuid-ossp'] });
+    expect(db).toBeDefined();
+  });
+
+  it('creates a test DB from scratch (default)', () => {
+    db = getConnection({});
+    expect(db).toBeDefined();
+  });
+});

package/jest.config.js

@@ -0,0 +1,18 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+    preset: "ts-jest",
+    testEnvironment: "node",
+    transform: {
+        "^.+\\.tsx?$": [
+            "ts-jest",
+            {
+                babelConfig: false,
+                tsconfig: "tsconfig.json",
+            },
+        ],
+    },
+    transformIgnorePatterns: [`/node_modules/*`],
+    testRegex: "(/__tests__/.*|(\\.|/)(test|spec))\\.(jsx?|tsx?)$",
+    moduleFileExtensions: ["ts", "tsx", "js", "jsx", "json", "node"],
+    modulePathIgnorePatterns: ["dist/*"]
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "pgsql-test",
+  "version": "0.0.1",
+  "author": "Dan Lynch <pyramation@gmail.com>",
+  "description": "PostgreSQL Testing in TypeScript",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "homepage": "https://github.com/launchql/launchql",
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/launchql/launchql"
+  },
+  "bugs": {
+    "url": "https://github.com/launchql/launchql/issues"
+  },
+  "scripts": {
+    "copy": "copyfiles -f ../../LICENSE README.md package.json dist",
+    "clean": "rimraf dist/**",
+    "prepare": "npm run build",
+    "build": "npm run clean; tsc; tsc -p tsconfig.esm.json; npm run copy",
+    "build:dev": "npm run clean; tsc --declarationMap; tsc -p tsconfig.esm.json; npm run copy",
+    "lint": "eslint . --fix",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "dependencies": {
+    "@launchql/types": "^2.0.4",
+    "chalk": "^4.1.0"
+  }
+}

package/sql/roles.sql

@@ -0,0 +1,48 @@
+BEGIN;
+DO $do$
+BEGIN
+    IF NOT EXISTS (
+        SELECT
+        FROM
+            pg_catalog.pg_roles
+        WHERE
+            rolname = 'administrator') THEN
+    CREATE ROLE administrator;
+END IF;
+    IF NOT EXISTS (
+        SELECT
+        FROM
+            pg_catalog.pg_roles
+        WHERE
+            rolname = 'anonymous') THEN
+    CREATE ROLE anonymous;
+END IF;
+    IF NOT EXISTS (
+        SELECT
+        FROM
+            pg_catalog.pg_roles
+        WHERE
+            rolname = 'authenticated') THEN
+    CREATE ROLE authenticated;
+END IF;
+END
+$do$;
+ALTER USER administrator WITH NOCREATEDB;
+ALTER USER administrator WITH NOCREATEROLE;
+ALTER USER administrator WITH NOLOGIN;
+ALTER USER administrator WITH NOREPLICATION;
+ALTER USER administrator WITH BYPASSRLS;
+ALTER USER anonymous WITH NOCREATEDB;
+ALTER USER anonymous WITH NOCREATEROLE;
+ALTER USER anonymous WITH NOLOGIN;
+ALTER USER anonymous WITH NOREPLICATION;
+ALTER USER anonymous WITH NOBYPASSRLS;
+ALTER USER authenticated WITH NOCREATEDB;
+ALTER USER authenticated WITH NOCREATEROLE;
+ALTER USER authenticated WITH NOLOGIN;
+ALTER USER authenticated WITH NOREPLICATION;
+ALTER USER authenticated WITH NOBYPASSRLS;
+GRANT anonymous TO administrator;
+GRANT authenticated TO administrator;
+COMMIT;
+

package/sql/test.sql

@@ -0,0 +1,36 @@
+-- https://en.wikipedia.org/wiki/Role-based_access_control
+BEGIN;
+CREATE EXTENSION IF NOT EXISTS citext;
+DROP SCHEMA IF EXISTS app_public CASCADE;
+CREATE SCHEMA app_public;
+CREATE TABLE app_public.users (
+    id serial PRIMARY KEY,
+    username citext,
+    UNIQUE (username),
+    CHECK (length(username) < 127)
+);
+CREATE TABLE app_public.roles (
+    id serial PRIMARY KEY,
+    org_id bigint NOT NULL REFERENCES app_public.users (id)
+);
+CREATE TABLE app_public.user_settings (
+    user_id bigint NOT NULL PRIMARY KEY REFERENCES app_public.users (id),
+    setting1 text,
+    UNIQUE (user_id)
+);
+CREATE TABLE app_public.permissions (
+    id serial PRIMARY KEY,
+    name citext
+);
+CREATE TABLE app_public.permission_assignment (
+    perm_id bigint NOT NULL REFERENCES app_public.permissions (id),
+    role_id bigint NOT NULL REFERENCES app_public.roles (id),
+    PRIMARY KEY (perm_id, role_id)
+);
+CREATE TABLE app_public.subject_assignment (
+    subj_id bigint NOT NULL REFERENCES app_public.users (id),
+    role_id bigint NOT NULL REFERENCES app_public.roles (id),
+    PRIMARY KEY (subj_id, role_id)
+);
+COMMIT;
+

package/src/admin.ts

@@ -0,0 +1,135 @@
+import { execSync } from 'child_process';
+import { PgConfig } from '@launchql/types';
+import { existsSync } from 'fs';
+import { streamSql as stream } from './stream';
+
+export class DbAdmin {
+  constructor(
+    private config: PgConfig,
+    private verbose: boolean = false
+  ) { }
+
+  private getEnv(): Record<string, string> {
+    return {
+      PGHOST: this.config.host,
+      PGPORT: String(this.config.port),
+      PGUSER: this.config.user,
+      PGPASSWORD: this.config.password,
+    };
+  }
+
+  private run(command: string): void {
+    execSync(command, {
+      stdio: this.verbose ? 'inherit' : 'pipe',
+      env: {
+        ...process.env,
+        ...this.getEnv(),
+      },
+    });
+  }
+
+  private safeDropDb(name: string): void {
+    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?: string): void {
+    this.safeDropDb(dbName ?? this.config.database);
+  }
+
+  dropTemplate(dbName: string): void {
+    this.run(`psql -c "UPDATE pg_database SET datistemplate='false' WHERE datname='${dbName}';"`);
+    this.drop(dbName);
+  }
+
+  create(dbName?: string): void {
+    const db = dbName ?? this.config.database;
+    this.run(`createdb -U ${this.config.user} -h ${this.config.host} -p ${this.config.port} "${db}"`);
+  }
+
+  createFromTemplate(template: string, dbName?: string): void {
+    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: string[] | string, dbName?: string): void {
+    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?: string): string {
+    const { user, password, host, port } = this.config;
+    const db = dbName ?? this.config.database;
+    return `postgres://${user}:${password}@${host}:${port}/${db}`;
+  }
+
+  createTemplateFromBase(base: string, template: string): void {
+    this.run(`createdb -T "${base}" "${template}"`);
+    this.run(`psql -c "UPDATE pg_database SET datistemplate = true WHERE datname = '${template}';"`);
+  }
+
+  cleanupTemplate(template: string): void {
+    try {
+      this.run(`psql -c "UPDATE pg_database SET datistemplate = false WHERE datname = '${template}'"`);
+    } catch { }
+    this.safeDropDb(template);
+  }
+
+  async createRole(role: string, password: string, dbName?: string): Promise<void> {
+    const db = dbName ?? this.config.database;
+    const sql = `CREATE ROLE ${role} WITH LOGIN PASSWORD '${password}';`;
+    await this.streamSql(sql, db);
+  }
+  
+  async grantRole(role: string, user: string, dbName?: string): Promise<void> {
+    const db = dbName ?? this.config.database;
+    const sql = `GRANT ${role} TO ${user};`;
+    await this.streamSql(sql, db);
+  }
+  
+  async grantConnect(role: string, dbName?: string): Promise<void> {
+    const db = dbName ?? this.config.database;
+    const sql = `GRANT CONNECT ON DATABASE "${db}" TO ${role};`;
+    await this.streamSql(sql, db);
+  }
+  
+  async createUserRole(user: string, password: string, dbName: string): Promise<void> {
+    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: string, dbName: string): void {
+    if (!existsSync(file)) {
+      throw new Error(`Missing SQL file: ${file}`);
+    }
+    this.run(`psql -f ${file} ${dbName}`);
+  }
+
+  async streamSql(sql: string, dbName: string): Promise<void> {
+    await stream({
+      ...this.config,
+      database: dbName
+    }, sql);
+  }
+
+}

package/src/connect.ts

@@ -0,0 +1,42 @@
+import { randomUUID } from 'crypto';
+import { getPgEnvOptions, PgConfig } from '@launchql/types';
+import { PgTestConnector } from './manager';
+import { DbAdmin } from './admin';
+
+let manager: PgTestConnector;
+export const getConnections = async () => {
+  const config: PgConfig = getPgEnvOptions({
+    database: `db-${randomUUID()}`
+  });
+
+  const app_user = 'app_user';
+  const app_password = 'app_password';
+
+  const admin = new DbAdmin(config);
+
+  // Create the test database
+  admin.create(config.database);
+
+  // Main admin client (optional unless needed elsewhere)
+  manager = PgTestConnector.getInstance();
+  const db = manager.getClient(config);
+
+  // Set up test role
+  admin.createUserRole(app_user, app_password, config.database);
+  admin.grantConnect(app_user, config.database);
+
+  // App user connection
+  const conn = manager.getClient({
+    ...config,
+    user: app_user,
+    password: app_password
+  })
+//   const conn = await getTestConnection(config.database, app_user, app_password);
+  conn.setContext({ role: 'anonymous' });
+
+  const teardown = async () => {
+    await manager.closeAll();
+  };
+
+  return { db, conn, teardown };
+};

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './legacy-connect';
+export * from './utils';

package/src/legacy-connect.ts

@@ -0,0 +1,34 @@
+import { PgTestClient } from './test-client';
+import { PgTestConnector } from './manager';
+import { randomUUID } from 'crypto';
+import { getPgEnvOptions, PgConfig } from '@launchql/types';
+
+export function connect(config: PgConfig): PgTestClient {
+  const manager = PgTestConnector.getInstance();
+  return manager.getClient(config);
+}
+
+export function close(client: PgTestClient): void {
+  client.close();
+}
+
+const manager = PgTestConnector.getInstance();
+
+export const Connection = {
+  connect(config: Partial<PgConfig>): PgTestClient {
+    const creds = getPgEnvOptions(config);
+    return manager.getClient(creds);
+  },
+
+  close(client: PgTestClient): void {
+    client.close();
+  },
+
+  closeAll(): Promise<void> {
+    return manager.closeAll();
+  },
+
+  getManager(): PgTestConnector {
+    return manager;
+  }
+};

package/src/manager.ts

@@ -0,0 +1,142 @@
+import { Pool } from 'pg';
+import chalk from 'chalk';
+import { DbAdmin } from './admin';
+import { PgConfig } from '@launchql/types';
+import { PgTestClient } from './test-client';
+
+const SYS_EVENTS = ['SIGTERM'];
+
+const end = (pool: Pool) => {
+  try {
+    if ((pool as any).ended || (pool as any).ending) {
+      console.warn(chalk.yellow('⚠️ pg pool already ended or ending'));
+      return;
+    }
+    pool.end();
+  } catch (err) {
+    console.error(chalk.red('❌ pg pool termination error:'), err);
+  }
+};
+
+export class PgTestConnector {
+  private static instance: PgTestConnector;
+
+  private readonly clients = new Set<PgTestClient>();
+  private readonly pgPools = new Map<string, Pool>();
+  private readonly seenDbConfigs = new Map<string, PgConfig>();
+
+  private verbose = false;
+
+  private constructor(verbose = false) {
+    this.verbose = verbose;
+
+    SYS_EVENTS.forEach((event) => {
+      process.on(event, () => {
+        this.log(chalk.magenta(`⏹ Received ${event}, closing all connections...`));
+        this.closeAll();
+      });
+    });
+  }
+
+  static getInstance(verbose = false): PgTestConnector {
+    if (!PgTestConnector.instance) {
+      PgTestConnector.instance = new PgTestConnector(verbose);
+    }
+    return PgTestConnector.instance;
+  }
+
+  private log(...args: any[]) {
+    if (this.verbose) console.log(...args);
+  }
+
+  private poolKey(config: PgConfig): string {
+    return `${config.user}@${config.host}:${config.port}/${config.database}`;
+  }
+
+  private dbKey(config: PgConfig): string {
+    return `${config.host}:${config.port}/${config.database}`;
+  }
+
+  getAdmin(config: PgConfig): DbAdmin {
+    return new DbAdmin(config, this.verbose);
+  }
+
+  getPool(config: PgConfig): Pool {
+    const key = this.poolKey(config);
+    if (!this.pgPools.has(key)) {
+      const pool = new Pool(config);
+      this.pgPools.set(key, pool);
+      this.log(chalk.blue(`📘 Created new pg pool: ${chalk.white(key)}`));
+    }
+    return this.pgPools.get(key)!;
+  }
+
+  getClient(config: PgConfig): PgTestClient {
+    const client = new PgTestClient(config);
+    this.clients.add(client);
+
+    const key = this.dbKey(config);
+    this.seenDbConfigs.set(key, config);
+
+    this.log(chalk.green(`🔌 New PgTestClient connected to ${config.database}`));
+    return client;
+  }
+
+  async closeAll(): Promise<void> {
+    this.log(chalk.cyan('\n🧹 Closing all PgTestClients...'));
+    await Promise.all(
+      Array.from(this.clients).map(async (client) => {
+        try {
+          await client.close();
+          this.log(chalk.green(`✅ Closed client for ${client.config.database}`));
+        } catch (err) {
+          console.warn(chalk.red(`❌ Error closing PgTestClient for ${client.config.database}:`), err);
+        }
+      })
+    );
+    this.clients.clear();
+
+    this.log(chalk.cyan('\n🧯 Disposing pg pools...'));
+    for (const [key, pool] of this.pgPools.entries()) {
+      this.log(chalk.gray(`🧯 Disposing pg pool [${key}]`));
+      end(pool);
+    }
+    this.pgPools.clear();
+
+    this.log(chalk.cyan('\n🗑️ Dropping seen databases...'));
+    await Promise.all(
+      Array.from(this.seenDbConfigs.values()).map(async (config) => {
+        try {
+          // somehow an "admin" db had app_user creds?
+          const admin = new DbAdmin({...config, user: 'postgres', password: 'password'}, this.verbose);
+          // console.log(config);
+          admin.drop();
+          this.log(chalk.yellow(`🧨 Dropped database: ${chalk.white(config.database)}`));
+        } catch (err) {
+          console.warn(chalk.red(`❌ Failed to drop database ${config.database}:`), err);
+        }
+      })
+    );
+    this.seenDbConfigs.clear();
+
+    this.log(chalk.green('\n✅ All PgTestClients closed, pools disposed, databases dropped.'));
+  }
+
+  close(): void {
+    this.closeAll();
+  }
+
+  drop(config: PgConfig): void {
+    const key = this.dbKey(config);
+    const admin = new DbAdmin(config, this.verbose);
+    admin.drop();
+    this.log(chalk.red(`🧨 Dropped database: ${chalk.white(config.database)}`));
+    this.seenDbConfigs.delete(key);
+  }
+  
+  kill(client: PgTestClient): void {
+    client.close();
+    this.drop(client.config);
+  }
+  
+}

package/src/stream.ts

@@ -0,0 +1,61 @@
+import { spawn } from 'child_process';
+import { Readable } from 'stream';
+import { env } from 'process';
+import { PgConfig } from '@launchql/types';
+
+function setArgs(config: PgConfig): string[] {
+  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: string): Readable {
+  const stream = new Readable({
+    read() {
+      this.push(text);
+      this.push(null);
+    }
+  });
+  return stream;
+}
+
+export async function streamSql(config: PgConfig, sql: string): Promise<void> {
+  const args = setArgs(config);
+
+  return new Promise<void>((resolve, reject) => {
+    const sqlStream = stringToStream(sql);
+
+    // TODO set env vars!
+    const proc = spawn('psql', args, {
+      env: {
+        ...env,
+        PGUSER: config.user,
+        PGHOST: config.host,
+        PGDATABASE: config.database,
+        PGPASSWORD: config.password,
+        // PGPORT: config.port
+      }
+    });
+
+    sqlStream.pipe(proc.stdin);
+
+    proc.on('close', (code) => {
+      resolve();
+    });
+
+    proc.on('error', (error) => {
+      reject(error);
+    });
+
+    proc.stderr.on('data', (data: Buffer) => {
+      reject(new Error(data.toString()));
+    });
+  });
+}

package/src/test-client.ts

@@ -0,0 +1,113 @@
+import { Client, QueryResult } from 'pg';
+import { PgConfig } from '@launchql/types';
+
+export class PgTestClient {
+  public config: PgConfig;
+  private client: Client;
+  private ctxStmts: string = '';
+  private _ended: boolean = false;
+
+  constructor(config: PgConfig) {
+    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
+    });
+    this.client.connect();
+  }
+
+  close(): void {
+    if (!this._ended) {
+      this._ended = true;
+      this.client.end();
+    }
+  }
+
+  async begin(): Promise<void> {
+    await this.client.query('BEGIN;');
+  }
+
+  async savepoint(name: string = 'lqlsavepoint'): Promise<void> {
+    await this.client.query(`SAVEPOINT "${name}";`);
+  }
+
+  async rollback(name: string = 'lqlsavepoint'): Promise<void> {
+    await this.client.query(`ROLLBACK TO SAVEPOINT "${name}";`);
+  }
+
+  async commit(): Promise<void> {
+    await this.client.query('COMMIT;');
+  }
+
+  async beforeEach(): Promise<void> {
+    await this.begin();
+    await this.savepoint();
+  }
+
+  async afterEach(): Promise<void> {
+    await this.rollback();
+    await this.commit();
+  }
+
+  setContext(ctx: Record<string, string | null>): void {
+    this.ctxStmts = Object.entries(ctx)
+      .map(([key, val]) =>
+        val === null
+          ? `SELECT set_config('${key}', NULL, true);`
+          : `SELECT set_config('${key}', '${val}', true);`
+      )
+      .join('\n');
+  }
+
+  private async runCtxQuery<T = any>(query: string, values?: any[]): Promise<QueryResult<T>> {
+    if (this.ctxStmts) {
+      await this.client.query(this.ctxStmts);
+    }
+    const result = await this.client.query<T>(query, values);
+    return result;
+  }
+
+  async any<T = any>(query: string, values?: any[]): Promise<T[]> {
+    const result = await this.runCtxQuery(query, values);
+    return result.rows;
+  }
+
+  async one<T = any>(query: string, values?: any[]): Promise<T> {
+    const rows = await this.any<T>(query, values);
+    if (rows.length !== 1) {
+      throw new Error('Expected exactly one result');
+    }
+    return rows[0];
+  }
+
+  async oneOrNone<T = any>(query: string, values?: any[]): Promise<T | null> {
+    const rows = await this.any<T>(query, values);
+    return rows[0] || null;
+  }
+
+  async many<T = any>(query: string, values?: any[]): Promise<T[]> {
+    const rows = await this.any<T>(query, values);
+    if (rows.length === 0) throw new Error('Expected many rows, got none');
+    return rows;
+  }
+
+  async manyOrNone<T = any>(query: string, values?: any[]): Promise<T[]> {
+    return this.any<T>(query, values);
+  }
+
+  async none(query: string, values?: any[]): Promise<void> {
+    await this.runCtxQuery(query, values);
+  }
+
+  async result(query: string, values?: any[]): Promise<import('pg').QueryResult> {
+    return this.runCtxQuery(query, values);
+  }
+
+  async query<T = any>(query: string, values?: any[]): Promise<QueryResult<T>> {
+    return this.client.query<T>(query, values);
+  }
+
+}

package/src/utils.ts

@@ -0,0 +1,48 @@
+import { Client, Pool } from 'pg';
+// import { createdb, dropdb, templatedb, installExt, grantConnect } from './db';
+import { connect, close } from './legacy-connect';
+import { getPgEnvOptions, PgConfig } from '@launchql/types';
+import { getEnvOptions } from '@launchql/types';
+import { randomUUID } from 'crypto';
+import { PgTestClient } from './test-client';
+import { DbAdmin } from './admin';
+
+export interface TestOptions {
+  hot?: boolean;
+  template?: string;
+  prefix?: string;
+  extensions?: string[];
+}
+
+export function getOpts(configOpts: TestOptions = {}): TestOptions {
+  return {
+    template: configOpts.template,
+    prefix: configOpts.prefix || 'testing-db',
+    extensions: configOpts.extensions || [],
+  };
+}
+
+export function getConnection(configOpts: TestOptions, database?: string): PgTestClient {
+  const opts = getOpts(configOpts);
+  const dbName = database || `${opts.prefix}-${Date.now()}`;
+
+  const config = getPgEnvOptions({
+    database: dbName
+  });
+
+  const admin = new DbAdmin(config);
+
+  if (process.env.TEST_DB) {
+    config.database = process.env.TEST_DB;
+  } else if (opts.hot) {
+    admin.create(config.database);
+    admin.installExtensions(opts.extensions);
+  } else if (opts.template) {
+    admin.createFromTemplate(opts.template, config.database);
+  } else {
+    admin.create(config.database);
+    admin.installExtensions(opts.extensions);
+  }
+
+  return connect(config);
+}

package/test-utils/index.ts

@@ -0,0 +1,2 @@
+import path from 'path';
+import fs from 'fs';

package/tsconfig.esm.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist/esm",
+    "module": "es2022",
+    "rootDir": "src/",
+    "declaration": false
+  }
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src/"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["dist", "node_modules", "**/*.spec.*", "**/*.test.*"]
+}