typescript-test-infra-duckdb-file-lock

Answer

Root cause. DuckDB opens database files with an exclusive write lock (OS-level flock/LockFile, visible via lsof as 41uW). When a long-lived MCP server holds that lock on the real namespace DB, any second process (vitest, E2E daemon) that opens the same file in read-write mode immediately fails with DUCKDB_CONNECTION_LOST — DuckDB cannot acquire the conflicting lock. Tests must therefore never open the file the server is using.

Fix, in two parts:

1. Env-var override in getConfig()

The config layer now lets DUCKBRAIN_NAMESPACES_PATH redirect the namespace directory before any connection factory runs:

// src/config.ts
export interface Config {
  namespacesPath: string;
  // ... other options
}

export function getConfig(env: NodeJS.ProcessEnv = process.env): Config {
  return {
    // env override > explicit option > platform default
    namespacesPath: env.DUCKBRAIN_NAMESPACES_PATH
      ?? defaultNamespacesPath(),
  };
}

The critical detail is that the path must be resolved lazily inside the connection factory, not captured at module top-level — otherwise the module gets imported before the override is applied:

// src/db.ts
export function openNamespace(name: string): Database {
  // resolve at call time so vitest's setupFiles override is honored
  const { namespacesPath } = getConfig();
  const file = join(namespacesPath, `${name}.duckdb`);
  return new Database(file); // second process on the same file → DUCKDB_CONNECTION_LOST
}

2. Vitest setupFiles pointing at an isolated mkdtemp namespace

// vitest.setup.ts
import { mkdtempSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

const KEY = Symbol.for("duckbrain.test.namespace");
const g = globalThis as Record<symbol, string>;

// one throwaway dir per worker process, created before any test module loads
if (!g[KEY]) {
  g[KEY] = mkdtempSync(join(tmpdir(), "duckbrain-test-"));
}
process.env.DUCKBRAIN_NAMESPACES_PATH = g[KEY];

// vitest.config.ts
import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    setupFiles: ["./vitest.setup.ts"], // runs before test modules import getConfig()
    // ...
  },
});

Because setupFiles executes before the test file's imports, every module that later calls getConfig() — and hence every new Database(...) — resolves to <mkdtemp>/<namespace>.duckdb, a file the MCP server never touches. The singleton guard keeps it at one temp dir per worker; globalSetup is the alternative when a single suite-wide dir is preferred.