Add SCHEMAVAULTS_DBH_ADAPTER env var support for adapter selection

[jalexw]

Summary

This PR adds support for selecting the database adapter via the SCHEMAVAULTS_DBH_ADAPTER environment variable, enabling more flexible deployment configurations without requiring code changes. The CLI and createDbh() factory now support a consistent adapter resolution strategy with clear precedence rules.

Key Changes

• New adapter type system (src/types/SchemaVaultsDbhAdapterType.ts):

  • Introduced SchemaVaultsDbhAdapterType union type ("postgres" | "postgres-neon-proxy")
  • Added isValidDbhAdapterType() type guard and SCHEMAVAULTS_DBH_ADAPTER_TYPES constant
  • Declared SCHEMAVAULTS_DBH_ADAPTER in ProcessEnv for type-safe environment variable access

• Environment variable resolution (src/utils/getDbhAdapterTypeFromEnv.ts):

  • New utility function to read and validate the SCHEMAVAULTS_DBH_ADAPTER env var
  • Strips surrounding quotes (for shell compatibility)
  • Throws TypeError on invalid values to fail loudly instead of silently falling back

• Enhanced createDbh() factory (src/create-dbh.ts):

  • Now accepts undefined as adapter_type to defer to the environment variable
  • Added overload signatures for better type inference
  • Falls back to SCHEMAVAULTS_DBH_ADAPTER when no adapter type is explicitly passed
  • Throws if both the parameter and env var are unset/invalid

• CLI adapter selection (src/cli.ts):

  • Added -a, --adapter <adapter> flag to both migrate and reverse commands
  • Implemented resolveCliAdapterType() with three-tier precedence:
    1. Explicit --adapter flag
    2. SCHEMAVAULTS_DBH_ADAPTER environment variable
    3. "postgres-neon-proxy" (historical default)
  • Added warning when --ws-proxy-url is used with non-neon-proxy adapters
  • Replaced hardcoded adapter instantiation with createDbh() factory calls

• Documentation (README.md):

  • Added "Choosing a database adapter" section with examples
  • Documented adapter resolution precedence for both CLI and createDbh()
  • Added SCHEMAVAULTS_DBH_ADAPTER and SCHEMAVAULTS_DBH_DEBUG to optional environment variables

• Comprehensive test coverage (src/tests/DbhAdapterTypeFromEnv.test.ts):

  • Tests for getDbhAdapterTypeFromEnv() utility
  • Tests for createDbh() fallback behavior
  • Tests for CLI adapter resolution via environment variable
  • Tests for quote stripping and error handling

• Package exports (src/index.ts):

  • Exported new adapter type utilities and getDbhAdapterTypeFromEnv() for public use

Implementation Details

• The adapter type resolution is consistent across CLI and programmatic APIs
• Invalid adapter values throw immediately rather than silently defaulting, preventing configuration mistakes
• The CLI maintains backward compatibility by defaulting to "postgres-neon-proxy" when neither flag nor env var is set
• Type safety is preserved through overloaded function signatures and type guards

https://claude.ai/code/session_01LiV9mbTstiiKfPL1FuwrUr