@schemavaults/dbh 0.7.4 → 0.8.1

package/CLAUDE.md

@@ -0,0 +1,41 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Is
+
+`@schemavaults/dbh` is an npm package that provides a Kysely-based adapter for connecting to Postgres databases through a Neon-compatible WebSocket proxy. It works with both Neon-hosted serverless Postgres and local Postgres instances (via a bundled WS proxy).
+
+## Commands
+
+Ensure dependencies are installed with `bun install` before attempting to run any other commands.
+
+- **Build:** `bun run build` (runs tsc + tsc-alias, then cleans test files from dist/)
+- **Lint:** `bun run lint` (eslint on src/)
+- **Unit tests:** `bun run test` or `bun run test:unit`
+- **Single test:** `bun test --test-name-pattern '<pattern>'`
+- **E2E tests:** `cd tests && /bin/bash ./run_e2e_tests.sh` (requires Docker Compose — spins up postgres, ws-proxy, and test-runner containers)
+- **CLI:** `bun run cli --help` locally or `bunx @schemavaults/dbh --help` remotely.
+
+## Architecture
+
+The core adapter is `SchemaVaultsPostgresNeonProxyAdapter<T>` (generic over Kysely table types). It wraps Kysely with a `NeonDialect` and handles credential parsing, WS proxy URL resolution, and debug logging. Consumers extend or instantiate it, passing an environment (`development|test|staging|production`), optional credentials (defaults to env vars), and an optional `wsProxyUrl` (string or generator function).
+
+Key modules:
+- `src/schemavaults-postgres-neon-proxy-adapter.ts` — the main adapter class
+- `src/migrate.ts` — Kysely migration helpers (`migrate`, `reverse`), exported as a separate entrypoint (`@schemavaults/dbh/migrate`)
+- `src/sql.ts` — re-exports Kysely's `sql` tag
+- `src/utils/parseDatabaseCredentials.ts` — parses/validates DB credentials from an object or `process.env`
+
+The package has two export entrypoints: `.` (adapter + sql + types), `./sql` (Kysely template tag re-export), `./migrate` (migration utilities), and `./cli` (@schemavaults/dbh command-line utility).
+
+## Local Dev Environment
+
+- Runtime/package manager: **Bun** (v1.3.6)
+- TypeScript with path alias `@/*` → `src/*` (resolved by tsc-alias at build time)
+- E2E tests run inside Docker containers (postgres:17.7 + a Go-based WS proxy on port 5433)
+
+## Environment Variables
+
+The adapter reads these from `process.env` when credentials aren't passed directly:
+`POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_URL`, `POSTGRES_URL_NON_POOLING` (optional), `POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_DATABASE`. Debug mode via `SCHEMAVAULTS_DBH_DEBUG=true`.

package/README.md

@@ -20,7 +20,7 @@ Ensure that you have both `postgres` and a `postgres-ws-proxy` containers runnin
 
 You'll likely want to replace the `build:` sections for the services in the e2e test example `.yml` file with `image:`. For example, use `image: postgres:17.7` for the `postgres` service. For the proxy, you can pull the docker image from `ghcr.io/schemavaults/dbh/postgres-ws-proxy`; use the version number equal to your `@schemavaults/dbh` npm package installation:
 ```md
-# NPM Package: @schemavaults/dbh@0.7.0 => ghcr.io/schemavaults/dbh/postgres-ws-proxy:0.7.0
+# NPM Package: @schemavaults/dbh@0.8.1 => ghcr.io/schemavaults/dbh/postgres-ws-proxy:0.8.1
 ```
 
 ### In your application server code
@@ -31,6 +31,28 @@ For an example, see the e2e test file: [./src/tests/e2e/ConnectToLocalDatabase.t
 
 You may need to define a custom `WsProxyUrlGenerator` function to determine how the `postgres-ws-proxy` can be reached.
 
+### From your command-line
+
+#### CLI Help Command
+```bash
+# run migrations (and more) from the cli
+bunx @schemavaults/dbh --help
+# or `bun run cli --help` if you have the dbh source repository as your working directory
+```
+
+#### Build example database migrations with the CLI
+```bash
+mkdir ./tests/tmp
+
+# compile TypeScript Kysely migrations to JavaScript
+bunx @schemavaults/dbh build-db-migrations ./src/tests/example-migrations \
+  --outdir ./tests/tmp/example-compiled-migrations \
+  --sql-module ./src/sql.ts \
+  --sql-outdir ./tests/tmp/
+  
+rm -rf ./tests/tmp
+```
+
 ## Required Environment Variables
 
 Ensure that the following environment variables are defined:

package/dist/build-db-migrations.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+declare const buildDbMigrations: Command;
+export default buildDbMigrations;

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+declare const dbhCli: Command;
+export default dbhCli;

package/dist/migrate.d.ts

@@ -1,4 +1,9 @@
-import { Kysely, MigrationResult } from "kysely";
+import { Kysely } from "kysely";
+export interface IMigrationResult {
+    migrationName: string;
+    status: "Success" | "Error" | "NotExecuted";
+    direction: "Up" | "Down";
+}
 export interface IMigrateOptions {
     db: Kysely<any>;
     migrationFolder: string;
@@ -9,6 +14,6 @@ export interface IReverseOptions {
     migrationFolder: string;
     version: string;
 }
-export declare function migrate({ db, migrationFolder, ...opts }: IMigrateOptions): Promise<MigrationResult[] | undefined>;
-export declare function reverse({ db, migrationFolder, version, }: IReverseOptions): Promise<MigrationResult[] | undefined>;
+export declare function migrate({ db, migrationFolder, ...opts }: IMigrateOptions): Promise<readonly IMigrationResult[]>;
+export declare function reverse({ db, migrationFolder, version, }: IReverseOptions): Promise<IMigrationResult[]>;
 export default migrate;

package/dist/migrate.js

@@ -13,6 +13,39 @@ function createMigrator({ db, migrationFolder }) {
         }),
     });
 }
+function validateMigrationResultFormat(migration_result) {
+    if (typeof migration_result !== "object" || !migration_result) {
+        throw new TypeError("Expected migration result to be an object!");
+    }
+    if (!("migrationName" in migration_result) ||
+        typeof migration_result.migrationName !== "string") {
+        throw new TypeError("Expected migration result's 'migrationName' to be a string!");
+    }
+    else if (!("direction" in migration_result) ||
+        typeof migration_result.direction !== "string") {
+        throw new TypeError("Expected migration result's 'direction' to be a string!");
+    }
+    else if (!("status" in migration_result) ||
+        typeof migration_result.status !== "string") {
+        throw new TypeError("Expected migration result's 'status' to be a string!");
+    }
+    else if (!["Up", "Down"].includes(migration_result.direction)) {
+        throw new TypeError("Expected migration result's 'direction' to be one of: 'Up' or 'Down'!");
+    }
+    else if (!["Success", "Error", "NotExecuted"].includes(migration_result.status)) {
+        throw new TypeError("Expected migration result's 'status' to be one of: 'Success', 'Error', or 'NotExecuted'!");
+    }
+    return true;
+}
+function validateMigrationResultFormats(results) {
+    if (!Array.isArray(results)) {
+        throw new TypeError("Expected 'results' to be an array!");
+    }
+    for (const migration_result of results) {
+        validateMigrationResultFormat(migration_result);
+    }
+    return true;
+}
 export async function migrate({ db, migrationFolder, ...opts }) {
     if (typeof migrationFolder !== "string") {
         throw new Error("migrationFolder must be a string");
@@ -33,6 +66,12 @@ export async function migrate({ db, migrationFolder, ...opts }) {
         console.error(error);
         throw error;
     }
+    if (!results) {
+        return [];
+    }
+    if (!validateMigrationResultFormats(results)) {
+        throw new TypeError("Migration appears to have succeeded but failed to parse received results!");
+    }
     return results;
 }
 export async function reverse({ db, migrationFolder, version, }) {
@@ -48,6 +87,12 @@ export async function reverse({ db, migrationFolder, version, }) {
         console.error(error);
         throw error;
     }
+    if (!results) {
+        return [];
+    }
+    if (!validateMigrationResultFormats(results)) {
+        throw new TypeError("Reverse migration appears to have succeeded but failed to parse received results!");
+    }
     return results;
 }
 export default migrate;

package/dist/migrate.js.map

@@ -1 +1 @@
-{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"AAAA,aAAa;AAEb,OAAO,EAEL,QAAQ,EACR,qBAAqB,GAGtB,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,MAAM,aAAa,CAAC;AAC7B,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAchC,SAAS,cAAc,CAAC,EAAE,EAAE,EAAE,eAAe,EAAmB;IAC9D,OAAO,IAAI,QAAQ,CAAC;QAClB,EAAE,EAAE,EAAE;QACN,QAAQ,EAAE,IAAI,qBAAqB,CAAC;YAClC,EAAE;YACF,IAAI;YACJ,eAAe;SAChB,CAAC;KACH,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,EAC5B,EAAE,EACF,eAAe,EACf,GAAG,IAAI,EACS;IAChB,IAAI,OAAO,eAAe,KAAK,QAAQ,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IACtD,CAAC;IAED,IAAI,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,oBAAoB,eAAe,kBAAkB,CAAC,CAAC;IACzE,CAAC;IAED,MAAM,QAAQ,GAAG,cAAc,CAAC,EAAE,EAAE,EAAE,eAAe,EAAE,CAAC,CAAC;IAEzD,IAAI,MAA0B,CAAC;IAC/B,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QACrC,MAAM,GAAG,MAAM,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAClD,CAAC;SAAM,CAAC;QACN,MAAM,GAAG,MAAM,QAAQ,CAAC,eAAe,EAAE,CAAC;IAC5C,CAAC;IACD,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;IAClC,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACrB,MAAM,KAAK,CAAC;IACd,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,EAC5B,EAAE,EACF,eAAe,EACf,OAAO,GACS;IAChB,IAAI,OAAO,eAAe,KAAK,QAAQ,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IACtD,CAAC;IAED,IAAI,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,oBAAoB,eAAe,kBAAkB,CAAC,CAAC;IACzE,CAAC;IAED,MAAM,QAAQ,GAAG,cAAc,CAAC,EAAE,EAAE,EAAE,eAAe,EAAE,CAAC,CAAC;IAEzD,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,MAAM,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAC7D,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACrB,MAAM,KAAK,CAAC;IACd,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,eAAe,OAAO,CAAC"}
+{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schemavaults/dbh",
-  "version": "0.7.4",
+  "version": "0.8.1",
   "description": "Easily connect to PostgresDB from serverless environment",
   "license": "UNLICENSED",
   "private": false,
@@ -8,6 +8,9 @@
     "type": "git",
     "url": "https://github.com/schemavaults/dbh.git"
   },
+  "bin": {
+    "dbh": "dist-cli/cli.js"
+  },
   "dependencies": {
     "kysely": "0.28.10",
     "kysely-neon": "1.3.0",
@@ -21,19 +24,25 @@
     "@eslint/js": "9.39.1",
     "globals": "16.5.0",
     "@typescript-eslint/eslint-plugin": "8.48.1",
-    "@typescript-eslint/parser": "8.48.1"
+    "@typescript-eslint/parser": "8.48.1",
+    "commander": "14.0.3"
   },
   "scripts": {
     "build": "tsc --project tsconfig.json && tsc-alias --project tsconfig.json",
+    "postbuild": "bun run cleanup",
+    "build:cli": "bun build ./src/cli.ts --outdir dist-cli --format esm --target node --minify",
+    "build:build-db-migrations": "bun build ./src/build-db-migrations.ts --outdir dist-cli --format esm --target bun --minify",
     "test:unit": "bun test --test-name-pattern 'DBH Init'",
     "test": "bun run test:unit",
-    "test:e2e": "bun test ./src/tests/e2e/ConnectToLocalDatabase.test.ts",
+    "test:e2e": "bun test ./src/tests/e2e/",
+    "test:build-db-migrations": "/bin/bash ./tests/run_build_example_migrations_test.sh",
     "cleanup:compiled_tests_in_dist_directory": "find ./dist -type f \\( -name \"*.test.js\" -o -name \"*.test.js.map\" -o -name \"*.test.d.ts\" \\) -delete",
     "cleanup:rm_tests_dir": "rm -rf ./dist/tests",
-    "cleanup": "bun run cleanup:compiled_tests_in_dist_directory",
-    "postbuild": "bun run cleanup",
+    "cleanup:rm_cli_js_artifacts": "rm -rf ./dist/cli.js && rm -rf ./dist/cli.js.map",
+    "cleanup": "bun run cleanup:compiled_tests_in_dist_directory && bun run cleanup:rm_tests_dir && bun run cleanup:rm_cli_js_artifacts",
     "version": "bun run ./scripts/package_version.ts",
-    "lint": "eslint src"
+    "lint": "eslint src",
+    "cli": "bun run ./src/cli.ts"
   },
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -63,6 +72,20 @@
       "types": "./dist/migrate.d.ts",
       "import": "./dist/migrate.js",
       "require": "./dist/migrate.js"
+    },
+    "./sql": {
+      "types": "./dist/sql.d.ts",
+      "import": "./dist/sql.js",
+      "require": "./dist/sql.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "import": "./dist-cli/cli.js",
+      "require": "./dist-cli/cli.js"
+    },
+    "./build-db-migrations": {
+      "import": "./dist-cli/build-db-migrations.js",
+      "require": "./dist-cli/build-db-migrations.js"
     }
   }
 }