pg-here 0.1.8 → 0.1.9

package/README.md

@@ -1,366 +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 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:
+Default output:
 
-```bash
-bunx pg-here
+```text
+Launching PostgreSQL 18.0.0 into new pg_local/
+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.
-
-`bunx pg-here` uses these defaults if you pass nothing:
-- `username=postgres`
-- `password=postgres`
-- `database=postgres`
-- `port=55432`
-
-All args are optional.
+If a data folder already exists:
 
-Pass CLI flags just like the local script when you want to override defaults:
-
-```bash
-bunx pg-here --username postgres --password postgres --database my_app --port 55432
+```text
+Reusing existing pg_local/data/ with PostgreSQL 18.0.0
+psql postgresql://postgres:postgres@localhost:55432/postgres
 ```
 
-#### 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:
+If the cached folder version differs:
 
-```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
+```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
 ```
 
-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.
+The process stays alive until you stop it.  
+Ctrl+C → exits and stops Postgres.
 
-```bash
-cat /etc/os-release
-apt-cache search '^libxml2$'
-```
+## Defaults (all args optional)
 
-and if that returns nothing, fix apt sources for your distro/arch first, or use a base image that includes PostgreSQL runtime packages.
+`bunx pg-here`
 
-Important ABI note:
+- `username = postgres`
+- `password = postgres`
+- `database = postgres`
+- `port = 55432`
+- `pg-version` = auto
 
-- 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:
+## Custom run
 
 ```bash
-rm -rf pg_local
-bunx pg-here@0.1.8
+bunx pg-here --username me --password secret --database my_app --port 55433 --pg-version 17.0.0
 ```
 
-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):
+You can also run locally in this repo:
 
 ```bash
-sudo ln -sfn /usr/lib/x86_64-linux-gnu/libxml2.so.16 /usr/local/lib/libxml2.so.2
-sudo ldconfig
+bun run db:up
 ```
 
-### 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
-```
-
-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
+bunx pg-here@0.1.9
 ```
-
-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

@@ -5,6 +5,8 @@ import { hideBin } from "yargs/helpers";
 import { startPgHere } from "../dist/index.js";
 import {
   maybePrintLinuxRuntimeHelp,
+  getPreStartPgHereState,
+  printPgHereStartupInfo,
   startPgHereWithLibxml2Compat,
 } from "../scripts/cli-error-help.mjs";
 
@@ -36,6 +38,7 @@ const argv = await yargs(hideBin(process.argv))
   .parse();
 
 let pg;
+const preStartState = getPreStartPgHereState(process.cwd());
 const startInstance = () =>
   startPgHere({
     projectDir: process.cwd(),
@@ -55,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.8",
+  "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,5 +1,15 @@
 import { spawnSync } from "node:child_process";
-import { accessSync, existsSync, lstatSync, mkdirSync, readlinkSync, rmSync, symlinkSync, F_OK } from "node:fs";
+import {
+  accessSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readlinkSync,
+  readdirSync,
+  rmSync,
+  symlinkSync,
+  F_OK,
+} from "node:fs";
 import { join } from "node:path";
 
 const LIBXML2_SONAME = "libxml2.so.2";
@@ -16,6 +26,12 @@ const LIB_PATHS = [
   "/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);
@@ -54,7 +70,7 @@ export function maybePrintLinuxRuntimeHelp(error) {
   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("    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(", ")}`
@@ -94,6 +110,91 @@ export function hasLibxml2CompatibilityNeed(error) {
   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}/`;
+
+  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();
@@ -111,6 +212,25 @@ export async function startPgHereWithLibxml2Compat(start, workingDir) {
   }
 }
 
+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;

package/scripts/pg-dev.mjs

@@ -3,6 +3,8 @@ import { hideBin } from "yargs/helpers";
 import { startPgHere } from "../index.ts";
 import {
   maybePrintLinuxRuntimeHelp,
+  getPreStartPgHereState,
+  printPgHereStartupInfo,
   startPgHereWithLibxml2Compat,
 } from "./cli-error-help.mjs";
 
@@ -34,6 +36,7 @@ const argv = await yargs(hideBin(process.argv))
   .parse();
 
 let pg;
+const preStartState = getPreStartPgHereState(process.cwd());
 const startInstance = () =>
   startPgHere({
     projectDir: process.cwd(),
@@ -53,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);