pg-here 0.1.5 → 0.1.9

package/README.md

@@ -1,335 +1,92 @@
 # pg-here
 
-Per-project Postgres instances with instant snapshot & restore to support yolo development methods.
+Run a local PostgreSQL instance in your project folder with one command.
 
-Repository: https://github.com/mayfer/pg-here
-
-## Project-Local PostgreSQL Setup
-
-Each project runs its own isolated PostgreSQL instance. Downloads correct binary automatically for your CPU architecture (x86_64 / arm64). Database lives inside the project folder.
-
-### Quick Start
-
-Start PostgreSQL:
-
-```bash
-bun run db:up
-```
-
-Output:
-```
-postgresql://postgres:postgres@localhost:55432/postgres
-```
-
-Connect from your app using that connection string, then Ctrl+C to stop.
-
-### One-command start from npm (no local install)
-
-If you have Bun installed, you can run the published package directly:
+## 30-second start
 
 ```bash
 bunx pg-here
 ```
 
-This is the single command you want from any directory.
-
-If it still resolves an older release, the package `latest` dist-tag is behind:
+Default output:
 
-To force that version and bypass a stale cache:
-
-```bash
-bunx pg-here@0.1.5
+```text
+Launching PostgreSQL 18.0.0 into new pg_local/
+psql postgresql://postgres:postgres@localhost:55432/postgres
 ```
 
-If maintainers want plain `bunx pg-here` to work for everyone, run once:
+If a data folder already exists:
 
-```bash
-npm dist-tag add pg-here@0.1.5 latest
+```text
+Reusing existing pg_local/data/ with PostgreSQL 18.0.0
+psql postgresql://postgres:postgres@localhost:55432/postgres
 ```
 
-After that, this should work anywhere:
+If the cached folder version differs:
 
-```bash
-bunx pg-here
+```text
+Reusing existing pg_local/data/ (pg_local/bin has 18.0.0, running PostgreSQL is 18.0)
+psql postgresql://postgres:postgres@localhost:55432/postgres
 ```
 
-This starts a local PostgreSQL instance in your current project directory and prints the connection string, then keeps the process alive until you stop it.
+The process stays alive until you stop it.  
+Ctrl+C → exits and stops Postgres.
+
+## Defaults (all args optional)
 
-`bunx pg-here` uses these defaults if you pass nothing:
-- `username=postgres`
-- `password=postgres`
-- `database=postgres`
-- `port=55432`
+`bunx pg-here`
 
-All args are optional.
+- `username = postgres`
+- `password = postgres`
+- `database = postgres`
+- `port = 55432`
+- `pg-version` = auto
 
-Pass CLI flags just like the local script when you want to override defaults:
+## Custom run
 
 ```bash
-bunx pg-here --username postgres --password postgres --database my_app --port 55432
+bunx pg-here --username me --password secret --database my_app --port 55433 --pg-version 17.0.0
 ```
 
-#### Linux note
-
-If `bunx pg-here` fails with `error while loading shared libraries`:
-- install missing system packages on the host (not in npm), then retry
-- restart the command
-
-Most commonly:
+You can also run locally in this repo:
 
 ```bash
-# Ubuntu/Debian
-sudo apt-get update && sudo apt-get install -y libxml2
-
-# Fedora/RHEL
-sudo dnf install -y libxml2
-
-# Alpine
-sudo apk add libxml2
+bun run db:up
 ```
 
-If that machine is intentionally minimal (or containerized), use an image with PostgreSQL runtime dependencies.
-
-### Programmatic usage
+Same CLI flags are supported.
 
-Use `pg-here` directly from your server startup code and auto-create the app database if missing.
+## Programmatic
 
 ```ts
 import { startPgHere } from "pg-here";
 
-const pgHere = await startPgHere({
+const pg = await startPgHere({
   projectDir: process.cwd(),
-  port: 55432,
   database: "my_app",
   createDatabaseIfMissing: true,
-  postgresVersion: "18.0.0",
 });
 
-console.log(pgHere.databaseConnectionString);
-
-// On shutdown:
-await pgHere.stop();
+console.log(pg.databaseConnectionString); // psql-ready URL
+await pg.stop();
 ```
 
-`databaseConnectionString` points to your target DB (`my_app` above).  
-If the DB does not exist yet, `createDatabaseIfMissing: true` creates it on startup.
-Set `postgresVersion` if you want to pin/select a specific PostgreSQL version.
-By default, `startPgHere()` installs SIGINT/SIGTERM shutdown hooks that stop Postgres when
-your process exits, and `stop()` preserves data (no cluster cleanup/delete).
-Use `await pgHere.cleanup()` only when you explicitly want full resource cleanup.
-`pg_stat_statements` is enabled automatically (`shared_preload_libraries` + extension creation).
-Set `enablePgStatStatements: false` to opt out.
+## Linux runtime error (quick fix)
 
-### CLI Options
+If startup fails with missing `libxml2` libraries, install runtime packages and retry:
 
 ```bash
-# Custom credentials
-bun run db:up --username postgres --password postgres
-
-# Short flags
-bun run db:up -u postgres -p postgres
-
-# Custom port
-bun run db:up --port 55433
-
-# All together
-bun run db:up -u postgres -p postgres --database postgres --port 55433
-
-# Pin postgres version
-bun run db:up --pg-version 18.0.0
-```
-
-**Defaults**: username=`postgres`, password=`postgres`, port=`55432`, pg-version=`PG_VERSION` or pg-embedded default
-
-### Project Structure
-
-```
-project/
-  pg_local/
-    data/        # PostgreSQL data cluster (persists between runs)
-    bin/         # Downloaded PostgreSQL binaries
-  scripts/
-    pg-dev.mjs   # Runner script
-  package.json
-```
-
-### How It Works
-
-- PostgreSQL only runs when you execute `bun run db:up`
-- Correct architecture binary downloads automatically on first run
-- Data persists in `pg_local/data/` across restarts
-- Process stops completely on exit (Ctrl+C)
-- One instance per project, no system PostgreSQL dependency
-
----
-
-## Use this from another project (recommended)
-
-Keep this repo in one place, and point it at any other project directory when you want a dedicated Postgres instance there.
-
-Example: your app lives at `/path/to/my-app`, but this repo lives elsewhere.
-
-```
-# start postgres for that project (one-time init happens automatically)
-bun run snapshot snapshot /path/to/my-app/.pg-here
-
-# list snapshots for that project
-bun run snapshot list /path/to/my-app/.pg-here
-
-# revert that project to a snapshot
-bun run revert /path/to/my-app/.pg-here snap_YYYYMMDD_HHMMSS
+sudo apt-get update && sudo apt-get install -y libxml2 libxml2-utils
+sudo dnf install -y libxml2
+sudo apk add libxml2
 ```
 
-Tips:
-- Pick a per-project folder (e.g. `.pg-here`) and reuse it.
-- The project directory just needs to be on the same APFS volume for clones to be fast.
-- You can also pass the directory with `--project/-p` instead of positional.
-
-To install dependencies:
+This release already retries startup with a project-local `libxml2` compatibility fallback when needed.
 
-```bash
-bun install
-```
+## Version pin / stale cache
 
-To run:
+If your environment keeps resolving an older release, force a specific version:
 
 ```bash
-bun run index.ts
+bunx pg-here@0.1.9
 ```
-
-This project was created using `bun init` in bun v1.3.1. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
-
-## APFS clone snapshots (macOS) — insanely simple
-
-### The 30‑second version
-
-```
-# take a snapshot for the default project directory
-bun run snapshot snapshot
-
-# list snapshots
-bun run snapshot list
-
-# revert to a snapshot (copy from list output)
-bun run snapshot revert snap_YYYYMMDD_HHMMSS
-
-# or use the alias
-bun run revert snap_YYYYMMDD_HHMMSS
-```
-
-By default, snapshots live under `./pg_projects/default`. You can pass a project directory explicitly if you want.
-
-### What this does
-
-- Uses APFS copy‑on‑write clones (`cp -cR` / `ditto --clone`)
-- Stops Postgres during snapshot/revert (cold stop/start)
-- Keeps snapshots immutable and restores into new instances
-
-### Why it's great
-
-- Near‑instant snapshot and revert via copy‑on‑write
-- Space grows only with changed blocks
-- No volume‑wide rollback
-- No WAL/PITR complexity
-- macOS‑native, zero extra services
-- Deterministic failure modes
-
-### Operational constraints
-
-- PostgreSQL must be stopped for snapshot/revert
-- Source and destination must be on the same APFS volume
-- One cluster per project
-
-### Under the hood layout
-
-```
-~/pg/proj/
-  current -> instances/inst_active
-  instances/
-  snaps/
-```
-
-### Full commands (helper script)
-
-```
-# snapshot current cluster
-bun run snapshot snapshot /path/to/project
-
-# list snapshots
-bun run snapshot list /path/to/project
-
-# revert to a snapshot
-bun run snapshot revert /path/to/project snap_YYYYMMDD_HHMMSS
-```
-
-Flags (optional):
-
-```
---project/-p   project directory (same as positional projectDir)
---snap/-s      snapshot name (for revert)
---pg-ctl       path to pg_ctl (overrides PG_CTL)
-```
-
-If `pg_ctl` isn't on your `PATH`, set `PG_CTL`. By default the script looks in `./pg_local/bin/*/bin/pg_ctl`.
-
-### One‑shot test (does everything end‑to‑end)
-
-```
-bun run snapshot:test
-```
-
-This:
-1) Starts a temporary cluster
-2) Writes sample data
-3) Snapshots
-4) Mutates data
-5) Restores
-6) Verifies the original data returns
-
-Optional flags:
-
-```
---project/-p   project directory (default: ./pg_projects/apfs_test_TIMESTAMP)
---port         postgres port (default: 55433 or PGPORT_SNAPSHOT_TEST)
---pg-version   postgres version (default: PG_VERSION or pg-embedded default)
---keep         keep the project directory after the test
-```
-
-### Bun test integration
-
-```
-bun test
-bun run test:apfs
-```
-
-Set `SKIP_APFS_TEST=1` to skip the APFS snapshot test.
-
-## APFS clone speed benchmark
-
-Compares clone time between a small and large dataset by seeding a table and cloning the data directory.
-
-```
-bun run bench:apfs
-```
-
-Optional flags:
-
-```
---project/-p   project directory (default: ./pg_projects/bench)
---port         postgres port (default: 55434 or PGPORT_BENCH)
---small-rows   rows for small dataset (default: 50_000)
---large-rows   rows for large dataset (default: 2_000_000)
---row-bytes    payload bytes per row (default: 256)
---pg-version   postgres version (default: PG_VERSION or pg-embedded default)
-```
-
-Example:
-
-```
-bun run bench:apfs --small-rows 100000 --large-rows 5000000 --row-bytes 512
-```
-
-### When to choose something else
-
-- Need online "rewind to 5 minutes ago" repeatedly → base backup + WAL/PITR
-- Dataset ≥ ~50 GB with heavy churn → dedicated APFS volume + volume snapshots, or move DB off the laptop

package/bin/pg-here.mjs

@@ -3,7 +3,12 @@
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 import { startPgHere } from "../dist/index.js";
-import { maybePrintLinuxRuntimeHelp } from "../scripts/cli-error-help.mjs";
+import {
+  maybePrintLinuxRuntimeHelp,
+  getPreStartPgHereState,
+  printPgHereStartupInfo,
+  startPgHereWithLibxml2Compat,
+} from "../scripts/cli-error-help.mjs";
 
 const argv = await yargs(hideBin(process.argv))
   .version(false)
@@ -33,8 +38,9 @@ const argv = await yargs(hideBin(process.argv))
   .parse();
 
 let pg;
-try {
-  pg = await startPgHere({
+const preStartState = getPreStartPgHereState(process.cwd());
+const startInstance = () =>
+  startPgHere({
     projectDir: process.cwd(),
     port: argv.port,
     username: argv.username,
@@ -42,6 +48,9 @@ try {
     database: argv.database,
     postgresVersion: argv["pg-version"],
   });
+
+try {
+  pg = await startPgHereWithLibxml2Compat(startInstance, process.cwd());
 } catch (error) {
   if (process.platform === "linux") {
     maybePrintLinuxRuntimeHelp(error);
@@ -49,5 +58,11 @@ try {
   throw error;
 }
 
-console.log(pg.databaseConnectionString);
+printPgHereStartupInfo({
+  connectionString: pg.databaseConnectionString,
+  instance: pg.instance,
+  preStartState,
+  requestedVersion: argv["pg-version"],
+});
+
 setInterval(() => {}, 1 << 30);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pg-here",
-  "version": "0.1.5",
+  "version": "0.1.9",
   "description": "Per-project embedded PostgreSQL with programmatic startup and auto DB creation.",
   "type": "module",
   "main": "./dist/index.js",

package/scripts/cli-error-help.mjs

@@ -1,11 +1,42 @@
 import { spawnSync } from "node:child_process";
+import {
+  accessSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readlinkSync,
+  readdirSync,
+  rmSync,
+  symlinkSync,
+  F_OK,
+} from "node:fs";
+import { join } from "node:path";
 
-const LIBXML_LIBRARY = /libxml2\.so\.2/;
+const LIBXML2_SONAME = "libxml2.so.2";
+const LIBXML2_ALTERNATE_SONAME = "libxml2.so.16";
+const LIBXML2_COMPAT_DIR = "pg_local/runtime-libs";
+
+const LIB_PATHS = [
+  "/usr/lib/x86_64-linux-gnu",
+  "/usr/lib/i386-linux-gnu",
+  "/usr/lib",
+  "/lib/x86_64-linux-gnu",
+  "/lib/i386-linux-gnu",
+  "/lib",
+  "/usr/local/lib",
+];
+
+const PG_LOCAL_DIR = "pg_local";
+const PG_LOCAL_DATA_DIR = "data";
+const PG_LOCAL_BIN_DIR = "bin";
+const PG_VERSION_FILE = "PG_VERSION";
+const VERSION_DIR_RE = /^\d+\.\d+(?:\.\d+)?$/;
 
 export function maybePrintLinuxRuntimeHelp(error) {
   const message = String(error?.message ?? error);
   const missingLibsFromError = extractMissingLibrariesFromMessage(message);
   const missingLibsFromBinary = extractMissingLibrariesFromBinaryPath(message);
+  const binPath = extractBinaryPathFromError(message);
 
   const missingLibs = [...new Set([...missingLibsFromError, ...missingLibsFromBinary])];
 
@@ -18,20 +49,248 @@ export function maybePrintLinuxRuntimeHelp(error) {
   console.error(`Missing libraries: ${missingLibs.join(", ")}`);
   console.error();
   console.error("Install system packages for your distro and retry:");
-  console.error("  Ubuntu/Debian: sudo apt-get update && sudo apt-get install -y libxml2");
-  console.error("  Fedora/RHEL:   sudo dnf install -y libxml2");
-  console.error("  Alpine:        sudo apk add libxml2");
   console.error(
-    `If your distro requires different package names, install packages that provide: ${missingLibs.join(
-      ", "
-    )}`
+    "  Ubuntu/Debian: sudo apt-get update && sudo apt-get install -y libxml2 libxml2-dev libxml2-utils"
+  );
+  console.error(
+    "  Fedora/RHEL:   sudo dnf install -y libxml2"
+  );
+  console.error(
+    "  Alpine:        sudo apk add libxml2"
+  );
+  console.error();
+  console.error("  Quick checks:");
+  console.error(
+    "    find /usr/lib /usr/local/lib /lib -name 'libxml2.so.2*' 2>/dev/null | head"
+  );
+  if (binPath) {
+    console.error(`    ldd ${binPath} | grep libxml2`);
+  }
+  console.error("    sudo ldconfig && sudo ldconfig -p | grep libxml2.so.2");
+  if (binPath.includes("/bin/bin/postgres")) {
+    console.error("  Your local pg_local cache looks partially provisioned (bin/bin/postgres path).");
+    console.error("  Try removing it and retrying:");
+    console.error("    rm -rf pg_local && bunx pg-here@0.1.9");
+  }
+  console.error(
+    `If your distro requires different package names, install packages that provide: ${missingLibs.join(", ")}`
   );
+  printPotentialSymlinkHint();
+
+  if (hasLibxml2CompatibilityNeed(error)) {
+    const fallback = findLibraryPath(LIBXML2_ALTERNATE_SONAME);
+    console.error();
+    console.error("Compatibility note:");
+    if (fallback) {
+      console.error(
+        `This host only provides ${LIBXML2_ALTERNATE_SONAME} at ${fallback}, not ${LIBXML2_SONAME}.`
+      );
+      console.error(
+        "This release now retries startup with a project-local symlink fallback automatically."
+      );
+      console.error(
+        `If that does not work, you can retry with a global symlink (requires sudo):\n    sudo ln -sfn ${fallback} /usr/local/lib/${LIBXML2_SONAME} && sudo ldconfig`
+      );
+    } else {
+      console.error(
+        `Expected ${LIBXML2_SONAME} was not found and no ${LIBXML2_ALTERNATE_SONAME} fallback was discovered.`
+      );
+      console.error(
+        `Your host may be too minimal or custom; install a PostgreSQL-ready runtime stack for your distro.`
+      );
+    }
+  }
+}
+
+export function hasLibxml2CompatibilityNeed(error) {
+  const message = String(error?.message ?? error);
+  const missingFromMessage = extractMissingLibrariesFromMessage(message);
+  const missingFromBinary = extractMissingLibrariesFromBinaryPath(message);
+  const missing = [...missingFromMessage, ...missingFromBinary];
+  return missing.includes(LIBXML2_SONAME) || message.includes("libxml2.so.2");
+}
+
+export function getPreStartPgHereState(projectDir) {
+  const normalizedProjectDir = typeof projectDir === "string" && projectDir ? projectDir : process.cwd();
+  const dataDir = join(normalizedProjectDir, PG_LOCAL_DIR, PG_LOCAL_DATA_DIR);
+  const binDir = join(normalizedProjectDir, PG_LOCAL_DIR, PG_LOCAL_BIN_DIR);
+  const hasData = existsSync(dataDir);
+  const hasPgVersionFile = existsSync(join(dataDir, PG_VERSION_FILE));
+  const installedVersions = getInstalledPostgresVersions(binDir);
+
+  return {
+    dataDir,
+    hasData,
+    hasPgVersionFile,
+    installedVersions,
+    installedVersion: installedVersions[0] ?? "",
+  };
+}
+
+export function printPgHereStartupInfo({
+  connectionString,
+  instance,
+  preStartState,
+  requestedVersion,
+}) {
+  const { hasData, installedVersion } = preStartState ?? {};
+  const startedVersion = getPostgresInstanceVersion(instance);
+
+  const displayVersion =
+    startedVersion || requestedVersion || "default";
+  const dataPath = `${PG_LOCAL_DIR}/${PG_LOCAL_DATA_DIR}/`;
+  const firstLine = hasData
+    ? getExistingDataStatusLine({ installedVersion, startedVersion, requestedVersion, dataPath })
+    : `Launching PostgreSQL ${displayVersion} into new ${PG_LOCAL_DIR}/`;
 
-  if (LIBXML_LIBRARY.test(message)) {
-    console.error("Hint: this project does not ship all optional shared objects in every Linux image.");
+  console.log(firstLine);
+  if (typeof connectionString === "string" && connectionString.length > 0) {
+    console.log(`psql ${connectionString}`);
   }
 }
 
+function getExistingDataStatusLine({
+  installedVersion,
+  startedVersion,
+  requestedVersion,
+  dataPath,
+}) {
+  const runVersion = startedVersion || requestedVersion || "default";
+  if (installedVersion && startedVersion && installedVersion !== startedVersion) {
+    return `Reusing existing ${dataPath} (pg_local/bin has ${installedVersion}, running PostgreSQL is ${startedVersion})`;
+  }
+
+  if (installedVersion && startedVersion && installedVersion === startedVersion) {
+    return `Reusing existing ${dataPath} with PostgreSQL ${runVersion}`;
+  }
+
+  return `Reusing existing ${dataPath} with PostgreSQL ${runVersion}`;
+}
+
+function getPostgresInstanceVersion(instance) {
+  try {
+    if (typeof instance?.getPostgreSqlVersion === "function") {
+      return instance.getPostgreSqlVersion();
+    }
+  } catch {
+    return "";
+  }
+
+  return "";
+}
+
+function compareSemVerDesc(left, right) {
+  const leftParts = left.split(".").map((segment) => Number.parseInt(segment, 10) || 0);
+  const rightParts = right.split(".").map((segment) => Number.parseInt(segment, 10) || 0);
+  const maxLength = Math.max(leftParts.length, rightParts.length);
+  for (let i = 0; i < maxLength; i += 1) {
+    const leftValue = leftParts[i] ?? 0;
+    const rightValue = rightParts[i] ?? 0;
+    if (leftValue === rightValue) {
+      continue;
+    }
+    return rightValue - leftValue;
+  }
+
+  return 0;
+}
+
+export async function startPgHereWithLibxml2Compat(start, workingDir) {
+  try {
+    return await start();
+  } catch (error) {
+    if (!hasLibxml2CompatibilityNeed(error)) {
+      throw error;
+    }
+
+    const patched = ensureLibxml2Compatibility(workingDir);
+    if (!patched) {
+      throw error;
+    }
+
+    return await start();
+  }
+}
+
+function getInstalledPostgresVersions(baseDir) {
+  if (!existsSync(baseDir)) {
+    return [];
+  }
+
+  let entries = [];
+  try {
+    entries = readdirSync(baseDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  return entries
+    .filter((entry) => entry.isDirectory() && VERSION_DIR_RE.test(entry.name))
+    .map((entry) => entry.name)
+    .sort(compareSemVerDesc);
+}
+
+
+export function ensureLibxml2Compatibility(workingDir) {
+  if (process.platform !== "linux") {
+    return false;
+  }
+
+  const projectDir = typeof workingDir === "string" && workingDir ? workingDir : process.cwd();
+  const compatDir = join(projectDir, LIBXML2_COMPAT_DIR);
+  const compatLib = join(compatDir, LIBXML2_SONAME);
+
+  if (findLibraryPath(LIBXML2_SONAME)) {
+    return false;
+  }
+
+  const fallback = findLibraryPath(LIBXML2_ALTERNATE_SONAME);
+  if (!fallback) {
+    return false;
+  }
+
+  try {
+    mkdirSync(compatDir, { recursive: true });
+    if (existsSync(compatLib)) {
+      const existing = readCompatLink(compatLib);
+      if (existing === fallback) {
+        ensureLdLibraryPath(compatDir);
+        return true;
+      }
+
+      rmSync(compatLib, { force: true });
+    }
+
+    symlinkSync(fallback, compatLib);
+    ensureLdLibraryPath(compatDir);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readCompatLink(path) {
+  try {
+    const info = lstatSync(path);
+    if (!info.isSymbolicLink()) {
+      return "";
+    }
+    return readlinkSync(path);
+  } catch {
+    return "";
+  }
+}
+
+function ensureLdLibraryPath(path) {
+  const currentPath = process.env.LD_LIBRARY_PATH ?? "";
+  const paths = currentPath.split(":").filter(Boolean);
+  if (paths.includes(path)) {
+    return;
+  }
+
+  process.env.LD_LIBRARY_PATH = path + (currentPath ? `:${currentPath}` : "");
+}
+
 function extractMissingLibrariesFromMessage(message) {
   const regex = /([A-Za-z0-9._-]+\.so(?:\.\d+)*)\b/g;
   const matches = [...message.matchAll(regex)].map((match) => match[1]);
@@ -55,3 +314,68 @@ function extractMissingLibrariesFromBinaryPath(message) {
     (match) => match[1]
   );
 }
+
+function extractBinaryPathFromError(message) {
+  const pathMatch = message.match(/(\/[^\s"]*\/bin\/postgres)/);
+  return pathMatch ? pathMatch[1] : "";
+}
+
+function hasLibxmlVersion16Only() {
+  const candidates = ["/usr/lib/x86_64-linux-gnu", "/usr/lib", "/lib/x86_64-linux-gnu", "/lib"];
+  for (const dir of candidates) {
+    try {
+      accessSync(`${dir}/libxml2.so.2`, F_OK);
+      return false;
+    } catch {
+      // continue
+    }
+
+    try {
+      accessSync(`${dir}/libxml2.so.16`, F_OK);
+      if (hasLibxmlVersion16AtPath(`${dir}/libxml2.so.16`)) {
+        return true;
+      }
+    } catch {}
+  }
+
+  return false;
+}
+
+function hasLibxmlVersion16AtPath(path) {
+  return typeof path === "string" && path.endsWith("/libxml2.so.16");
+}
+
+function printPotentialSymlinkHint() {
+  const result = spawnSync("sh", [
+    "-c",
+    "find /usr/lib /usr/local/lib /lib -name 'libxml2.so.2*' 2>/dev/null",
+  ], { encoding: "utf8" });
+
+  if (result.status !== 0) {
+    return;
+  }
+
+  const matches = (result.stdout ?? "").split("\n").filter(Boolean);
+  const exact = matches.find((item) => item.endsWith("/libxml2.so.2"));
+  if (!exact) {
+    console.error();
+    console.error("Hint:");
+    if (hasLibxmlVersion16Only()) {
+      console.error("This host appears to provide only libxml2.so.16. Compatibility is not guaranteed.");
+    } else {
+      console.error("No libxml2.so.2 file was found in the standard library paths.");
+    }
+  }
+}
+
+function findLibraryPath(name) {
+  const args = [...LIB_PATHS, "-name", `${name}*`, "-print"];
+  const result = spawnSync("find", args, { encoding: "utf8" });
+  const matches = (result.stdout ?? "").split("\n").filter(Boolean);
+  if (matches.length === 0) {
+    return "";
+  }
+
+  const exact = matches.find((item) => item.endsWith(`/${name}`));
+  return exact ?? matches[0];
+}

package/scripts/pg-dev.mjs

@@ -1,7 +1,12 @@
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 import { startPgHere } from "../index.ts";
-import { maybePrintLinuxRuntimeHelp } from "./cli-error-help.mjs";
+import {
+  maybePrintLinuxRuntimeHelp,
+  getPreStartPgHereState,
+  printPgHereStartupInfo,
+  startPgHereWithLibxml2Compat,
+} from "./cli-error-help.mjs";
 
 const argv = await yargs(hideBin(process.argv))
   .version(false)
@@ -31,8 +36,9 @@ const argv = await yargs(hideBin(process.argv))
   .parse();
 
 let pg;
-try {
-  pg = await startPgHere({
+const preStartState = getPreStartPgHereState(process.cwd());
+const startInstance = () =>
+  startPgHere({
     projectDir: process.cwd(),
     port: argv.port,
     username: argv.username,
@@ -40,6 +46,9 @@ try {
     database: argv.database,
     postgresVersion: argv["pg-version"],
   });
+
+try {
+  pg = await startPgHereWithLibxml2Compat(startInstance, process.cwd());
 } catch (error) {
   if (process.platform === "linux") {
     maybePrintLinuxRuntimeHelp(error);
@@ -47,8 +56,12 @@ try {
   throw error;
 }
 
-// print connection string for tooling
-console.log(pg.databaseConnectionString);
+printPgHereStartupInfo({
+  connectionString: pg.databaseConnectionString,
+  instance: pg.instance,
+  preStartState,
+  requestedVersion: argv["pg-version"],
+});
 
 // keep this process alive; Ctrl-C stops postgres
 setInterval(() => {}, 1 << 30);