@webpresso/db

Vendor-agnostic ephemeral database branch interface for the branch-per-test-run pattern.

Subpath exports

| Subpath | Exports | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | . (root) | Branch, BranchConfig, BranchProvider interfaces | | ./worktree | detectWorktreeSlug — parse worktree slug from git env | | ./e2e-policy | resolveE2EBranchPlan, E2EBranchPlan, shouldAttemptE2EWarmStackReuse | | ./tenancy | tenantBranchName, tenantPreviewBranchName, isTenantBranch, TenantBranchKind, TenantLifetime, lifetimeFromEnvironment, e2eBranchPrefix, TenantBranchInfo | | ./context | detectExecutionContext, ExecutionContext, detectDatabaseUrlMode, DatabaseUrlMode, getBranchName, WORKTREE_BRANCH_PREFIX |

Root export

| Symbol | Kind | Description | | ---------------- | --------- | -------------------------------------------------------------------------------- | | Branch | interface | Database branch with id and connectionUri (required), plus optional metadata | | BranchConfig | interface | Options for createBranch (name, parentBranchId, ttlMs) | | BranchProvider | interface | Implement this to integrate any database branching provider |

Usage

import type { Branch, BranchConfig, BranchProvider } from "@webpresso/db";
import { detectWorktreeSlug } from "@webpresso/db/worktree";
import { resolveE2EBranchPlan } from "@webpresso/db/e2e-policy";
import { tenantBranchName, TenantLifetime } from "@webpresso/db/tenancy";
import { detectExecutionContext } from "@webpresso/db/context";

// Implement BranchProvider for your provider
class MyBranchProvider implements BranchProvider {
  async createBranch(config?: BranchConfig): Promise<Branch> {
    /* ... */
  }
  async deleteBranch(branchId: string): Promise<void> {
    /* ... */
  }
  async resetBranch(branchId: string): Promise<void> {
    /* ... */
  }
  async getConnectionUri(branchId?: string): Promise<string> {
    /* ... */
  }
}

// Detect execution context (prod | e2e | preview | dev)
const ctx = detectExecutionContext();

// Resolve E2E branch plan from env vars
const plan = resolveE2EBranchPlan();

// Generate tenant branch names
const branchName = tenantBranchName("my-project", "production");

Migration from older Neon wrappers

Use @webpresso/db for vendor-agnostic primitives (Branch, BranchConfig, BranchProvider) and @webpresso/db/neon for the Neon adapter (NeonBranchProvider). Product-specific Neon wrappers stay private inside the Webpresso monorepo.