pg-here 0.1.4 → 0.1.8

package/README.md

@@ -31,7 +31,27 @@ If you have Bun installed, you can run the published package directly:
 bunx pg-here
 ```
 
-If this command fails with `could not determine executable to run for package`, install at least `pg-here@0.1.4` (this is the first release with a real package binary).
+This is the single command you want from any directory.
+
+If it still resolves an older release, the package `latest` dist-tag may be behind:
+
+To force that version and bypass a stale cache:
+
+```bash
+bunx pg-here@0.1.8
+```
+
+If maintainers want plain `bunx pg-here` to work for everyone, run once:
+
+```bash
+npm dist-tag add pg-here@0.1.8 latest
+```
+
+After that, this should work anywhere:
+
+```bash
+bunx pg-here
+```
 
 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.
 
@@ -49,6 +69,58 @@ Pass CLI flags just like the local script when you want to override defaults:
 bunx pg-here --username postgres --password postgres --database my_app --port 55432
 ```
 
+#### 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:
+
+```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
+```
+
+If that machine is intentionally minimal (or containerized), use an image with PostgreSQL runtime dependencies.
+
+If apt says `Package 'libxml2' has no installation candidate`, your apt sources are likely missing standard repos.
+
+```bash
+cat /etc/os-release
+apt-cache search '^libxml2$'
+```
+
+and if that returns nothing, fix apt sources for your distro/arch first, or use a base image that includes PostgreSQL runtime packages.
+
+Important ABI note:
+
+- If your host exposes `libxml2.so.16` but not `libxml2.so.2`, older releases may fail to start before applying fallback.
+- If a failure mentions `/pg_local/bin/bin/postgres`, clear and redownload:
+
+```bash
+rm -rf pg_local
+bunx pg-here@0.1.8
+```
+
+For this release, `0.1.8` also attempts a one-time compatibility workaround when it detects
+`libxml2.so.16`-only hosts:
+- it creates a local runtime symlink in `./pg_local/runtime-libs/libxml2.so.2` pointing to the discovered `libxml2.so.16`
+- sets `LD_LIBRARY_PATH` for the retry so `postgres`/`initdb` can launch
+
+If your system is locked down and this still fails, create a global compatibility symlink (where permitted):
+
+```bash
+sudo ln -sfn /usr/lib/x86_64-linux-gnu/libxml2.so.16 /usr/local/lib/libxml2.so.2
+sudo ldconfig
+```
+
 ### Programmatic usage
 
 Use `pg-here` directly from your server startup code and auto-create the app database if missing.

package/bin/pg-here.mjs

@@ -3,6 +3,10 @@
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 import { startPgHere } from "../dist/index.js";
+import {
+  maybePrintLinuxRuntimeHelp,
+  startPgHereWithLibxml2Compat,
+} from "../scripts/cli-error-help.mjs";
 
 const argv = await yargs(hideBin(process.argv))
   .version(false)
@@ -31,14 +35,25 @@ const argv = await yargs(hideBin(process.argv))
   })
   .parse();
 
-const pg = await startPgHere({
-  projectDir: process.cwd(),
-  port: argv.port,
-  username: argv.username,
-  password: argv.password,
-  database: argv.database,
-  postgresVersion: argv["pg-version"],
-});
+let pg;
+const startInstance = () =>
+  startPgHere({
+    projectDir: process.cwd(),
+    port: argv.port,
+    username: argv.username,
+    password: argv.password,
+    database: argv.database,
+    postgresVersion: argv["pg-version"],
+  });
+
+try {
+  pg = await startPgHereWithLibxml2Compat(startInstance, process.cwd());
+} catch (error) {
+  if (process.platform === "linux") {
+    maybePrintLinuxRuntimeHelp(error);
+  }
+  throw error;
+}
 
 console.log(pg.databaseConnectionString);
 setInterval(() => {}, 1 << 30);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pg-here",
-  "version": "0.1.4",
+  "version": "0.1.8",
   "description": "Per-project embedded PostgreSQL with programmatic startup and auto DB creation.",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,6 +19,7 @@
     "index.ts",
     "bin/pg-here.mjs",
     "scripts/pg-dev.mjs",
+    "scripts/cli-error-help.mjs",
     "README.md"
   ],
   "private": false,

package/scripts/cli-error-help.mjs

@@ -0,0 +1,261 @@
+import { spawnSync } from "node:child_process";
+import { accessSync, existsSync, lstatSync, mkdirSync, readlinkSync, rmSync, symlinkSync, F_OK } from "node:fs";
+import { join } from "node:path";
+
+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",
+];
+
+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])];
+
+  if (missingLibs.length === 0) {
+    return;
+  }
+
+  console.error();
+  console.error("PostgreSQL startup failed due to missing Linux runtime dependencies.");
+  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 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.8");
+  }
+  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 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();
+  }
+}
+
+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]);
+  return matches.filter((value) => value.toLowerCase().includes("so"));
+}
+
+function extractMissingLibrariesFromBinaryPath(message) {
+  const pathMatch = message.match(/(\/[^\s"]*\/bin\/postgres)/);
+  if (!pathMatch) {
+    return [];
+  }
+
+  const binaryPath = pathMatch[1];
+  const result = spawnSync("ldd", [binaryPath], { encoding: "utf8" });
+  const output = `${result.stdout ?? ""} ${result.stderr ?? ""}`;
+  if (!output) {
+    return [];
+  }
+
+  return [...output.matchAll(/([^\s]+)\s+=>\s+not found/g)].map(
+    (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,6 +1,10 @@
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 import { startPgHere } from "../index.ts";
+import {
+  maybePrintLinuxRuntimeHelp,
+  startPgHereWithLibxml2Compat,
+} from "./cli-error-help.mjs";
 
 const argv = await yargs(hideBin(process.argv))
   .version(false)
@@ -29,14 +33,25 @@ const argv = await yargs(hideBin(process.argv))
   })
   .parse();
 
-const pg = await startPgHere({
-  projectDir: process.cwd(),
-  port: argv.port,
-  username: argv.username,
-  password: argv.password,
-  database: argv.database,
-  postgresVersion: argv["pg-version"],
-});
+let pg;
+const startInstance = () =>
+  startPgHere({
+    projectDir: process.cwd(),
+    port: argv.port,
+    username: argv.username,
+    password: argv.password,
+    database: argv.database,
+    postgresVersion: argv["pg-version"],
+  });
+
+try {
+  pg = await startPgHereWithLibxml2Compat(startInstance, process.cwd());
+} catch (error) {
+  if (process.platform === "linux") {
+    maybePrintLinuxRuntimeHelp(error);
+  }
+  throw error;
+}
 
 // print connection string for tooling
 console.log(pg.databaseConnectionString);