pg-here 0.1.3 → 0.1.5

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 currently fails with `could not determine executable to run for package`, you’re using a release that was published before the CLI binary was exposed. It will work after the next publish.
+This is the single command you want from any directory.
+
+If it still resolves an older release, the package `latest` dist-tag is behind:
+
+To force that version and bypass a stale cache:
+
+```bash
+bunx pg-here@0.1.5
+```
+
+If maintainers want plain `bunx pg-here` to work for everyone, run once:
+
+```bash
+npm dist-tag add pg-here@0.1.5 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,27 @@ 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.
+
 ### Programmatic usage
 
 Use `pg-here` directly from your server startup code and auto-create the app database if missing.

package/bin/pg-here.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import { startPgHere } from "../dist/index.js";
+import { maybePrintLinuxRuntimeHelp } from "../scripts/cli-error-help.mjs";
+
+const argv = await yargs(hideBin(process.argv))
+  .version(false)
+  .option("username", {
+    alias: "u",
+    default: "postgres",
+    describe: "PostgreSQL username",
+  })
+  .option("password", {
+    alias: "p",
+    default: "postgres",
+    describe: "PostgreSQL password",
+  })
+  .option("port", {
+    default: 55432,
+    describe: "PostgreSQL port",
+  })
+  .option("database", {
+    alias: "d",
+    default: "postgres",
+    describe: "Database to use (created automatically if missing)",
+  })
+  .option("pg-version", {
+    default: process.env.PG_VERSION,
+    describe: "PostgreSQL version (e.g. 18.0.0 or >=17.0)",
+  })
+  .parse();
+
+let pg;
+try {
+  pg = await startPgHere({
+    projectDir: process.cwd(),
+    port: argv.port,
+    username: argv.username,
+    password: argv.password,
+    database: argv.database,
+    postgresVersion: argv["pg-version"],
+  });
+} catch (error) {
+  if (process.platform === "linux") {
+    maybePrintLinuxRuntimeHelp(error);
+  }
+  throw error;
+}
+
+console.log(pg.databaseConnectionString);
+setInterval(() => {}, 1 << 30);

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "pg-here",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Per-project embedded PostgreSQL with programmatic startup and auto DB creation.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "pg-here": "scripts/pg-dev.mjs"
+    "pg-here": "bin/pg-here.mjs"
   },
   "exports": {
     ".": {
@@ -17,7 +17,9 @@
   "files": [
     "dist",
     "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,57 @@
+import { spawnSync } from "node:child_process";
+
+const LIBXML_LIBRARY = /libxml2\.so\.2/;
+
+export function maybePrintLinuxRuntimeHelp(error) {
+  const message = String(error?.message ?? error);
+  const missingLibsFromError = extractMissingLibrariesFromMessage(message);
+  const missingLibsFromBinary = extractMissingLibrariesFromBinaryPath(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");
+  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(
+      ", "
+    )}`
+  );
+
+  if (LIBXML_LIBRARY.test(message)) {
+    console.error("Hint: this project does not ship all optional shared objects in every Linux image.");
+  }
+}
+
+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]
+  );
+}

package/scripts/pg-dev.mjs

@@ -1,6 +1,7 @@
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 import { startPgHere } from "../index.ts";
+import { maybePrintLinuxRuntimeHelp } from "./cli-error-help.mjs";
 
 const argv = await yargs(hideBin(process.argv))
   .version(false)
@@ -29,14 +30,22 @@ 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;
+try {
+  pg = await startPgHere({
+    projectDir: process.cwd(),
+    port: argv.port,
+    username: argv.username,
+    password: argv.password,
+    database: argv.database,
+    postgresVersion: argv["pg-version"],
+  });
+} catch (error) {
+  if (process.platform === "linux") {
+    maybePrintLinuxRuntimeHelp(error);
+  }
+  throw error;
+}
 
 // print connection string for tooling
 console.log(pg.databaseConnectionString);