pg-here 0.1.0 → 0.1.3

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 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 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.
@@ -47,21 +73,26 @@ await pgHere.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.
 
 ### CLI Options
 
 ```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/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { PostgresInstance } from "pg-embedded";
+export type PgHereShutdownSignal = "SIGINT" | "SIGTERM" | "SIGHUP";
 export interface PgHereOptions {
     projectDir?: string;
     dataDir?: string;
@@ -11,16 +12,25 @@ export interface PgHereOptions {
     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: () => Promise<void>;
+    stop: (options?: StopPgHereOptions) => Promise<void>;
+    cleanup: () => Promise<void>;
     ensureDatabase: (databaseName?: string) => Promise<boolean>;
+    removeShutdownHooks: () => void;
 }
 export declare function createPgHereInstance(options?: PgHereOptions): PostgresInstance;
 export declare function ensurePgHereDatabase(instance: PostgresInstance, databaseName: string): Promise<boolean>;
-export declare function stopPgHere(instance: PostgresInstance): Promise<void>;
+export declare function stopPgHere(instance: PostgresInstance, options?: StopPgHereOptions): Promise<void>;
 export declare function startPgHere(options?: PgHereOptions): Promise<PgHereHandle>;

package/dist/index.js

@@ -1,9 +1,12 @@
 import { join, resolve } from "node:path";
 import { PostgresInstance } from "pg-embedded";
+import { Client } from "pg";
 const DEFAULT_USERNAME = "postgres";
 const DEFAULT_PASSWORD = "postgres";
 const DEFAULT_PORT = 55432;
 const DEFAULT_DATABASE = "postgres";
+const DEFAULT_SHUTDOWN_SIGNALS = ["SIGINT", "SIGTERM"];
+const PG_STAT_STATEMENTS_EXTENSION = "pg_stat_statements";
 export function createPgHereInstance(options = {}) {
     const root = resolve(options.projectDir ?? process.cwd());
     const dataDir = resolve(options.dataDir ?? join(root, "pg_local", "data"));
@@ -30,18 +33,20 @@ export async function ensurePgHereDatabase(instance, databaseName) {
     await instance.createDatabase(databaseName);
     return true;
 }
-export async function stopPgHere(instance) {
+export async function stopPgHere(instance, options = {}) {
     try {
         await instance.stop();
     }
     catch {
         // no-op
     }
-    try {
-        await instance.cleanup();
-    }
-    catch {
-        // no-op
+    if (options.cleanup) {
+        try {
+            await instance.cleanup();
+        }
+        catch {
+            // no-op
+        }
     }
 }
 export async function startPgHere(options = {}) {
@@ -52,15 +57,33 @@ export async function startPgHere(options = {}) {
     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 = {}) => {
+        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: async () => stopPgHere(instance),
+        stop: stopHandle,
+        cleanup: async () => stopHandle({ cleanup: true }),
         ensureDatabase: async (databaseName = database) => ensurePgHereDatabase(instance, databaseName),
+        removeShutdownHooks,
     };
 }
 function setConnectionDatabase(connectionString, database) {
@@ -68,3 +91,82 @@ function setConnectionDatabase(connectionString, database) {
     connectionUrl.pathname = `/${database}`;
     return connectionUrl.toString();
 }
+async function ensurePgStatStatements(instance, database) {
+    await ensureSharedPreloadLibrary(instance, PG_STAT_STATEMENTS_EXTENSION);
+    await ensureExtension(instance, database, PG_STAT_STATEMENTS_EXTENSION);
+}
+async function ensureSharedPreloadLibrary(instance, libraryName) {
+    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, database, extensionName) {
+    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) {
+    if (!value) {
+        return [];
+    }
+    return value
+        .split(",")
+        .map((library) => library.trim())
+        .filter(Boolean);
+}
+function quoteIdentifier(identifier) {
+    return `"${identifier.replaceAll('"', '""')}"`;
+}
+function escapeSqlLiteral(value) {
+    return value.replaceAll("'", "''");
+}
+function registerPgHereShutdownHandlers({ stop, signals, }) {
+    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/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.0",
+  "version": "0.1.3",
   "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"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -13,6 +16,8 @@
   },
   "files": [
     "dist",
+    "index.ts",
+    "scripts/pg-dev.mjs",
     "README.md"
   ],
   "private": false,
@@ -49,6 +54,7 @@
   },
   "devDependencies": {
     "@types/bun": "latest",
+    "@types/pg": "^8.15.6",
     "typescript": "^5.9.2"
   },
   "dependencies": {

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);