@grest-ts/db-postgre 0.0.5

package/src/GGPostgres.ts

@@ -0,0 +1,138 @@
+import {Pool, QueryResult, QueryResultRow} from 'pg';
+import {GGLocator, GGLocatorServiceType} from '@grest-ts/locator';
+import {GGLog} from '@grest-ts/logger';
+import {GGPostgresConnection} from './GGPostgresConnection';
+import type {GGPostgresConfig} from "./GGPostgresConfig";
+
+export class GGPostgres {
+
+    private readonly config: GGPostgresConfig;
+
+    private started = false;
+
+    private pool: Pool | undefined = undefined;
+    private unwatchHost: (() => void) | undefined = undefined;
+    private unwatchUser: (() => void) | undefined = undefined;
+
+    constructor(config: GGPostgresConfig) {
+        this.config = config
+
+        this.unwatchHost = this.config.host.watch(() => this.connect());
+        this.unwatchUser = this.config.user.watch(() => this.connect());
+
+        GGLocator.getScope().setWithLifecycle(this.config.token, this, {
+            type: GGLocatorServiceType.DATABASE,
+            start: () => this.start(),
+            teardown: () => this.teardown(),
+        });
+    }
+
+    private async connect(): Promise<void> {
+        if (!this.started) {
+            return;
+        }
+
+        const config = this.config.host.get();
+        const user = this.config.user.reveal();
+        const connectionsLimit = config.connectionLimit ?? 20;
+
+        const newPool = new Pool({
+            host: config.host ?? "localhost",
+            port: config.port ?? 5432,
+            user: user.username,
+            password: user.password,
+            database: config.database,
+            max: connectionsLimit,
+        });
+
+        try {
+            const client = await newPool.connect();
+            await client.query('SELECT 1');
+            client.release();
+        } catch (err) {
+            GGLog.critical(this, 'Failed to connect to pool! Must resolve immediately, new services will fail to start!', {
+                database: config.database,
+                host: config.host,
+                error: err instanceof Error ? err.message : String(err)
+            });
+            await newPool.end();
+            return;
+        }
+
+        if (this.pool) {
+            this.pool.end().catch(err => {
+                GGLog.warn(this, 'Config change: error closing old pool', {
+                    error: err instanceof Error ? err.message : String(err)
+                });
+            });
+        }
+
+        this.pool = newPool;
+
+        GGLog.info(this, 'Postgres connected!', {database: config.database});
+    }
+
+    private async start(): Promise<void> {
+        this.started = true;
+        await this.connect();
+    }
+
+    private async teardown(): Promise<void> {
+        this.unwatchHost?.();
+        this.unwatchHost = undefined;
+        this.unwatchUser?.();
+        this.unwatchUser = undefined;
+        if (this.pool) {
+            await this.pool.end();
+            this.pool = undefined;
+            GGLog.debug(this, 'disconnected');
+        }
+    }
+
+    private getPool(): Pool {
+        if (!this.pool) {
+            throw new Error(`Postgres '${this.config.name}' not connected. Are you calling this before runtime.start()?`);
+        }
+        return this.pool;
+    }
+
+    public async query<T extends QueryResultRow = QueryResultRow>(sql: string, params?: unknown[]): Promise<T[]> {
+        GGLog.debug(this, 'query', {sql, params});
+        const result: QueryResult<T> = await this.getPool().query<T>(sql, params);
+        GGLog.debug(this, 'query result', {rowCount: result.rowCount});
+        return result.rows;
+    }
+
+    public async execute(sql: string, params?: unknown[]): Promise<QueryResult> {
+        GGLog.debug(this, 'execute', {sql, params});
+        const result = await this.getPool().query(sql, params);
+        GGLog.debug(this, 'execute result', {rowCount: result.rowCount});
+        return result;
+    }
+
+    // ==================== Connection for transactions ====================
+
+    /**
+     * Get a dedicated connection from the pool.
+     * Use this for transactions or when you need multiple queries on the same connection.
+     *
+     * IMPORTANT: Always call release() on the connection when done.
+     */
+    public async getConnection(): Promise<GGPostgresConnection> {
+        const client = await this.getPool().connect();
+        return new GGPostgresConnection(client);
+    }
+
+    /**
+     * Run a callback within a transaction.
+     * Automatically handles connection lifecycle, commits on success, rolls back on failure.
+     */
+    public async runInTransaction<T>(callback: (conn: GGPostgresConnection) => Promise<T>): Promise<T> {
+        const conn = await this.getConnection();
+        try {
+            return await conn.runInTransaction(() => callback(conn));
+        } finally {
+            conn.release();
+        }
+    }
+}

package/src/GGPostgresConfig.ts

@@ -0,0 +1,39 @@
+import {GGResource, GGSecret} from "@grest-ts/config";
+import {GGPostgres} from "./GGPostgres";
+import {IsNumber, IsObject, IsString} from "@grest-ts/schema";
+import {GGLocatorKey} from "@grest-ts/locator";
+
+const IsPostgresResource = IsObject({
+    host: IsString.orUndefined,
+    port: IsNumber.orUndefined,
+    database: IsString,
+    connectionLimit: IsNumber.orUndefined
+});
+export type GGPostgresHostData = typeof IsPostgresResource.infer
+
+const IsPostgresUserData = IsObject({
+    username: IsString.orUndefined,
+    password: IsString.orUndefined
+});
+export type GGPostgresUserData = typeof IsPostgresUserData.infer
+
+export class GGPostgresConfig {
+
+    public readonly name: string;
+    public readonly token: GGLocatorKey<GGPostgres>;
+    public readonly host: GGResource<GGPostgresHostData>;
+    public readonly user: GGSecret<GGPostgresUserData>;
+    public readonly schemaFile?: string;
+
+    constructor(name: string, schemaFile?: string) {
+        this.name = name;
+        this.token = new GGLocatorKey<GGPostgres>(`Postgres:${name}`);
+        this.host = new GGResource(name + "/host", IsPostgresResource, "Postgres host configuration")
+        this.user = new GGSecret(name + "/user", IsPostgresUserData, "Postgres user credentials")
+        this.schemaFile = schemaFile;
+    }
+
+    public newPostgresPool() {
+        return new GGPostgres(this);
+    }
+}

package/src/GGPostgresConnection.ts

@@ -0,0 +1,146 @@
+import {PoolClient, QueryResult, QueryResultRow} from 'pg';
+import {GGLog} from '@grest-ts/logger';
+
+/**
+ * PostgresConnection - A single connection from the pool.
+ *
+ * Use this when you need:
+ * - Transactions (BEGIN, COMMIT, ROLLBACK)
+ * - Multiple queries that must use the same connection
+ *
+ * IMPORTANT: Always call release() when done to return the connection to the pool.
+ *
+ * @example
+ * ```typescript
+ * const conn = await db.getConnection();
+ * try {
+ *     await conn.beginTransaction();
+ *     await conn.execute('INSERT INTO users ...', [...]);
+ *     await conn.execute('INSERT INTO profiles ...', [...]);
+ *     await conn.commit();
+ * } catch (err) {
+ *     await conn.rollback();
+ *     throw err;
+ * } finally {
+ *     conn.release();
+ * }
+ * ```
+ */
+export class GGPostgresConnection {
+    private client: PoolClient;
+    private released = false;
+
+    constructor(client: PoolClient) {
+        this.client = client;
+    }
+
+    /**
+     * Execute a SELECT query and return rows.
+     */
+    async query<T extends QueryResultRow = QueryResultRow>(sql: string, params?: unknown[]): Promise<T[]> {
+        this.checkReleased();
+        GGLog.debug(this, 'query', {sql, params});
+        const result: QueryResult<T> = await this.client.query<T>(sql, params);
+        GGLog.debug(this, 'query result', {rowCount: result.rowCount});
+        return result.rows;
+    }
+
+    /**
+     * Execute an INSERT, UPDATE, or DELETE query.
+     */
+    async execute(sql: string, params?: unknown[]): Promise<QueryResult> {
+        this.checkReleased();
+        GGLog.debug(this, 'execute', {sql, params});
+        const result = await this.client.query(sql, params);
+        GGLog.debug(this, 'execute result', {rowCount: result.rowCount});
+        return result;
+    }
+
+    // ==================== Transaction methods ====================
+
+    /**
+     * Run a callback within a transaction.
+     * Automatically commits on success, rolls back on failure.
+     *
+     * Note: Does NOT release the connection. Call release() when done.
+     *
+     * @example
+     * ```typescript
+     * const conn = await db.getConnection();
+     * try {
+     *     const result = await conn.runInTransaction(async () => {
+     *         await conn.execute('INSERT INTO orders ...', [...]);
+     *         await conn.execute('UPDATE inventory ...', [...]);
+     *         return orderId;
+     *     });
+     * } finally {
+     *     conn.release();
+     * }
+     * ```
+     */
+    async runInTransaction<T>(callback: () => Promise<T>): Promise<T> {
+        this.checkReleased();
+        await this.client.query('BEGIN');
+        GGLog.debug(this, 'beginTransaction');
+        try {
+            const result = await callback();
+            await this.client.query('COMMIT');
+            GGLog.debug(this, 'commit');
+            return result;
+        } catch (err) {
+            await this.client.query('ROLLBACK');
+            GGLog.debug(this, 'rollback', {error: err});
+            throw err;
+        }
+    }
+
+    /**
+     * Start a transaction.
+     */
+    async beginTransaction(): Promise<void> {
+        this.checkReleased();
+        GGLog.debug(this, 'beginTransaction');
+        await this.client.query('BEGIN');
+    }
+
+    /**
+     * Commit the current transaction.
+     */
+    async commit(): Promise<void> {
+        this.checkReleased();
+        GGLog.debug(this, 'commit');
+        await this.client.query('COMMIT');
+    }
+
+    /**
+     * Rollback the current transaction.
+     */
+    async rollback(): Promise<void> {
+        this.checkReleased();
+        GGLog.debug(this, 'rollback');
+        await this.client.query('ROLLBACK');
+    }
+
+    // ==================== Lifecycle ====================
+
+    /**
+     * Release this connection back to the pool.
+     * MUST be called when done with the connection.
+     */
+    release(): void {
+        if (!this.released) {
+            this.client.release();
+            this.released = true;
+            GGLog.debug(this, 'released');
+        }
+    }
+
+    /**
+     * Check if connection has been released.
+     */
+    private checkReleased(): void {
+        if (this.released) {
+            throw new Error('Connection has been released. Cannot perform operations on a released connection.');
+        }
+    }
+}

package/src/index-node.ts

@@ -0,0 +1,4 @@
+export * from './GGPostgres';
+export * from "./GGPostgresConfig";
+export * from './GGPostgresConnection';
+export type {QueryResult, QueryResultRow} from 'pg';

package/src/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "//": "THIS FILE IS GENERATED - DO NOT EDIT",
+  "extends": "../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "lib": [
+      "ES2022"
+    ],
+    "types": [
+      "node"
+    ]
+  },
+  "include": [
+    "**/*"
+  ]
+}