@schemavaults/dbh 0.11.0 → 0.11.1

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.11.0 => ghcr.io/schemavaults/dbh/postgres-ws-proxy:0.11.0
+# NPM Package: @schemavaults/dbh@0.11.1 => ghcr.io/schemavaults/dbh/postgres-ws-proxy:0.11.1
 ```
 
 ### In your application server code

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schemavaults/dbh",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "Easily connect to PostgresDB from serverless environment",
   "license": "UNLICENSED",
   "private": false,

package/.claude/hooks/install-deps-in-fresh-environment.sh

@@ -1,5 +0,0 @@
-#!/bin/bash
-if [ ! -d "node_modules" ]; then
-  echo "No node_modules/ folder appears to exist so we're going to install dependencies..."
-  bun install
-fi

package/.claude/settings.json

@@ -1,15 +0,0 @@
-{
-  "hooks": {
-    "SessionStart": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": ".claude/hooks/install-deps-in-fresh-environment.sh"
-          }
-        ]
-      }
-    ]
-  }
-}

package/.claude/skills/database-migrations/SKILL.md

@@ -1,244 +0,0 @@
----
-name: database-migrations
-description: Authoring, building, validating, and running PostgreSQL database migrations with the @schemavaults/dbh package. Use when a project depends on @schemavaults/dbh and you are creating or editing Kysely migration files, setting up a migrations/ directory, or when the user mentions migrations, up()/down(), schema changes, or the dbh CLI's migrate / build-db-migrations / validate-migration-directory commands.
----
-
-# Database Migrations with @schemavaults/dbh
-
-`@schemavaults/dbh` provides [Kysely](https://kysely.dev/) migrations for
-PostgreSQL, applied through the `dbh` CLI. Migrations are opinionated: every file
-is a numbered module that exports an `up()` and a `down()` function. TypeScript
-source migrations are **built** to JavaScript first, then **applied** with the
-CLI.
-
-Invoke the CLI with your package runner. Use **`bunx @schemavaults/dbh`** for
-**validating and building** migrations — `build-db-migrations` uses Bun's
-bundler and requires Bun anyway. Use **`npx @schemavaults/dbh`** for **running /
-applying** migrations (`migrate` and `reverse`): most PostgreSQL drivers are
-built for Node.js rather than Bun, so apply migrations on the Node runtime.
-
-## One-time setup (for consumers)
-
-Migrations import the `sql` template tag from `@/sql` rather than directly from
-the package. This indirection is required by the build step (see the note under
-"Building migrations"), so configure it once:
-
-1. **Create a local `sql` module** somewhere in your source tree, e.g.
-   `./src/db/sql.ts`, that re-exports the tag from the package:
-
-   ```ts
-   // src/db/sql.ts
-   export { sql, sql as default } from "@schemavaults/dbh/sql";
-   export type * from "@schemavaults/dbh/sql";
-   ```
-
-2. **Configure the `@/sql` path alias** in your `tsconfig.json` so migration
-   sources typecheck and resolve:
-
-   ```jsonc
-   {
-     "compilerOptions": {
-       "baseUrl": ".",
-       "paths": {
-         "@/sql": ["./src/db/sql.ts"]
-       }
-     }
-   }
-   ```
-
-3. **Create a migrations directory**, e.g. `./src/db/migrations/`, and add your
-   numbered migration files there.
-
-## Migration file format
-
-Each migration is a single file in your migrations directory. The rules are:
-
-1. **The directory is non-empty.**
-2. **Each file name is prefixed with a 5-digit migration number**, followed by a
-   short kebab-case description, e.g. `00000-template-migration.ts`,
-   `00001-create-users-table.ts`. The number defines apply order.
-3. **Each module exports an `up(db)` and a `down(db)` function.** `up()` applies
-   the change; `down()` must reverse it exactly so migrations can be rolled back.
-4. **Migration numbers are unique** — never reuse a number. If two branches both
-   add `00040-*.ts`, that collision must be resolved by renumbering one of them
-   before merge.
-
-Both `up` and `down` receive a `Kysely<any>` instance and return a `Promise`.
-Import the `Kysely` type from the package: `import type { Kysely } from "@schemavaults/dbh"`.
-
-### Example: using the `Kysely<any>` query builder
-
-Prefer the typed query builder for schema operations:
-
-```ts
-// 00001-create-users-table.ts
-import type { Kysely } from "@schemavaults/dbh";
-
-export async function up(db: Kysely<any>): Promise<void> {
-  await db.schema
-    .createTable("users")
-    .addColumn("user_id", "uuid", (col) => col.primaryKey())
-    .addColumn("email", "text", (col) => col.notNull().unique())
-    .addColumn("created_at", "bigint", (col) => col.notNull())
-    .execute();
-}
-
-export async function down(db: Kysely<any>): Promise<void> {
-  await db.schema.dropTable("users").execute();
-}
-```
-
-### Example: using the `sql` template tag
-
-For statements the builder can't express (or raw DDL), import `sql` from
-`@/sql` (your local module from setup, which re-exports Kysely's `sql` tag) and
-call `.execute(db)`:
-
-```ts
-// 00002-create-squirrels-table.ts
-import type { Kysely } from "@schemavaults/dbh";
-import { sql } from "@/sql";
-
-export async function up(db: Kysely<any>): Promise<void> {
-  await sql`
-    CREATE TABLE IF NOT EXISTS EXAMPLE_SQUIRRELS (
-      squirrel_id UUID PRIMARY KEY,
-      squirrel_name TEXT NOT NULL,
-      created_at BIGINT NOT NULL
-    );
-  `.execute(db);
-
-  // Always interpolate values via ${...}; the sql tag parameterizes them.
-  await sql`CREATE INDEX squirrels_name_idx ON EXAMPLE_SQUIRRELS (squirrel_name);`.execute(
-    db,
-  );
-}
-
-export async function down(db: Kysely<any>): Promise<void> {
-  await sql`DROP TABLE IF EXISTS EXAMPLE_SQUIRRELS;`.execute(db);
-}
-```
-
-> Important: migration files must **always** import `sql` from `@/sql`, never
-> directly from `@schemavaults/dbh/sql`. The `build-db-migrations` step rewrites
-> the literal `@/sql` import specifier to a relative path pointing at the built,
-> standalone `sql.js`, so the import must be written exactly as `@/sql` for the
-> build to work. (This is why the one-time setup configures the `@/sql` alias.)
-
-### Empty template migration
-
-A no-op migration is valid (useful as a starting template):
-
-```ts
-// 00000-template-migration.ts
-import type { Kysely } from "@schemavaults/dbh";
-
-export async function up(
-  db: Kysely<any>, // eslint-disable-line @typescript-eslint/no-unused-vars
-): Promise<void> {}
-
-export async function down(
-  db: Kysely<any>, // eslint-disable-line @typescript-eslint/no-unused-vars
-): Promise<void> {}
-```
-
-## Validating migrations
-
-Before building or applying, assert your source migrations directory is
-well-formed. The `validate-migration-directory` command checks all four rules
-above and exits `0` when valid, non-zero otherwise (good for CI / pre-commit):
-
-```bash
-bunx @schemavaults/dbh validate-migration-directory ./src/db/migrations
-```
-
-It reports each problem with an `[ERROR]`/`[WARN]` prefix:
-- empty directory,
-- a file missing the 5-digit prefix,
-- a module missing `up()` or `down()`,
-- duplicate migration numbers (branch collisions).
-
-Treat duplicate numbers as warnings (non-fatal) with `--duplicates-as-warnings`.
-
-## Building migrations
-
-TypeScript migrations must be compiled to JavaScript before they're applied
-(the `migrate` step runs on Node and imports `.js`). The `build-db-migrations`
-command uses Bun's bundler and also builds the standalone `sql` module the
-migrations depend on. Point `--sql-module` at the local `sql.ts` you created
-during setup:
-
-```bash
-bunx @schemavaults/dbh build-db-migrations ./src/db/migrations \
-  --outdir ./dist/migrations \
-  --sql-module ./src/db/sql.ts \
-  --sql-outdir ./dist
-```
-
-Key options:
-- `<migrations-src>` — directory of `.ts` migration sources (positional).
-- `--outdir <dir>` — where compiled `.js` migrations are written (required).
-- `--sql-module <path>` — path to your local `sql.ts` module to build alongside (required).
-- `--sql-outdir <dir>` — where the built `sql.js` goes (defaults to the parent of `--outdir`).
-- `--external <pkg...>` — packages to keep external (default: `@schemavaults/dbh`, `kysely`).
-
-`build-db-migrations` requires `bun` to be installed and on the PATH.
-
-## Running migrations
-
-Apply built migrations with `migrate`, and roll back with `reverse`. Both take
-the **built** migration folder and require an `--environment`; credentials come
-from `process.env` (or an `--env-file`). Run these with **`npx`** (Node.js):
-most PostgreSQL drivers target Node rather than Bun.
-
-```bash
-# Apply all pending migrations (to latest):
-npx @schemavaults/dbh migrate ./dist/migrations --environment production --env-file ./.env.production
-
-# Apply up to a specific version (the migration name w/o extension):
-npx @schemavaults/dbh migrate ./dist/migrations 00001-create-users-table --environment staging
-
-# Roll back down to a target version:
-npx @schemavaults/dbh reverse ./dist/migrations 00000-template-migration --environment staging
-```
-
-Options for `migrate` / `reverse`:
-- `<folder>` — path to the built migration folder (positional).
-- `[version]` / `<version>` — target migration name; `migrate` defaults to latest, `reverse` requires it.
-- `-e, --environment <env>` — `development | test | staging | production` (required).
-- `--ws-proxy-url <url>` — custom Neon-compatible WebSocket proxy URL.
-- `--env-file <path>` — load DB credentials from a `.env` file first.
-
-Each result line prints as `[Up|Down] <migrationName>: <Success|Error|NotExecuted>`.
-
-### Programmatic API
-
-The same operations are available from `@schemavaults/dbh/migrate` for tests or
-custom scripts, using the adapter's Kysely instance:
-
-```ts
-import { migrate, reverse } from "@schemavaults/dbh/migrate";
-
-await migrate({ db: adapter.db, migrationFolder, version /* optional */ });
-await reverse({ db: adapter.db, migrationFolder, version });
-```
-
-## Typical end-to-end flow
-
-```bash
-# 1. Validate the source migrations directory.
-bunx @schemavaults/dbh validate-migration-directory ./src/db/migrations
-
-# 2. Build .ts migrations (+ sql module) to .js.
-bunx @schemavaults/dbh build-db-migrations ./src/db/migrations \
-  --outdir ./dist/migrations --sql-module ./src/db/sql.ts --sql-outdir ./dist
-
-# 3. Apply the built migrations (npx / Node.js — pg drivers target Node).
-npx @schemavaults/dbh migrate ./dist/migrations --environment production --env-file ./.env.production
-```
-
-## Required environment variables (for migrate/reverse)
-
-`POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_URL`, `POSTGRES_HOST`,
-`POSTGRES_PORT`, `POSTGRES_DATABASE` (and optional `POSTGRES_URL_NON_POOLING`).
-Set `SCHEMAVAULTS_DBH_DEBUG=true` for verbose debug logging.

package/CLAUDE.md

@@ -1,41 +0,0 @@
-# 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/eslint.config.cjs

@@ -1,56 +0,0 @@
-// @schemavaults/dbh - eslint.config.cjs
-
-const js = require("@eslint/js");
-const tsParser = require("@typescript-eslint/parser");
-const tsPlugin = require("@typescript-eslint/eslint-plugin");
-const globals = require("globals");
-
-module.exports = [
-  // Base recommended configs
-  js.configs.recommended,
-
-  // Main config
-  {
-    files: ["src/**/*.{ts,tsx,js,jsx}"],
-
-    languageOptions: {
-      parser: tsParser,
-      parserOptions: {
-        ecmaVersion: "latest",
-        sourceType: "module",
-        ecmaFeatures: {
-          jsx: false,
-        },
-        project: "./tsconfig.json",
-      },
-      globals: {
-        ...globals.browser,
-        ...globals.es2021,
-        ...globals.node,
-      },
-    },
-
-    plugins: {
-      "@typescript-eslint": tsPlugin,
-    },
-
-    rules: {
-      // TypeScript recommended rules
-      ...tsPlugin.configs.recommended.rules,
-
-      "@typescript-eslint/no-unused-vars": [
-        "warn",
-        { argsIgnorePattern: "^_" },
-      ],
-      "@typescript-eslint/no-explicit-any": "off",
-      "@typescript-eslint/no-namespace": "off",
-      "@typescript-eslint/no-empty-object-type": "off",
-      "no-redeclare": "off",
-    },
-  },
-
-  // Ignore patterns
-  {
-    ignores: ["dist/**", "node_modules/**", "*.config.js", "*.config.cjs"],
-  },
-];