@schemavaults/dbh 0.7.5 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schemavaults/dbh",
-  "version": "0.7.5",
+  "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"
     }
   }
 }