pg-here 0.1.0 → 0.1.2

package/README.md

@@ -47,6 +47,11 @@ 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
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pg-here",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Per-project embedded PostgreSQL with programmatic startup and auto DB creation.",
   "type": "module",
   "main": "./dist/index.js",
@@ -49,6 +49,7 @@
   },
   "devDependencies": {
     "@types/bun": "latest",
+    "@types/pg": "^8.15.6",
     "typescript": "^5.9.2"
   },
   "dependencies": {