pg-here 0.1.2 → 0.1.4

package/README.md

@@ -23,6 +23,32 @@ 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:
+
+```bash
+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 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.
+
+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
+```
+
 ### Programmatic usage
 
 Use `pg-here` directly from your server startup code and auto-create the app database if missing.
@@ -57,16 +83,16 @@ Set `enablePgStatStatements: false` to opt out.
 
 ```bash
 # Custom credentials
-bun run db:up --username myuser --password mypass
+bun run db:up --username postgres --password postgres
 
 # Short flags
-bun run db:up -u myuser -p mypass
+bun run db:up -u postgres -p postgres
 
 # Custom port
 bun run db:up --port 55433
 
 # All together
-bun run db:up -u myuser -p mypass --port 55433
+bun run db:up -u postgres -p postgres --database postgres --port 55433
 
 # Pin postgres version
 bun run db:up --pg-version 18.0.0

package/bin/pg-here.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import { startPgHere } from "../dist/index.js";
+
+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();
+
+const pg = await startPgHere({
+  projectDir: process.cwd(),
+  port: argv.port,
+  username: argv.username,
+  password: argv.password,
+  database: argv.database,
+  postgresVersion: argv["pg-version"],
+});
+
+console.log(pg.databaseConnectionString);
+setInterval(() => {}, 1 << 30);

package/index.ts

@@ -0,0 +1,270 @@
+import { join, resolve } from "node:path";
+import { PostgresInstance } from "pg-embedded";
+import { Client } from "pg";
+
+export type PgHereShutdownSignal = "SIGINT" | "SIGTERM" | "SIGHUP";
+
+export interface PgHereOptions {
+  projectDir?: string;
+  dataDir?: string;
+  installationDir?: string;
+  postgresVersion?: string;
+  version?: string;
+  port?: number;
+  username?: string;
+  password?: string;
+  persistent?: boolean;
+  database?: string;
+  createDatabaseIfMissing?: boolean;
+  registerProcessShutdownHandlers?: boolean;
+  shutdownSignals?: PgHereShutdownSignal[];
+  cleanupOnShutdown?: boolean;
+  enablePgStatStatements?: boolean;
+}
+
+export interface StopPgHereOptions {
+  cleanup?: boolean;
+}
+
+export interface PgHereHandle {
+  instance: PostgresInstance;
+  connectionString: string;
+  databaseConnectionString: string;
+  database: string;
+  stop: (options?: StopPgHereOptions) => Promise<void>;
+  cleanup: () => Promise<void>;
+  ensureDatabase: (databaseName?: string) => Promise<boolean>;
+  removeShutdownHooks: () => void;
+}
+
+const DEFAULT_USERNAME = "postgres";
+const DEFAULT_PASSWORD = "postgres";
+const DEFAULT_PORT = 55432;
+const DEFAULT_DATABASE = "postgres";
+const DEFAULT_SHUTDOWN_SIGNALS: PgHereShutdownSignal[] = ["SIGINT", "SIGTERM"];
+const PG_STAT_STATEMENTS_EXTENSION = "pg_stat_statements";
+
+export function createPgHereInstance(options: PgHereOptions = {}): PostgresInstance {
+  const root = resolve(options.projectDir ?? process.cwd());
+  const dataDir = resolve(options.dataDir ?? join(root, "pg_local", "data"));
+  const installationDir = resolve(
+    options.installationDir ?? join(root, "pg_local", "bin")
+  );
+  const postgresVersion = options.postgresVersion ?? options.version;
+
+  return new PostgresInstance({
+    version: postgresVersion,
+    dataDir,
+    installationDir,
+    port: options.port ?? DEFAULT_PORT,
+    username: options.username ?? DEFAULT_USERNAME,
+    password: options.password ?? DEFAULT_PASSWORD,
+    persistent: options.persistent ?? true,
+  });
+}
+
+export async function ensurePgHereDatabase(
+  instance: PostgresInstance,
+  databaseName: string
+): Promise<boolean> {
+  if (!databaseName || databaseName === DEFAULT_DATABASE) {
+    return false;
+  }
+
+  const exists = await instance.databaseExists(databaseName);
+  if (exists) {
+    return false;
+  }
+
+  await instance.createDatabase(databaseName);
+  return true;
+}
+
+export async function stopPgHere(
+  instance: PostgresInstance,
+  options: StopPgHereOptions = {}
+): Promise<void> {
+  try {
+    await instance.stop();
+  } catch {
+    // no-op
+  }
+
+  if (options.cleanup) {
+    try {
+      await instance.cleanup();
+    } catch {
+      // no-op
+    }
+  }
+}
+
+export async function startPgHere(options: PgHereOptions = {}): Promise<PgHereHandle> {
+  const instance = createPgHereInstance(options);
+  await instance.start();
+
+  const database = options.database ?? DEFAULT_DATABASE;
+  const shouldCreate =
+    options.createDatabaseIfMissing ?? database !== DEFAULT_DATABASE;
+
+  if (shouldCreate) {
+    await ensurePgHereDatabase(instance, database);
+  }
+
+  if (options.enablePgStatStatements ?? true) {
+    await ensurePgStatStatements(instance, database);
+  }
+
+  const defaultCleanupOnShutdown = options.cleanupOnShutdown ?? false;
+  const connectionString = instance.connectionInfo.connectionString;
+  const databaseConnectionString = setConnectionDatabase(connectionString, database);
+  let removeShutdownHooks = () => {};
+
+  const stopHandle = async (stopOptions: StopPgHereOptions = {}) => {
+    removeShutdownHooks();
+    const cleanup = stopOptions.cleanup ?? defaultCleanupOnShutdown;
+    await stopPgHere(instance, { cleanup });
+  };
+
+  if (options.registerProcessShutdownHandlers ?? true) {
+    removeShutdownHooks = registerPgHereShutdownHandlers({
+      stop: async () => stopHandle({ cleanup: defaultCleanupOnShutdown }),
+      signals: options.shutdownSignals ?? DEFAULT_SHUTDOWN_SIGNALS,
+    });
+  }
+
+  return {
+    instance,
+    connectionString,
+    databaseConnectionString,
+    database,
+    stop: stopHandle,
+    cleanup: async () => stopHandle({ cleanup: true }),
+    ensureDatabase: async (databaseName = database) =>
+      ensurePgHereDatabase(instance, databaseName),
+    removeShutdownHooks,
+  };
+}
+
+function setConnectionDatabase(connectionString: string, database: string): string {
+  const connectionUrl = new URL(connectionString);
+  connectionUrl.pathname = `/${database}`;
+  return connectionUrl.toString();
+}
+
+async function ensurePgStatStatements(
+  instance: PostgresInstance,
+  database: string
+): Promise<void> {
+  await ensureSharedPreloadLibrary(instance, PG_STAT_STATEMENTS_EXTENSION);
+  await ensureExtension(instance, database, PG_STAT_STATEMENTS_EXTENSION);
+}
+
+async function ensureSharedPreloadLibrary(
+  instance: PostgresInstance,
+  libraryName: string
+): Promise<boolean> {
+  const adminConnection = setConnectionDatabase(
+    instance.connectionInfo.connectionString,
+    DEFAULT_DATABASE
+  );
+  const client = new Client({ connectionString: adminConnection });
+
+  try {
+    await client.connect();
+    const result = await client.query("show shared_preload_libraries");
+    const rawLibraries = String(result.rows[0]?.shared_preload_libraries ?? "");
+    const libraries = parsePreloadLibraries(rawLibraries);
+
+    if (libraries.includes(libraryName)) {
+      return false;
+    }
+
+    const nextLibraries = [...libraries, libraryName];
+    const librariesValue = escapeSqlLiteral(nextLibraries.join(","));
+    await client.query(
+      `ALTER SYSTEM SET shared_preload_libraries = '${librariesValue}'`
+    );
+  } finally {
+    await client.end().catch(() => {});
+  }
+
+  await instance.stop().catch(() => {});
+  await instance.start();
+  return true;
+}
+
+async function ensureExtension(
+  instance: PostgresInstance,
+  database: string,
+  extensionName: string
+): Promise<void> {
+  const connectionString = setConnectionDatabase(
+    instance.connectionInfo.connectionString,
+    database
+  );
+  const client = new Client({ connectionString });
+
+  try {
+    await client.connect();
+    await client.query(`CREATE EXTENSION IF NOT EXISTS ${quoteIdentifier(extensionName)}`);
+  } finally {
+    await client.end().catch(() => {});
+  }
+}
+
+function parsePreloadLibraries(value: string): string[] {
+  if (!value) {
+    return [];
+  }
+
+  return value
+    .split(",")
+    .map((library) => library.trim())
+    .filter(Boolean);
+}
+
+function quoteIdentifier(identifier: string): string {
+  return `"${identifier.replaceAll('"', '""')}"`;
+}
+
+function escapeSqlLiteral(value: string): string {
+  return value.replaceAll("'", "''");
+}
+
+function registerPgHereShutdownHandlers({
+  stop,
+  signals,
+}: {
+  stop: () => Promise<void>;
+  signals: PgHereShutdownSignal[];
+}): () => void {
+  let isStopping = false;
+  const uniqueSignals = [...new Set(signals)];
+
+  const handlers = uniqueSignals.map((signal) => {
+    const handler = () => {
+      if (isStopping) {
+        return;
+      }
+      isStopping = true;
+
+      void (async () => {
+        try {
+          await stop();
+        } finally {
+          process.exit(0);
+        }
+      })();
+    };
+
+    process.on(signal, handler);
+    return { signal, handler };
+  });
+
+  return () => {
+    for (const { signal, handler } of handlers) {
+      process.off(signal, handler);
+    }
+  };
+}

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "pg-here",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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": "bin/pg-here.mjs"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -13,6 +16,9 @@
   },
   "files": [
     "dist",
+    "index.ts",
+    "bin/pg-here.mjs",
+    "scripts/pg-dev.mjs",
     "README.md"
   ],
   "private": false,

package/scripts/pg-dev.mjs

@@ -0,0 +1,45 @@
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import { startPgHere } from "../index.ts";
+
+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();
+
+const pg = await startPgHere({
+  projectDir: process.cwd(),
+  port: argv.port,
+  username: argv.username,
+  password: argv.password,
+  database: argv.database,
+  postgresVersion: argv["pg-version"],
+});
+
+// print connection string for tooling
+console.log(pg.databaseConnectionString);
+
+// keep this process alive; Ctrl-C stops postgres
+setInterval(() => {}, 1 << 30);