@pipeline-builder/pipeline-data 3.1.0

package/lib/database/index.d.ts

@@ -0,0 +1,3 @@
+export * from './drizzle-schema';
+export * from './postgres-connection';
+export * from './retry-strategy';

package/lib/database/index.js

@@ -0,0 +1,22 @@
+"use strict";
+// Copyright 2026 Pipeline Builder Contributors
+// SPDX-License-Identifier: Apache-2.0
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./drizzle-schema"), exports);
+__exportStar(require("./postgres-connection"), exports);
+__exportStar(require("./retry-strategy"), exports);
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvZGF0YWJhc2UvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IjtBQUFBLCtDQUErQztBQUMvQyxzQ0FBc0M7Ozs7Ozs7Ozs7Ozs7Ozs7QUFFdEMsbURBQWlDO0FBQ2pDLHdEQUFzQztBQUN0QyxtREFBaUMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBDb3B5cmlnaHQgMjAyNiBQaXBlbGluZSBCdWlsZGVyIENvbnRyaWJ1dG9yc1xuLy8gU1BEWC1MaWNlbnNlLUlkZW50aWZpZXI6IEFwYWNoZS0yLjBcblxuZXhwb3J0ICogZnJvbSAnLi9kcml6emxlLXNjaGVtYSc7XG5leHBvcnQgKiBmcm9tICcuL3Bvc3RncmVzLWNvbm5lY3Rpb24nO1xuZXhwb3J0ICogZnJvbSAnLi9yZXRyeS1zdHJhdGVneSc7XG4iXX0=

package/lib/database/postgres-connection.d.ts

@@ -0,0 +1,232 @@
+import { drizzle } from 'drizzle-orm/node-postgres';
+import { Pool, PoolClient } from 'pg';
+/**
+ * Database connection statistics for monitoring
+ */
+export interface ConnectionStats {
+    totalCount: number;
+    idleCount: number;
+    waitingCount: number;
+}
+/**
+ * Options for configuring the database connection
+ */
+export interface ConnectionOptions {
+    /** Whether to enable connection logging */
+    enableLogging?: boolean;
+    /** Whether to automatically retry failed connections */
+    enableAutoRetry?: boolean;
+    /** Maximum number of connection retry attempts */
+    maxRetries?: number;
+    /** Delay between retry attempts in milliseconds */
+    retryDelay?: number;
+    /** SSL configuration */
+    ssl?: boolean | {
+        rejectUnauthorized: boolean;
+    };
+}
+/**
+ * Singleton database connection class.
+ * Manages PostgreSQL connection pooling and Drizzle ORM instance.
+ *
+ * Features:
+ * - Singleton pattern for single connection pool
+ * - Automatic connection retry with backoff
+ * - Connection health monitoring
+ * - Graceful shutdown handling
+ * - Comprehensive error handling
+ * - Connection statistics tracking
+ *
+ * @example
+ * ```typescript
+ * import { Connection } from './connection';
+ *
+ * const connection = Connection.getInstance();
+ * const plugins = await connection.db.select().from(schema.plugin);
+ *
+ * // During shutdown
+ * await connection.close();
+ * ```
+ */
+export declare class Connection {
+    private static instance;
+    /**
+     * Drizzle ORM database instance with schema
+     */
+    readonly db: ReturnType<typeof drizzle>;
+    private readonly pool;
+    private readonly options;
+    private readonly retryStrategy;
+    private isShuttingDown;
+    /**
+     * Private constructor to enforce singleton pattern.
+     * Initializes PostgreSQL connection pool and Drizzle ORM instance.
+     *
+     * @param options - Optional configuration for the connection
+     * @throws {Error} If database initialization fails after all retries
+     */
+    private constructor();
+    /**
+     * Gets the singleton instance of the Connection class.
+     * Creates a new instance if one doesn't exist.
+     *
+     * @param options - Optional configuration (only used on first call)
+     * @returns The singleton Connection instance
+     */
+    static getInstance(options?: ConnectionOptions): Connection;
+    /**
+     * Resets the singleton instance.
+     * Useful for testing or reconfiguring the connection.
+     *
+     * @param closeExisting - Whether to close existing connection before reset
+     */
+    static reset(closeExisting?: boolean): Promise<void>;
+    /**
+     * Tests the database connection
+     *
+     * @returns Promise that resolves to true if connection is healthy
+     */
+    testConnection(): Promise<boolean>;
+    /**
+     * Gets connection pool statistics
+     *
+     * @returns Current connection pool statistics
+     */
+    getStats(): ConnectionStats;
+    /**
+     * Executes a database transaction
+     *
+     * @param callback - Function to execute within the transaction
+     * @returns Result of the transaction
+     *
+     * @example
+     * ```typescript
+     * const result = await connection.transaction(async (tx) => {
+     *   await tx.insert(schema.plugin).values({ ... });
+     *   await tx.insert(schema.metadata).values({ ... });
+     *   return { success: true };
+     * });
+     * ```
+     */
+    transaction<T>(callback: Parameters<typeof this.db.transaction>[0], timeoutMs?: number): Promise<T>;
+    /**
+     * Acquires a client from the pool for manual query execution
+     * Remember to release the client when done
+     *
+     * @returns PostgreSQL client from the pool
+     *
+     * @example
+     * ```typescript
+     * const client = await connection.getClient();
+     * try {
+     *   await client.query('BEGIN');
+     *   await client.query('INSERT INTO ...');
+     *   await client.query('COMMIT');
+     * } finally {
+     *   client.release();
+     * }
+     * ```
+     */
+    getClient(): Promise<PoolClient>;
+    /**
+     * Closes the database connection pool gracefully.
+     * Should be called during application shutdown.
+     *
+     * @param timeout - Maximum time to wait for connections to close (ms)
+     * @returns Promise that resolves when pool is closed
+     */
+    close(timeout?: number): Promise<void>;
+    /**
+     * Checks if the connection is shutting down
+     *
+     * @returns true if connection is in shutdown state
+     */
+    isClosing(): boolean;
+    /**
+     * Sets up event handlers for the connection pool
+     */
+    private setupEventHandlers;
+    /**
+     * Logs connection configuration (sanitized)
+     */
+    private logConnectionConfig;
+}
+/**
+ * Proxy-based lazy database instance
+ * The actual connection is only created when first accessed
+ *
+ * @example
+ * ```typescript
+ * import { db } from './connection';
+ *
+ * // Connection is created here on first use, not on import
+ * const plugins = await db.select().from(schema.plugin);
+ * ```
+ */
+export declare const db: import("drizzle-orm/node-postgres").NodePgDatabase<Record<string, unknown>> & {
+    $client: Pool;
+};
+/**
+ * Gets the Connection instance for advanced operations
+ *
+ * @example
+ * ```typescript
+ * import { getConnection } from './connection';
+ *
+ * const connection = getConnection();
+ * const stats = connection.getStats();
+ * console.log(`Active connections: ${stats.totalCount}`);
+ * ```
+ */
+export declare function getConnection(): Connection;
+/**
+ * Closes the database connection
+ * Should be called during application shutdown
+ *
+ * @example
+ * ```typescript
+ * import { closeConnection } from './connection';
+ *
+ * process.on('SIGTERM', async () => {
+ *   await closeConnection();
+ *   process.exit(0);
+ * });
+ * ```
+ */
+export declare function closeConnection(): Promise<void>;
+/**
+ * Tests the database connection
+ *
+ * @returns Promise that resolves to true if connection is healthy
+ *
+ * @example
+ * ```typescript
+ * import { testConnection } from './connection';
+ *
+ * if (await testConnection()) {
+ *   console.log('Database is ready');
+ * } else {
+ *   console.error('Database connection failed');
+ *   process.exit(1);
+ * }
+ * ```
+ */
+export declare function testConnection(): Promise<boolean>;
+/**
+ * Initialize the database connection explicitly
+ * Call this during application startup after environment is configured
+ *
+ * @example
+ * ```typescript
+ * import { initializeDatabase } from './connection';
+ *
+ * async function bootstrap() {
+ *   // Load environment variables first
+ *   dotenv.config();
+ *
+ *   // Then initialize database
+ *   await initializeDatabase();
+ * }
+ * ```
+ */
+export declare function initializeDatabase(): Promise<void>;