pgsql-client 1.5.1 → 2.0.0

package/ephemeral.d.ts

@@ -0,0 +1,85 @@
+import { PgConfig } from 'pg-env';
+import { DbAdmin } from './admin';
+/**
+ * Options for creating an ephemeral database
+ */
+export interface EphemeralDbOptions {
+    /**
+     * Database name prefix (default: 'ephemeral_')
+     */
+    prefix?: string;
+    /**
+     * PostgreSQL extensions to install after creation
+     */
+    extensions?: string[];
+    /**
+     * Base PostgreSQL configuration (host, port, user, password)
+     * If not provided, uses environment variables via pg-env
+     */
+    baseConfig?: Partial<PgConfig>;
+    /**
+     * Enable verbose logging
+     */
+    verbose?: boolean;
+}
+/**
+ * Options for tearing down an ephemeral database
+ */
+export interface TeardownOptions {
+    /**
+     * If true, keeps the database instead of dropping it (useful for debugging)
+     */
+    keepDb?: boolean;
+}
+/**
+ * Result of creating an ephemeral database
+ */
+export interface EphemeralDbResult {
+    /**
+     * The name of the created database
+     */
+    name: string;
+    /**
+     * Full PostgreSQL configuration for connecting to the ephemeral database
+     */
+    config: PgConfig;
+    /**
+     * Database admin instance for additional operations
+     */
+    admin: DbAdmin;
+    /**
+     * Teardown function to clean up the ephemeral database
+     * Call this when done to drop the database (unless keepDb is true)
+     */
+    teardown: (opts?: TeardownOptions) => void;
+}
+/**
+ * Create an ephemeral (temporary) PostgreSQL database
+ *
+ * Creates a new database with a unique UUID-based name. The database
+ * can be used for testing, code generation, or other temporary purposes.
+ *
+ * @example
+ * ```typescript
+ * const { config, teardown } = createEphemeralDb();
+ *
+ * // Use the database...
+ * const pool = new Pool(config);
+ * await pool.query('SELECT 1');
+ * await pool.end();
+ *
+ * // Clean up
+ * teardown();
+ *
+ * // Or keep for debugging
+ * teardown({ keepDb: true });
+ * ```
+ */
+export declare function createEphemeralDb(options?: EphemeralDbOptions): EphemeralDbResult;
+/**
+ * Create an ephemeral database asynchronously
+ *
+ * Same as createEphemeralDb but returns a Promise for consistency
+ * with async workflows.
+ */
+export declare function createEphemeralDbAsync(options?: EphemeralDbOptions): Promise<EphemeralDbResult>;

package/ephemeral.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEphemeralDb = createEphemeralDb;
+exports.createEphemeralDbAsync = createEphemeralDbAsync;
+/**
+ * Ephemeral Database Utilities
+ *
+ * Provides utilities for creating and managing temporary PostgreSQL databases
+ * for testing, code generation, and other ephemeral use cases.
+ */
+const crypto_1 = require("crypto");
+const pg_env_1 = require("pg-env");
+const admin_1 = require("./admin");
+/**
+ * Create an ephemeral (temporary) PostgreSQL database
+ *
+ * Creates a new database with a unique UUID-based name. The database
+ * can be used for testing, code generation, or other temporary purposes.
+ *
+ * @example
+ * ```typescript
+ * const { config, teardown } = createEphemeralDb();
+ *
+ * // Use the database...
+ * const pool = new Pool(config);
+ * await pool.query('SELECT 1');
+ * await pool.end();
+ *
+ * // Clean up
+ * teardown();
+ *
+ * // Or keep for debugging
+ * teardown({ keepDb: true });
+ * ```
+ */
+function createEphemeralDb(options = {}) {
+    const { prefix = 'ephemeral_', extensions = [], baseConfig = {}, verbose = false, } = options;
+    // Generate unique database name
+    const dbName = `${prefix}${(0, crypto_1.randomUUID)().replace(/-/g, '_')}`;
+    // Get base config from environment, merged with any provided config
+    const config = (0, pg_env_1.getPgEnvOptions)({
+        ...baseConfig,
+        database: dbName,
+    });
+    // Create admin instance for database operations
+    const admin = new admin_1.DbAdmin(config, verbose);
+    // Create the database
+    admin.create(dbName);
+    // Install extensions if specified
+    if (extensions.length > 0) {
+        admin.installExtensions(extensions, dbName);
+    }
+    // Create teardown function
+    const teardown = (opts = {}) => {
+        const { keepDb = false } = opts;
+        if (keepDb) {
+            if (verbose) {
+                console.log(`[ephemeral-db] Keeping database: ${dbName}`);
+            }
+            return;
+        }
+        try {
+            admin.drop(dbName);
+            if (verbose) {
+                console.log(`[ephemeral-db] Dropped database: ${dbName}`);
+            }
+        }
+        catch (err) {
+            if (verbose) {
+                console.error(`[ephemeral-db] Failed to drop database ${dbName}:`, err);
+            }
+        }
+    };
+    return {
+        name: dbName,
+        config,
+        admin,
+        teardown,
+    };
+}
+/**
+ * Create an ephemeral database asynchronously
+ *
+ * Same as createEphemeralDb but returns a Promise for consistency
+ * with async workflows.
+ */
+async function createEphemeralDbAsync(options = {}) {
+    return createEphemeralDb(options);
+}

package/esm/ephemeral.js

@@ -0,0 +1,85 @@
+/**
+ * Ephemeral Database Utilities
+ *
+ * Provides utilities for creating and managing temporary PostgreSQL databases
+ * for testing, code generation, and other ephemeral use cases.
+ */
+import { randomUUID } from 'crypto';
+import { getPgEnvOptions } from 'pg-env';
+import { DbAdmin } from './admin';
+/**
+ * Create an ephemeral (temporary) PostgreSQL database
+ *
+ * Creates a new database with a unique UUID-based name. The database
+ * can be used for testing, code generation, or other temporary purposes.
+ *
+ * @example
+ * ```typescript
+ * const { config, teardown } = createEphemeralDb();
+ *
+ * // Use the database...
+ * const pool = new Pool(config);
+ * await pool.query('SELECT 1');
+ * await pool.end();
+ *
+ * // Clean up
+ * teardown();
+ *
+ * // Or keep for debugging
+ * teardown({ keepDb: true });
+ * ```
+ */
+export function createEphemeralDb(options = {}) {
+    const { prefix = 'ephemeral_', extensions = [], baseConfig = {}, verbose = false, } = options;
+    // Generate unique database name
+    const dbName = `${prefix}${randomUUID().replace(/-/g, '_')}`;
+    // Get base config from environment, merged with any provided config
+    const config = getPgEnvOptions({
+        ...baseConfig,
+        database: dbName,
+    });
+    // Create admin instance for database operations
+    const admin = new DbAdmin(config, verbose);
+    // Create the database
+    admin.create(dbName);
+    // Install extensions if specified
+    if (extensions.length > 0) {
+        admin.installExtensions(extensions, dbName);
+    }
+    // Create teardown function
+    const teardown = (opts = {}) => {
+        const { keepDb = false } = opts;
+        if (keepDb) {
+            if (verbose) {
+                console.log(`[ephemeral-db] Keeping database: ${dbName}`);
+            }
+            return;
+        }
+        try {
+            admin.drop(dbName);
+            if (verbose) {
+                console.log(`[ephemeral-db] Dropped database: ${dbName}`);
+            }
+        }
+        catch (err) {
+            if (verbose) {
+                console.error(`[ephemeral-db] Failed to drop database ${dbName}:`, err);
+            }
+        }
+    };
+    return {
+        name: dbName,
+        config,
+        admin,
+        teardown,
+    };
+}
+/**
+ * Create an ephemeral database asynchronously
+ *
+ * Same as createEphemeralDb but returns a Promise for consistency
+ * with async workflows.
+ */
+export async function createEphemeralDbAsync(options = {}) {
+    return createEphemeralDb(options);
+}

package/esm/index.js

@@ -1,5 +1,6 @@
 export * from './admin';
 export * from './client';
 export * from './context-utils';
+export * from './ephemeral';
 export * from './roles';
 export { streamSql } from './stream';

package/index.d.ts

@@ -1,5 +1,6 @@
 export * from './admin';
 export * from './client';
 export * from './context-utils';
+export * from './ephemeral';
 export * from './roles';
 export { streamSql } from './stream';

package/index.js

@@ -18,6 +18,7 @@ exports.streamSql = void 0;
 __exportStar(require("./admin"), exports);
 __exportStar(require("./client"), exports);
 __exportStar(require("./context-utils"), exports);
+__exportStar(require("./ephemeral"), exports);
 __exportStar(require("./roles"), exports);
 var stream_1 = require("./stream");
 Object.defineProperty(exports, "streamSql", { enumerable: true, get: function () { return stream_1.streamSql; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgsql-client",
-  "version": "1.5.1",
+  "version": "2.0.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "PostgreSQL client utilities with query helpers, RLS context management, and database administration",
   "main": "index.js",
@@ -45,11 +45,11 @@
     "makage": "^0.1.10"
   },
   "dependencies": {
-    "@pgpmjs/core": "^4.17.1",
-    "@pgpmjs/logger": "^1.5.0",
+    "@pgpmjs/core": "^5.0.0",
+    "@pgpmjs/logger": "^2.0.0",
     "@pgpmjs/types": "^2.15.0",
     "pg": "^8.17.1",
     "pg-env": "^1.3.0"
   },
-  "gitHead": "39b5c59b01b8ce391dc14daf5a9430ca0ff67574"
+  "gitHead": "390f4dd57fc158554518ec454bf2a4856d550552"
 }