@elench/testkit 0.1.14 → 0.1.15

package/README.md

@@ -1,6 +1,6 @@
 # @elench/testkit
 
-CLI that reads `runner.manifest.json` plus `testkit.config.json` from a product repo, starts the required local services, provisions Neon branches when configured, and runs manifest-defined suites across `k6` and Playwright.
+CLI that reads `runner.manifest.json` plus `testkit.config.json` from a product repo, starts the required local services, provisions the selected database backend, and runs manifest-defined suites across `k6` and Playwright.
 
 ## Prerequisites
 
@@ -11,6 +11,8 @@ sudo apt-get install -y jq
 
 For DAL suites, `@elench/testkit` ships its own `k6` SQL binary. For suites using a Neon branch, set `NEON_API_KEY` in the product `.env`, shell, or `.envrc`.
 
+Local database mode uses Docker-managed `postgres:16` containers. `testkit` creates and reuses template databases automatically, then clones per-worker databases from those templates for fast reruns.
+
 ## Usage
 
 ```bash
@@ -24,6 +26,10 @@ npx @elench/testkit int
 npx @elench/testkit dal
 npx @elench/testkit e2e
 
+# Force a database backend
+npx @elench/testkit --db-backend local
+npx @elench/testkit --db-backend neon
+
 # Filter by framework
 npx @elench/testkit --framework playwright
 npx @elench/testkit --framework k6
@@ -49,7 +55,7 @@ npx @elench/testkit destroy
 1. **Discovery** — reads `runner.manifest.json` for services, suites, files, and frameworks
 2. **Config** — reads `testkit.config.json` for local runtime, migration, dependency, and database settings
    Per-service `.env` files declared in config are loaded when present.
-3. **Database** — provisions a Neon branch when a service declares one
+3. **Database** — provisions the selected backend (`neon` or Docker-managed `local`) when a service declares one
 4. **Seed** — runs optional product seed commands against the provisioned database
 5. **Runtime** — starts required local services, waits for readiness, and injects test env
 6. **Execution** — distributes suites across isolated worker stacks, runs `k6` suites file-by-file, and runs Playwright suites suite-by-suite
@@ -66,6 +72,9 @@ Each run ends with a compact summary that shows per-service pass/fail status, su
 
 - `envFile` / `envFiles` for service-specific environment loading
 - `databaseFrom` for dependency services that must share another service's `DATABASE_URL`
+- `database.defaultBackend` / `database.backends` to switch between Neon and local Postgres
+- `database.template.inputs` to define the local template cache invalidation inputs
+- `migrate.backends` / `seed.backends` for backend-specific command overrides
 
 ## Parallel execution
 
@@ -73,6 +82,7 @@ Each run ends with a compact summary that shows per-service pass/fail status, su
 
 Each worker gets its own:
 - Neon branch
+- or cloned local Postgres database
 - `.testkit` state subtree
 - local service ports
 

package/lib/cli.mjs

@@ -16,6 +16,7 @@ export function run() {
     .option("--jobs <n>", "Number of isolated worker stacks per service", {
       default: "1",
     })
+    .option("--db-backend <name>", "Database backend override (neon, local)")
     .option("--shard <i/n>", "Run only shard i of n at suite granularity")
     .option("--framework <name>", "Filter by framework (k6, playwright, all)", {
       default: "all",
@@ -63,7 +64,7 @@ export function run() {
         );
       }
 
-      const allConfigs = loadConfigs({ dir: options.dir });
+      const allConfigs = loadConfigs({ dir: options.dir, dbBackend: options.dbBackend });
       const configs = service
         ? allConfigs.filter((config) => config.name === service)
         : allConfigs;

package/lib/config.mjs

@@ -5,6 +5,7 @@ import { fileURLToPath } from "url";
 const RUNNER_MANIFEST = "runner.manifest.json";
 const TESTKIT_CONFIG = "testkit.config.json";
 const VALID_FRAMEWORKS = new Set(["k6", "playwright"]);
+const VALID_DB_PROVIDERS = new Set(["neon", "local"]);
 
 /**
  * Parse a .env file into an object. Supports KEY=VALUE, KEY='VALUE', KEY="VALUE".
@@ -67,8 +68,20 @@ export function loadConfigs(opts = {}) {
       );
     }
 
-    validateMergedService(name, runnerService, serviceConfig, productDir);
+    const resolvedDatabase = resolveSelectedDatabase(name, serviceConfig, opts.dbBackend);
     const serviceEnv = loadServiceEnv(productDir, serviceConfig);
+    const selectedBackend = resolvedDatabase?.selectedBackend;
+    const resolvedMigrate = resolveLifecycleConfig(serviceConfig.migrate, selectedBackend);
+    const resolvedSeed = resolveLifecycleConfig(serviceConfig.seed, selectedBackend);
+    validateMergedService(
+      name,
+      runnerService,
+      serviceConfig,
+      resolvedDatabase,
+      resolvedMigrate,
+      resolvedSeed,
+      productDir
+    );
 
     return {
       name,
@@ -77,6 +90,10 @@ export function loadConfigs(opts = {}) {
       suites: runnerService.suites,
       testkit: {
         ...serviceConfig,
+        database: resolvedDatabase,
+        migrate: resolvedMigrate,
+        seed: resolvedSeed,
+        envFiles: getServiceEnvFiles(serviceConfig),
         serviceEnv,
       },
     };
@@ -279,7 +296,15 @@ export function isSiblingProduct(name) {
   );
 }
 
-function validateMergedService(name, runnerService, serviceConfig, productDir) {
+function validateMergedService(
+  name,
+  runnerService,
+  serviceConfig,
+  resolvedDatabase,
+  resolvedMigrate,
+  resolvedSeed,
+  productDir
+) {
   const usesLocalExecution = Object.values(runnerService.suites).some((suites) =>
     suites.some(
       (suite) =>
@@ -302,6 +327,16 @@ function validateMergedService(name, runnerService, serviceConfig, productDir) {
     }
   }
 
+  if (
+    resolvedDatabase?.provider === "local" &&
+    (serviceConfig.migrate || serviceConfig.seed) &&
+    resolvedDatabase.template.inputs.length === 0
+  ) {
+    throw new Error(
+      `Service "${name}" uses local database provisioning with migrations or seeds, so database.template.inputs must list the files/directories that define the template cache`
+    );
+  }
+
   if (serviceConfig.local?.cwd) {
     const cwdPath = resolveServiceCwd(productDir, serviceConfig.local.cwd);
     if (!fs.existsSync(cwdPath)) {
@@ -311,20 +346,20 @@ function validateMergedService(name, runnerService, serviceConfig, productDir) {
     }
   }
 
-  if (serviceConfig.migrate?.cwd) {
-    const cwdPath = resolveServiceCwd(productDir, serviceConfig.migrate.cwd);
+  if (resolvedMigrate?.cwd) {
+    const cwdPath = resolveServiceCwd(productDir, resolvedMigrate.cwd);
     if (!fs.existsSync(cwdPath)) {
       throw new Error(
-        `Service "${name}" migrate.cwd does not exist: ${serviceConfig.migrate.cwd}`
+        `Service "${name}" migrate.cwd does not exist: ${resolvedMigrate.cwd}`
       );
     }
   }
 
-  if (serviceConfig.seed?.cwd) {
-    const cwdPath = resolveServiceCwd(productDir, serviceConfig.seed.cwd);
+  if (resolvedSeed?.cwd) {
+    const cwdPath = resolveServiceCwd(productDir, resolvedSeed.cwd);
     if (!fs.existsSync(cwdPath)) {
       throw new Error(
-        `Service "${name}" seed.cwd does not exist: ${serviceConfig.seed.cwd}`
+        `Service "${name}" seed.cwd does not exist: ${resolvedSeed.cwd}`
       );
     }
   }
@@ -367,38 +402,24 @@ function validateServiceConfig(name, service, configPath) {
     if (!isObject(service.database)) {
       throw new Error(`Service "${name}" database must be an object`);
     }
-    const db = service.database;
-    if (db.provider !== "neon") {
-      throw new Error(`Service "${name}" database.provider must be "neon"`);
-    }
-    requireString(db, "projectId", `Service "${name}" database.projectId`);
-    requireString(db, "dbName", `Service "${name}" database.dbName`);
-    if (db.branchName !== undefined && typeof db.branchName !== "string") {
-      throw new Error(`Service "${name}" database.branchName must be a string`);
-    }
-    if (db.reset !== undefined && typeof db.reset !== "boolean") {
-      throw new Error(`Service "${name}" database.reset must be a boolean`);
+
+    if (service.database.provider !== undefined) {
+      validateDatabaseProviderConfig(name, service.database, `Service "${name}" database`);
+    } else if (service.database.backends !== undefined) {
+      validateMultiBackendDatabaseConfig(name, service.database);
+    } else {
+      throw new Error(
+        `Service "${name}" database must define either provider or backends`
+      );
     }
   }
 
   if (service.migrate !== undefined) {
-    if (!isObject(service.migrate)) {
-      throw new Error(`Service "${name}" migrate must be an object`);
-    }
-    requireString(service.migrate, "cmd", `Service "${name}" migrate.cmd`);
-    if (service.migrate.cwd !== undefined && typeof service.migrate.cwd !== "string") {
-      throw new Error(`Service "${name}" migrate.cwd must be a string`);
-    }
+    validateLifecycleConfig(name, service.migrate, "migrate");
   }
 
   if (service.seed !== undefined) {
-    if (!isObject(service.seed)) {
-      throw new Error(`Service "${name}" seed must be an object`);
-    }
-    requireString(service.seed, "cmd", `Service "${name}" seed.cmd`);
-    if (service.seed.cwd !== undefined && typeof service.seed.cwd !== "string") {
-      throw new Error(`Service "${name}" seed.cwd must be a string`);
-    }
+    validateLifecycleConfig(name, service.seed, "seed");
   }
 
   if (service.local !== undefined) {
@@ -446,6 +467,189 @@ function getServiceEnvFiles(serviceConfig) {
   return files;
 }
 
+function resolveSelectedDatabase(name, serviceConfig, requestedBackend) {
+  if (!serviceConfig.database) return undefined;
+
+  const database = serviceConfig.database;
+  if (database.provider !== undefined) {
+    if (requestedBackend && requestedBackend !== database.provider) {
+      throw new Error(
+        `Service "${name}" does not define database backend "${requestedBackend}". Available: ${database.provider}`
+      );
+    }
+
+    return {
+      ...database,
+      provider: database.provider,
+      selectedBackend: database.provider,
+      reset: database.reset !== false,
+      template: normalizeTemplateConfig(database.template),
+    };
+  }
+
+  const backends = database.backends || {};
+  const selectedBackend =
+    requestedBackend ||
+    process.env.TESTKIT_DB_BACKEND ||
+    database.defaultBackend ||
+    Object.keys(backends)[0];
+
+  if (!selectedBackend || !backends[selectedBackend]) {
+    throw new Error(
+      `Service "${name}" does not define database backend "${selectedBackend || "undefined"}"`
+    );
+  }
+
+  const backend = backends[selectedBackend];
+  return {
+    ...backend,
+    provider: backend.provider,
+    selectedBackend,
+    reset: database.reset !== false,
+    template: normalizeTemplateConfig(database.template),
+  };
+}
+
+function validateMultiBackendDatabaseConfig(name, database) {
+  if (
+    database.defaultBackend !== undefined &&
+    (typeof database.defaultBackend !== "string" || !database.defaultBackend.length)
+  ) {
+    throw new Error(`Service "${name}" database.defaultBackend must be a non-empty string`);
+  }
+  if (database.reset !== undefined && typeof database.reset !== "boolean") {
+    throw new Error(`Service "${name}" database.reset must be a boolean`);
+  }
+  if (database.template !== undefined) {
+    validateTemplateConfig(name, database.template, `Service "${name}" database.template`);
+  }
+  if (!isObject(database.backends) || Object.keys(database.backends).length === 0) {
+    throw new Error(`Service "${name}" database.backends must be a non-empty object`);
+  }
+
+  for (const [backendName, backendConfig] of Object.entries(database.backends)) {
+    if (!isObject(backendConfig)) {
+      throw new Error(
+        `Service "${name}" database.backends.${backendName} must be an object`
+      );
+    }
+    validateDatabaseProviderConfig(
+      name,
+      backendConfig,
+      `Service "${name}" database.backends.${backendName}`
+    );
+  }
+
+  if (database.defaultBackend && !database.backends[database.defaultBackend]) {
+    throw new Error(
+      `Service "${name}" database.defaultBackend "${database.defaultBackend}" is missing from database.backends`
+    );
+  }
+}
+
+function validateDatabaseProviderConfig(name, db, label) {
+  if (!VALID_DB_PROVIDERS.has(db.provider)) {
+    throw new Error(
+      `${label}.provider must be one of: ${[...VALID_DB_PROVIDERS].join(", ")}`
+    );
+  }
+
+  if (db.reset !== undefined && typeof db.reset !== "boolean") {
+    throw new Error(`${label}.reset must be a boolean`);
+  }
+  if (db.template !== undefined) {
+    validateTemplateConfig(name, db.template, `${label}.template`);
+  }
+
+  if (db.provider === "neon") {
+    requireString(db, "projectId", `${label}.projectId`);
+    requireString(db, "dbName", `${label}.dbName`);
+    if (db.branchName !== undefined && typeof db.branchName !== "string") {
+      throw new Error(`${label}.branchName must be a string`);
+    }
+    return;
+  }
+
+  if (db.image !== undefined && typeof db.image !== "string") {
+    throw new Error(`${label}.image must be a string`);
+  }
+  if (db.user !== undefined && typeof db.user !== "string") {
+    throw new Error(`${label}.user must be a string`);
+  }
+  if (db.password !== undefined && typeof db.password !== "string") {
+    throw new Error(`${label}.password must be a string`);
+  }
+}
+
+function validateTemplateConfig(name, template, label) {
+  if (!isObject(template)) {
+    throw new Error(`${label} must be an object`);
+  }
+  if (
+    template.inputs !== undefined &&
+    (!Array.isArray(template.inputs) || template.inputs.some((value) => typeof value !== "string"))
+  ) {
+    throw new Error(`${label}.inputs must be an array of strings`);
+  }
+}
+
+function normalizeTemplateConfig(template) {
+  return {
+    inputs: Array.isArray(template?.inputs) ? [...template.inputs] : [],
+  };
+}
+
+function validateLifecycleConfig(name, value, label) {
+  if (!isObject(value)) {
+    throw new Error(`Service "${name}" ${label} must be an object`);
+  }
+
+  if (value.cmd !== undefined) {
+    requireString(value, "cmd", `Service "${name}" ${label}.cmd`);
+  }
+  if (value.cwd !== undefined && typeof value.cwd !== "string") {
+    throw new Error(`Service "${name}" ${label}.cwd must be a string`);
+  }
+
+  if (value.backends !== undefined) {
+    if (!isObject(value.backends)) {
+      throw new Error(`Service "${name}" ${label}.backends must be an object`);
+    }
+    for (const [backendName, override] of Object.entries(value.backends)) {
+      if (!isObject(override)) {
+        throw new Error(
+          `Service "${name}" ${label}.backends.${backendName} must be an object`
+        );
+      }
+      if (override.cmd !== undefined) {
+        requireString(override, "cmd", `Service "${name}" ${label}.backends.${backendName}.cmd`);
+      }
+      if (override.cwd !== undefined && typeof override.cwd !== "string") {
+        throw new Error(
+          `Service "${name}" ${label}.backends.${backendName}.cwd must be a string`
+        );
+      }
+    }
+  }
+
+  if (value.cmd === undefined && value.backends === undefined) {
+    throw new Error(`Service "${name}" ${label} must define cmd or backends`);
+  }
+}
+
+function resolveLifecycleConfig(value, selectedBackend) {
+  if (!value) return value;
+
+  const override =
+    selectedBackend && isObject(value.backends) ? value.backends[selectedBackend] || {} : {};
+  const resolved = {
+    ...value,
+    ...override,
+  };
+  delete resolved.backends;
+  return resolved;
+}
+
 function requireString(obj, key, label) {
   if (typeof obj[key] !== "string" || obj[key].length === 0) {
     throw new Error(`${label} must be a non-empty string`);

package/lib/database.mjs

@@ -0,0 +1,656 @@
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+import { execa } from "execa";
+import { requireNeonApiKey, resolveServiceCwd } from "./config.mjs";
+import { runScript } from "./exec.mjs";
+
+const LOCAL_IMAGE = "postgres:16";
+const LOCAL_USER = "testkit";
+const LOCAL_PASSWORD = "testkit";
+const LOCAL_ADMIN_DB = "postgres";
+const LOCAL_READY_TIMEOUT_MS = 60_000;
+const LOCAL_POLL_INTERVAL_MS = 1_000;
+
+export async function prepareDatabaseRuntime(config, hooks = {}) {
+  const db = config.testkit.database;
+  if (!db) return;
+
+  fs.mkdirSync(config.stateDir, { recursive: true });
+  if (db.provider === "neon") {
+    await prepareNeonDatabase(config, hooks);
+    return;
+  }
+  if (db.provider === "local") {
+    await prepareLocalDatabase(config, hooks);
+    return;
+  }
+
+  throw new Error(`Unsupported database provider "${db.provider}"`);
+}
+
+export async function destroyRuntimeDatabase({ productDir, stateDir }) {
+  const backend = readStateValue(path.join(stateDir, "database_backend"));
+  if (!backend || backend === "neon") {
+    await destroyNeonDatabase(stateDir);
+    return;
+  }
+
+  if (backend === "local") {
+    await destroyLocalRuntimeDatabase(productDir, stateDir);
+    return;
+  }
+}
+
+export async function destroyServiceDatabaseCache(productDir, serviceName) {
+  const cacheDir = getLocalServiceCacheDir(productDir, serviceName);
+  if (!fs.existsSync(cacheDir)) return;
+
+  const backend = readStateValue(path.join(cacheDir, "database_backend"));
+  if (backend !== "local") {
+    fs.rmSync(cacheDir, { recursive: true, force: true });
+    return;
+  }
+
+  const lockDir = getLocalLocksDir(productDir);
+  fs.mkdirSync(lockDir, { recursive: true });
+  await withLock(path.join(lockDir, `template-${serviceName}.lock`), async () => {
+    const infra = await loadExistingLocalContainer(productDir);
+    if (!infra) {
+      fs.rmSync(cacheDir, { recursive: true, force: true });
+      return;
+    }
+    const templateDbName = readStateValue(path.join(cacheDir, "template_database_name"));
+    if (templateDbName) {
+      await dropDatabaseIfExists(infra, templateDbName);
+    }
+    fs.rmSync(cacheDir, { recursive: true, force: true });
+  });
+}
+
+export async function cleanupOrphanedLocalInfrastructure(productDir) {
+  const infraDir = getLocalInfraDir(productDir);
+  if (!fs.existsSync(infraDir)) return;
+
+  if (hasRemainingLocalArtifacts(productDir)) return;
+
+  const containerName = readStateValue(path.join(infraDir, "container_name"));
+  if (containerName) {
+    await stopAndRemoveContainer(containerName);
+  }
+  fs.rmSync(infraDir, { recursive: true, force: true });
+}
+
+export function isDatabaseStateDir(dir) {
+  if (!fs.existsSync(dir)) return false;
+  return (
+    fs.existsSync(path.join(dir, "database_backend")) ||
+    fs.existsSync(path.join(dir, "neon_branch_id")) ||
+    fs.existsSync(path.join(dir, "neon_project_id"))
+  );
+}
+
+export function showServiceDatabaseStatus(productDir, serviceName) {
+  const cacheDir = getLocalServiceCacheDir(productDir, serviceName);
+  const infraDir = getLocalInfraDir(productDir);
+  if (!fs.existsSync(cacheDir) && !fs.existsSync(infraDir)) return false;
+
+  if (fs.existsSync(cacheDir)) {
+    console.log("  database-cache/");
+    printStateDir(cacheDir, "    ");
+  }
+
+  if (fs.existsSync(infraDir)) {
+    console.log("  database-infra/");
+    printStateDir(infraDir, "    ");
+  }
+
+  return true;
+}
+
+async function prepareNeonDatabase(config, hooks) {
+  const db = config.testkit.database;
+  requireNeonApiKey();
+
+  removeLocalRuntimeState(config.stateDir);
+
+  await runScript("neon-up.sh", {
+    NEON_PROJECT_ID: db.projectId,
+    NEON_DB_NAME: db.dbName,
+    NEON_BRANCH_NAME: db.branchName,
+    NEON_RESET: db.reset === false ? "false" : "true",
+    STATE_DIR: config.stateDir,
+  });
+
+  fs.writeFileSync(path.join(config.stateDir, "database_backend"), "neon");
+  fs.writeFileSync(path.join(config.stateDir, "neon_project_id"), db.projectId);
+
+  const databaseUrl = readStateValue(path.join(config.stateDir, "database_url"));
+  if (hooks.runMigrate) {
+    await hooks.runMigrate(databaseUrl);
+  }
+  if (hooks.runSeed) {
+    await hooks.runSeed(databaseUrl);
+  }
+}
+
+async function destroyNeonDatabase(stateDir) {
+  const projectId = readStateValue(path.join(stateDir, "neon_project_id"));
+  if (!projectId) return;
+
+  await runScript("neon-down.sh", {
+    NEON_PROJECT_ID: projectId,
+    STATE_DIR: stateDir,
+  });
+}
+
+async function prepareLocalDatabase(config, hooks) {
+  const db = config.testkit.database;
+  const productDir = config.productDir;
+  const serviceName = config.name;
+  const lockDir = getLocalLocksDir(productDir);
+  const cacheDir = getLocalServiceCacheDir(productDir, serviceName);
+  fs.mkdirSync(lockDir, { recursive: true });
+  fs.mkdirSync(cacheDir, { recursive: true });
+
+  const templateFingerprint = await computeTemplateFingerprint(config);
+  const infra = await withLock(path.join(lockDir, "container.lock"), () =>
+    ensureLocalContainer(productDir, db)
+  );
+
+  await withLock(path.join(lockDir, `template-${serviceName}.lock`), async () => {
+    await ensureTemplateDatabase(config, infra, cacheDir, templateFingerprint, hooks);
+  });
+
+  await withLock(path.join(lockDir, `runtime-${serviceName}-${hashString(config.stateDir, 10)}.lock`), async () => {
+    await ensureWorkerClone(config, infra, cacheDir, templateFingerprint);
+  });
+}
+
+async function ensureTemplateDatabase(config, infra, cacheDir, templateFingerprint, hooks) {
+  const serviceName = config.name;
+  const existingFingerprint = readStateValue(path.join(cacheDir, "template_fingerprint"));
+  const existingDbName = readStateValue(path.join(cacheDir, "template_database_name"));
+  const desiredDbName = buildTemplateDatabaseName(serviceName, templateFingerprint);
+
+  if (
+    existingFingerprint === templateFingerprint &&
+    existingDbName &&
+    (await databaseExists(infra, existingDbName))
+  ) {
+    writeLocalCacheState(cacheDir, infra, existingDbName, templateFingerprint);
+    return;
+  }
+
+  if (existingDbName && existingDbName !== desiredDbName) {
+    await dropDatabaseIfExists(infra, existingDbName);
+  }
+  if (await databaseExists(infra, desiredDbName)) {
+    await dropDatabaseIfExists(infra, desiredDbName);
+  }
+
+  await createEmptyDatabase(infra, desiredDbName);
+  const templateUrl = buildDatabaseUrl(infra, desiredDbName);
+  if (hooks.runMigrate) {
+    await hooks.runMigrate(templateUrl);
+  }
+  if (hooks.runSeed) {
+    await hooks.runSeed(templateUrl);
+  }
+
+  writeLocalCacheState(cacheDir, infra, desiredDbName, templateFingerprint);
+}
+
+async function ensureWorkerClone(config, infra, cacheDir, templateFingerprint) {
+  const serviceName = config.name;
+  const templateDbName = readStateValue(path.join(cacheDir, "template_database_name"));
+  if (!templateDbName) {
+    throw new Error(`Missing template database for service "${serviceName}"`);
+  }
+
+  const desiredDbName = buildWorkerDatabaseName(serviceName, config.stateDir, templateFingerprint);
+  const existingDbName = readStateValue(path.join(config.stateDir, "local_database_name"));
+  const existingFingerprint = readStateValue(path.join(config.stateDir, "local_template_fingerprint"));
+  const needsReset =
+    config.testkit.database.reset !== false ||
+    existingFingerprint !== templateFingerprint ||
+    existingDbName !== desiredDbName ||
+    !(await databaseExists(infra, desiredDbName));
+
+  if (existingDbName && existingDbName !== desiredDbName) {
+    await dropDatabaseIfExists(infra, existingDbName);
+  }
+
+  if (needsReset) {
+    await dropDatabaseIfExists(infra, desiredDbName);
+    await cloneDatabaseFromTemplate(infra, desiredDbName, templateDbName);
+  }
+
+  fs.mkdirSync(config.stateDir, { recursive: true });
+  removeNeonRuntimeState(config.stateDir);
+  fs.writeFileSync(path.join(config.stateDir, "database_backend"), "local");
+  fs.writeFileSync(path.join(config.stateDir, "database_url"), buildDatabaseUrl(infra, desiredDbName));
+  fs.writeFileSync(path.join(config.stateDir, "local_database_name"), desiredDbName);
+  fs.writeFileSync(path.join(config.stateDir, "local_template_fingerprint"), templateFingerprint);
+  fs.writeFileSync(path.join(config.stateDir, "local_template_database_name"), templateDbName);
+  fs.writeFileSync(path.join(config.stateDir, "local_container_name"), infra.containerName);
+}
+
+async function destroyLocalRuntimeDatabase(productDir, stateDir) {
+  const dbName = readStateValue(path.join(stateDir, "local_database_name"));
+  if (!dbName) return;
+
+  const infra = await loadExistingLocalContainer(productDir);
+  if (!infra) return;
+  await dropDatabaseIfExists(infra, dbName);
+}
+
+async function ensureLocalContainer(productDir, database = {}) {
+  const infraDir = getLocalInfraDir(productDir);
+  fs.mkdirSync(infraDir, { recursive: true });
+
+  const containerName =
+    readStateValue(path.join(infraDir, "container_name")) || buildContainerName(productDir);
+  const image = database.image || readStateValue(path.join(infraDir, "image")) || LOCAL_IMAGE;
+  const user = database.user || readStateValue(path.join(infraDir, "user")) || LOCAL_USER;
+  const password =
+    database.password || readStateValue(path.join(infraDir, "password")) || LOCAL_PASSWORD;
+
+  let inspect = await inspectContainer(containerName);
+  if (inspect && inspect.Config?.Image !== image) {
+    await stopAndRemoveContainer(containerName);
+    inspect = null;
+  }
+
+  if (!inspect) {
+    await execa("docker", [
+      "run",
+      "-d",
+      "--name",
+      containerName,
+      "-e",
+      `POSTGRES_USER=${user}`,
+      "-e",
+      `POSTGRES_PASSWORD=${password}`,
+      "-e",
+      `POSTGRES_DB=${LOCAL_ADMIN_DB}`,
+      "-p",
+      "127.0.0.1::5432",
+      image,
+    ]);
+    inspect = await inspectContainer(containerName);
+  } else if (!inspect.State?.Running) {
+    await execa("docker", ["start", containerName]);
+    inspect = await inspectContainer(containerName);
+  }
+
+  const hostPort = inspect?.NetworkSettings?.Ports?.["5432/tcp"]?.[0]?.HostPort;
+  if (!hostPort) {
+    throw new Error(`Could not determine published port for local database container ${containerName}`);
+  }
+
+  const infra = {
+    containerName,
+    containerId: inspect.Id,
+    image,
+    user,
+    password,
+    host: "127.0.0.1",
+    port: Number(hostPort),
+  };
+
+  await waitForLocalContainerReady(infra);
+  writeLocalInfraState(infraDir, infra);
+  return infra;
+}
+
+async function loadExistingLocalContainer(productDir) {
+  const infraDir = getLocalInfraDir(productDir);
+  const containerName = readStateValue(path.join(infraDir, "container_name"));
+  if (!containerName) return null;
+
+  const inspect = await inspectContainer(containerName);
+  if (!inspect) return null;
+
+  if (!inspect.State?.Running) {
+    await execa("docker", ["start", containerName]);
+  }
+
+  const nextInspect = await inspectContainer(containerName);
+  const hostPort = nextInspect?.NetworkSettings?.Ports?.["5432/tcp"]?.[0]?.HostPort;
+  if (!hostPort) return null;
+
+  const infra = {
+    containerName,
+    containerId: nextInspect.Id,
+    image: nextInspect.Config?.Image || readStateValue(path.join(infraDir, "image")) || LOCAL_IMAGE,
+    user: readStateValue(path.join(infraDir, "user")) || LOCAL_USER,
+    password: readStateValue(path.join(infraDir, "password")) || LOCAL_PASSWORD,
+    host: "127.0.0.1",
+    port: Number(hostPort),
+  };
+  await waitForLocalContainerReady(infra);
+  return infra;
+}
+
+async function waitForLocalContainerReady(infra) {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < LOCAL_READY_TIMEOUT_MS) {
+    try {
+      await execa("docker", [
+        "exec",
+        infra.containerName,
+        "pg_isready",
+        "-U",
+        infra.user,
+        "-d",
+        LOCAL_ADMIN_DB,
+      ]);
+      return;
+    } catch {
+      await sleep(LOCAL_POLL_INTERVAL_MS);
+    }
+  }
+
+  throw new Error(`Timed out waiting for local database container ${infra.containerName}`);
+}
+
+async function inspectContainer(containerName) {
+  try {
+    const { stdout } = await execa("docker", ["inspect", containerName]);
+    const parsed = JSON.parse(stdout);
+    return parsed[0] || null;
+  } catch {
+    return null;
+  }
+}
+
+async function stopAndRemoveContainer(containerName) {
+  try {
+    await execa("docker", ["rm", "-f", containerName]);
+  } catch {
+    // Already gone.
+  }
+}
+
+async function databaseExists(infra, dbName) {
+  const result = await runAdminQuery(infra, [
+    "-tAc",
+    `SELECT 1 FROM pg_database WHERE datname = '${escapeSqlLiteral(dbName)}'`,
+  ]);
+  return result.trim() === "1";
+}
+
+async function createEmptyDatabase(infra, dbName) {
+  await runAdminQuery(infra, ["-c", `CREATE DATABASE "${escapeIdentifier(dbName)}"`]);
+}
+
+async function cloneDatabaseFromTemplate(infra, dbName, templateDbName) {
+  await runAdminQuery(infra, [
+    "-c",
+    `CREATE DATABASE "${escapeIdentifier(dbName)}" TEMPLATE "${escapeIdentifier(templateDbName)}"`,
+  ]);
+}
+
+async function dropDatabaseIfExists(infra, dbName) {
+  await runAdminQuery(infra, [
+    "-c",
+    [
+      `SELECT pg_terminate_backend(pid)`,
+      `FROM pg_stat_activity`,
+      `WHERE datname = '${escapeSqlLiteral(dbName)}' AND pid <> pg_backend_pid();`,
+    ].join(" "),
+  ]);
+  await runAdminQuery(infra, [
+    "-c",
+    `DROP DATABASE IF EXISTS "${escapeIdentifier(dbName)}"`,
+  ]);
+}
+
+async function runAdminQuery(infra, args) {
+  const commandArgs = [
+    "exec",
+    "-e",
+    `PGPASSWORD=${infra.password}`,
+    infra.containerName,
+    "psql",
+    "-v",
+    "ON_ERROR_STOP=1",
+    "-U",
+    infra.user,
+    "-d",
+    LOCAL_ADMIN_DB,
+    ...args,
+  ];
+  const { stdout } = await execa("docker", commandArgs);
+  return stdout;
+}
+
+async function computeTemplateFingerprint(config) {
+  const hash = crypto.createHash("sha256");
+  const db = config.testkit.database;
+  hash.update(JSON.stringify({
+    provider: db.provider,
+    selectedBackend: db.selectedBackend,
+    image: db.image || LOCAL_IMAGE,
+    user: db.user || LOCAL_USER,
+    migrate: config.testkit.migrate || null,
+    seed: config.testkit.seed || null,
+  }));
+
+  const rootEnvPath = path.join(config.productDir, ".env");
+  appendFileToHash(hash, config.productDir, rootEnvPath);
+  for (const envFile of config.testkit.envFiles || []) {
+    appendFileToHash(hash, config.productDir, resolveServiceCwd(config.productDir, envFile));
+  }
+  for (const input of db.template.inputs || []) {
+    appendInputToHash(hash, config.productDir, input);
+  }
+
+  return hash.digest("hex");
+}
+
+function appendInputToHash(hash, productDir, input) {
+  const absPath = resolveServiceCwd(productDir, input);
+  if (!fs.existsSync(absPath)) {
+    hash.update(`missing:${path.relative(productDir, absPath)}`);
+    return;
+  }
+
+  const stat = fs.statSync(absPath);
+  if (stat.isDirectory()) {
+    hash.update(`dir:${path.relative(productDir, absPath)}`);
+    for (const entry of fs.readdirSync(absPath).sort()) {
+      if (entry === ".git" || entry === "node_modules" || entry === ".testkit") continue;
+      appendInputToHash(hash, productDir, path.join(input, entry));
+    }
+    return;
+  }
+
+  appendFileToHash(hash, productDir, absPath);
+}
+
+function appendFileToHash(hash, productDir, absPath) {
+  if (!fs.existsSync(absPath)) {
+    hash.update(`missing:${path.relative(productDir, absPath)}`);
+    return;
+  }
+  const stat = fs.statSync(absPath);
+  if (!stat.isFile()) return;
+
+  hash.update(`file:${path.relative(productDir, absPath)}:${stat.size}:${stat.mtimeMs}`);
+  hash.update(fs.readFileSync(absPath));
+}
+
+function buildDatabaseUrl(infra, dbName) {
+  return `postgresql://${encodeURIComponent(infra.user)}:${encodeURIComponent(infra.password)}@${infra.host}:${infra.port}/${dbName}?sslmode=disable`;
+}
+
+function buildContainerName(productDir) {
+  return limitIdentifier(
+    `testkit_pg_${slugSegment(path.basename(productDir))}_${hashString(productDir, 10)}`,
+    63
+  );
+}
+
+function buildTemplateDatabaseName(serviceName, fingerprint) {
+  return limitIdentifier(
+    `tk_tpl_${slugSegment(serviceName)}_${fingerprint.slice(0, 16)}`,
+    63
+  );
+}
+
+function buildWorkerDatabaseName(serviceName, stateDir, fingerprint) {
+  return limitIdentifier(
+    `tk_${slugSegment(serviceName)}_${hashString(stateDir, 10)}_${fingerprint.slice(0, 12)}`,
+    63
+  );
+}
+
+function writeLocalInfraState(infraDir, infra) {
+  fs.writeFileSync(path.join(infraDir, "database_backend"), "local");
+  fs.writeFileSync(path.join(infraDir, "container_name"), infra.containerName);
+  fs.writeFileSync(path.join(infraDir, "container_id"), infra.containerId);
+  fs.writeFileSync(path.join(infraDir, "image"), infra.image);
+  fs.writeFileSync(path.join(infraDir, "user"), infra.user);
+  fs.writeFileSync(path.join(infraDir, "password"), infra.password);
+  fs.writeFileSync(path.join(infraDir, "host"), infra.host);
+  fs.writeFileSync(path.join(infraDir, "port"), String(infra.port));
+}
+
+function writeLocalCacheState(cacheDir, infra, templateDbName, fingerprint) {
+  fs.writeFileSync(path.join(cacheDir, "database_backend"), "local");
+  fs.writeFileSync(path.join(cacheDir, "template_database_name"), templateDbName);
+  fs.writeFileSync(path.join(cacheDir, "template_fingerprint"), fingerprint);
+  fs.writeFileSync(path.join(cacheDir, "container_name"), infra.containerName);
+}
+
+function getLocalInfraDir(productDir) {
+  return path.join(productDir, ".testkit", "_infra", "local-postgres");
+}
+
+function getLocalLocksDir(productDir) {
+  return path.join(getLocalInfraDir(productDir), "locks");
+}
+
+function getLocalServiceCacheDir(productDir, serviceName) {
+  return path.join(productDir, ".testkit", "_dbcache", serviceName);
+}
+
+function hasRemainingLocalArtifacts(productDir) {
+  const root = path.join(productDir, ".testkit");
+  if (!fs.existsSync(root)) return false;
+
+  let found = false;
+  visitDirs(root, (dir) => {
+    if (found) return;
+    if (dir.includes(`${path.sep}.testkit${path.sep}_infra`)) return;
+    if (readStateValue(path.join(dir, "database_backend")) === "local") {
+      found = true;
+    }
+  });
+
+  if (found) return true;
+
+  const cacheRoot = path.join(productDir, ".testkit", "_dbcache");
+  if (!fs.existsSync(cacheRoot)) return false;
+  return fs.readdirSync(cacheRoot).some((entry) => {
+    const entryPath = path.join(cacheRoot, entry);
+    return fs.statSync(entryPath).isDirectory();
+  });
+}
+
+function visitDirs(root, visitor) {
+  if (!fs.existsSync(root)) return;
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const dir = path.join(root, entry.name);
+    visitor(dir);
+    visitDirs(dir, visitor);
+  }
+}
+
+function printStateDir(dir, indent) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const filePath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      console.log(`${indent}${entry.name}/`);
+      printStateDir(filePath, `${indent}  `);
+      continue;
+    }
+    const value =
+      entry.name === "password" ? "********" : fs.readFileSync(filePath, "utf8").trim();
+    console.log(`${indent}${entry.name}: ${value}`);
+  }
+}
+
+async function withLock(lockPath, fn) {
+  const lockDir = `${lockPath}.dir`;
+  const timeoutMs = 60_000;
+  const startedAt = Date.now();
+
+  while (true) {
+    try {
+      fs.mkdirSync(lockDir, { recursive: false });
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      if (Date.now() - startedAt > timeoutMs) {
+        throw new Error(`Timed out waiting for lock ${path.basename(lockPath)}`);
+      }
+      await sleep(200);
+    }
+  }
+
+  try {
+    return await fn();
+  } finally {
+    fs.rmSync(lockDir, { recursive: true, force: true });
+  }
+}
+
+function hashString(value, length = 12) {
+  return crypto.createHash("sha256").update(value).digest("hex").slice(0, length);
+}
+
+function slugSegment(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "") || "db";
+}
+
+function limitIdentifier(value, maxLength) {
+  return value.length <= maxLength ? value : value.slice(0, maxLength);
+}
+
+function escapeIdentifier(value) {
+  return String(value).replace(/"/g, "\"\"");
+}
+
+function escapeSqlLiteral(value) {
+  return String(value).replace(/'/g, "''");
+}
+
+function readStateValue(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  return fs.readFileSync(filePath, "utf8").trim();
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function removeLocalRuntimeState(stateDir) {
+  for (const file of [
+    "local_database_name",
+    "local_template_fingerprint",
+    "local_template_database_name",
+    "local_container_name",
+  ]) {
+    fs.rmSync(path.join(stateDir, file), { force: true });
+  }
+}
+
+function removeNeonRuntimeState(stateDir) {
+  for (const file of ["neon_project_id", "neon_branch_id"]) {
+    fs.rmSync(path.join(stateDir, file), { force: true });
+  }
+}

package/lib/runner.mjs

@@ -3,12 +3,15 @@ import path from "path";
 import { spawn } from "child_process";
 import net from "net";
 import { execa, execaCommand } from "execa";
-import { runScript } from "./exec.mjs";
+import { resolveDalBinary, resolveServiceCwd } from "./config.mjs";
 import {
-  requireNeonApiKey,
-  resolveDalBinary,
-  resolveServiceCwd,
-} from "./config.mjs";
+  cleanupOrphanedLocalInfrastructure,
+  destroyRuntimeDatabase,
+  destroyServiceDatabaseCache,
+  isDatabaseStateDir,
+  prepareDatabaseRuntime,
+  showServiceDatabaseStatus,
+} from "./database.mjs";
 
 const TYPE_ORDER = ["dal", "integration", "e2e", "load"];
 const HTTP_K6_TYPES = new Set(["integration", "e2e", "load"]);
@@ -38,25 +41,24 @@ export async function destroy(config) {
 
   const runtimeStateDirs = findRuntimeStateDirs(config.stateDir);
   for (const stateDir of runtimeStateDirs) {
-    const projectId = readStateValue(path.join(stateDir, "neon_project_id"));
-    if (!projectId) continue;
-
-    await runScript("neon-down.sh", {
-      NEON_PROJECT_ID: projectId,
-      STATE_DIR: stateDir,
+    await destroyRuntimeDatabase({
+      productDir: config.productDir,
+      stateDir,
     });
   }
 
+  await destroyServiceDatabaseCache(config.productDir, config.name);
   fs.rmSync(config.stateDir, { recursive: true, force: true });
+  await cleanupOrphanedLocalInfrastructure(config.productDir);
 }
 
 export function showStatus(config) {
   if (!fs.existsSync(config.stateDir)) {
     console.log("No state — run tests first.");
-    return;
+  } else {
+    printStateDir(config.stateDir, "  ");
   }
-
-  printStateDir(config.stateDir, "  ");
+  showServiceDatabaseStatus(config.productDir, config.name);
 }
 
 async function runService(targetConfig, configMap, suiteType, suiteNames, opts, runtimeSlot) {
@@ -387,9 +389,12 @@ function resolveWorkerConfig(
     ? {
         ...config.testkit.database,
         branchName:
+          config.testkit.database.provider === "neon" &&
           config.testkit.database.branchName !== undefined
             ? finalizeString(config.testkit.database.branchName, context)
-            : `${targetConfig.name}-${config.name}-w${workerId}-testkit`,
+            : config.testkit.database.provider === "neon"
+              ? `${targetConfig.name}-${config.name}-w${workerId}-testkit`
+              : undefined,
       }
     : undefined;
 
@@ -464,8 +469,6 @@ async function runWorkerPlan(plan) {
 
   try {
     await prepareDatabases(plan.runtimeConfigs);
-    await runMigrations(plan.runtimeConfigs);
-    await runSeeds(plan.runtimeConfigs);
 
     if (needsLocalRuntime(plan.suites)) {
       startedServices = await startLocalServices(plan.runtimeConfigs);
@@ -501,60 +504,45 @@ async function runWorkerPlan(plan) {
 
 async function prepareDatabases(runtimeConfigs) {
   for (const config of runtimeConfigs) {
-    const db = config.testkit.database;
-    if (!db) continue;
-
-    requireNeonApiKey();
-    fs.mkdirSync(config.stateDir, { recursive: true });
-
-    await runScript("neon-up.sh", {
-      NEON_PROJECT_ID: db.projectId,
-      NEON_DB_NAME: db.dbName,
-      NEON_BRANCH_NAME: db.branchName,
-      NEON_RESET: db.reset === false ? "false" : "true",
-      STATE_DIR: config.stateDir,
+    await prepareDatabaseRuntime(config, {
+      runMigrate: config.testkit.migrate
+        ? (databaseUrl) => runMigrate(config, databaseUrl)
+        : null,
+      runSeed: config.testkit.seed ? (databaseUrl) => runSeed(config, databaseUrl) : null,
     });
-
-    fs.writeFileSync(path.join(config.stateDir, "neon_project_id"), db.projectId);
   }
 }
 
-async function runMigrations(runtimeConfigs) {
-  for (const config of runtimeConfigs) {
-    const migrate = config.testkit.migrate;
-    if (!migrate) continue;
+async function runMigrate(config, databaseUrl) {
+  const migrate = config.testkit.migrate;
+  if (!migrate) return;
 
-    const env = buildExecutionEnv(config);
-    const dbUrl = readDatabaseUrl(config.stateDir);
-    if (dbUrl) env.DATABASE_URL = dbUrl;
+  const env = buildExecutionEnv(config);
+  if (databaseUrl) env.DATABASE_URL = databaseUrl;
 
-    console.log(`\n── migrate:${config.workerLabel}:${config.name} ──`);
-    await execaCommand(migrate.cmd, {
-      cwd: resolveServiceCwd(config.productDir, migrate.cwd),
-      env,
-      stdio: "inherit",
-      shell: true,
-    });
-  }
+  console.log(`\n── migrate:${config.workerLabel}:${config.name} ──`);
+  await execaCommand(migrate.cmd, {
+    cwd: resolveServiceCwd(config.productDir, migrate.cwd),
+    env,
+    stdio: "inherit",
+    shell: true,
+  });
 }
 
-async function runSeeds(runtimeConfigs) {
-  for (const config of runtimeConfigs) {
-    const seed = config.testkit.seed;
-    if (!seed) continue;
+async function runSeed(config, databaseUrl) {
+  const seed = config.testkit.seed;
+  if (!seed) return;
 
-    const env = buildExecutionEnv(config);
-    const dbUrl = readDatabaseUrl(config.stateDir);
-    if (dbUrl) env.DATABASE_URL = dbUrl;
+  const env = buildExecutionEnv(config);
+  if (databaseUrl) env.DATABASE_URL = databaseUrl;
 
-    console.log(`\n── seed:${config.workerLabel}:${config.name} ──`);
-    await execaCommand(seed.cmd, {
-      cwd: resolveServiceCwd(config.productDir, seed.cwd),
-      env,
-      stdio: "inherit",
-      shell: true,
-    });
-  }
+  console.log(`\n── seed:${config.workerLabel}:${config.name} ──`);
+  await execaCommand(seed.cmd, {
+    cwd: resolveServiceCwd(config.productDir, seed.cwd),
+    env,
+    stdio: "inherit",
+    shell: true,
+  });
 }
 
 async function startLocalServices(runtimeConfigs) {
@@ -1180,12 +1168,7 @@ function findRuntimeStateDirs(rootDir) {
   const visit = (dir) => {
     if (!fs.existsSync(dir)) return;
     const entries = fs.readdirSync(dir, { withFileTypes: true });
-    const hasRuntimeFiles = entries.some(
-      (entry) =>
-        entry.isFile() &&
-        (entry.name === "neon_project_id" || entry.name === "neon_branch_id")
-    );
-    if (hasRuntimeFiles) {
+    if (isDatabaseStateDir(dir)) {
       found.push(dir);
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "CLI for running manifest-defined local test suites across k6 and Playwright",
   "type": "module",
   "bin": {