Description

PostgreSQL module for Nest framework (node.js) 😻

Installation

First install the module via yarn or npm or pnpm and do not forget to install the driver package as well:

    $ npm i --save @n0isy/nest-postgres pg

or

    $ yarn add @n0isy/nest-postgres pg

or

    $ pnpm add @n0isy/nest-postgres pg

Table of Contents

• Description
• Table of Contents
• Migration
• Usage
  • PostgresModule
  • PostgresPoolModule
  • MultiConnectionsDatabase
  • ExampleOfUse

Migration

Migrating from nest-postgres? See MIGRATION.md for a step-by-step guide.

Usage

PostgresModule

PostgresModule is the primary entry point for this package and can be used synchronously

@Module({
  imports: [
    PostgresModule.forRoot({
        connectionString: 'postgresql://[user]:[password]@[host]/[nameDb]',
        // or 
        // host: 'localhost',
        // database: [:databaseName],
        // password: [:passwordDb],
        // user: [:userDb],
        // port: 5432,
    }),
  ],
})

or asynchronously

@Module({
  imports: [
    PostgresModule.forRootAsync({
      useFactory: () => ({
        connectionString: 'postgresql://[user]:[password]@[host]/[nameDb]',
        // or 
        // host: 'localhost',
        // database: [:databaseName],
        // password: [:passwordDb],
        // user: [:userDb],
        // port: 5432,
      }),
    }),
  ],
})

PostgresModule keeps the original behavior and provides a dedicated PoolClient, injectable with InjectClient or InjectConnection.

PostgresPoolModule

Use PostgresPoolModule when the application should share a pg.Pool:

@Module({
  imports: [
    PostgresPoolModule.forRoot({
      connectionString: 'postgresql://[user]:[password]@[host]/[nameDb]',
    }),
  ],
})
export class AppModule {}

Inject it independently with InjectPool:

import { InjectPool, PostgresPool } from '@n0isy/nest-postgres';

@Injectable()
export class ReportsService {
  constructor(@InjectPool() private readonly pool: PostgresPool) {}

  async createReport(): Promise<void> {
    await this.pool.transaction(async (client) => {
      await client.query('INSERT INTO reports DEFAULT VALUES');
      await client.query('INSERT INTO audit_log DEFAULT VALUES');
    });
  }
}

The callback uses one checked-out client, runs BEGIN/COMMIT, rolls back on failure, and always releases the client. For unrelated queries, call pool.query(...) directly.

Client and pool registrations use separate DI tokens, so both modules can be registered for the same connection name when both access styles are needed:

import { PoolClient } from 'pg';

imports: [
  PostgresModule.forRoot(options, 'main'),
  PostgresPoolModule.forRoot(options, 'main'),
]

constructor(
  @InjectClient('main') private readonly client: PoolClient,
  @InjectPool('main') private readonly pool: PostgresPool,
) {}

Example of use

UsersService:

import { Client } from 'pg';
import { InjectClient } from '@n0isy/nest-postgres';

@Injectable()
export class UsersService {
  constructor(@InjectClient() private readonly pg: Client) {}

  public async findAll(): Promise<User[]> {
    const users = await this.pg.query('SELECT * FROM users');
    return users.rows;
  }
}

UsersController:

import { Controller, Get } from '@nestjs/common';
import { UsersService } from './users.service';

@Controller()
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Get()
  async getAllUsers(): Promise<User[]> {
    return await this.usersService.findAll();
  }
}

Multi Connections Database

@Module({
  imports: [
    PostgresModule.forRoot(
      {
        connectionString: 'postgresql://postgres:pass123@localhost:5432/nest1',
        // or 
        // host: 'localhost',
        // database: [:databaseName],
        // password: [:passwordDb],
        // user: [:userDb],
        // port: 5432,
      },
      'db1Connection',
    ),
    PostgresModule.forRoot(
      {
        connectionString: 'postgresql://postgres:pass123@localhost:5434/nest2',
      },
      'db2Connection',
    ),
  ],
  controllers: [],
  providers: [],
})
export class AppModule {}

Usage example with Multi Connection

PostService:

import { Client } from 'pg';
import { InjectConnection } from '@n0isy/nest-postgres';
import { CreatePostDto } from './dto/create-post.dto';
import { Post } from './interfaces/post.interface';

@Injectable()
export class PostService {
  constructor(
    @InjectConnection('db2Connection')
    private dbConnection: Client,
  ) {}

  public async findAll(): Promise<Post[]> {
    const users = await this.dbConnection.query('SELECT * FROM posts');
    return users.rows;
  }

  public async create(createPostDto: CreatePostDto): Promise<Post[]> {
    try {
      const user = await this.dbConnection.query(
        'INSERT INTO posts (title, description)  VALUES ($1, $2) RETURNING *',
        [createPostDto.title, createPostDto.description],
      );
      return user.rows;
    } catch (err) {
      throw new HttpException(err, HttpStatus.BAD_REQUEST);
    }
  }
}

UsersService:

import { Client } from 'pg';
import { InjectConnection } from '@n0isy/nest-postgres';
import { CreateUserDto } from './dto/create-user.dto';
import { User } from './interfaces/user.interface';

@Injectable()
export class UsersService {
  constructor(
    @InjectConnection('db1Connection')
    private dbConnection: Client,
  ) {}

  public async findAll(): Promise<User[]> {
    const users = await this.dbConnection.query('SELECT * FROM users');
    return users.rows;
  }

  public async create(createUserDto: CreateUserDto): Promise<User[]> {
    try {
      const user = await this.dbConnection.query(
        'INSERT INTO users (firstName, lastName)  VALUES ($1, $2) RETURNING *',
        [createUserDto.firstName, createUserDto.lastName],
      );
      return user.rows;
    } catch (err) {
      throw new HttpException(err, HttpStatus.BAD_REQUEST);
    }
  }
}

For more information on node-postgres for Nodejs see here

Note

TypeScript source code (lib/) was restored from compiled dist/ output using Claude Code. The original author dropped the source contribution, so the library was reverse-engineered from the published JavaScript and declaration files. All e2e tests pass against the restored source.

Contribute

Feel free to help this library. Make sure you follow the guidelines.

Releasing

GitHub Actions runs lint, build, and PostgreSQL integration tests for pull requests and pushes to main. Tags matching v* run the same checks before publishing to npm through the trusted publisher configured for .github/workflows/publish.yml. The tag must match the version in both package.json and package-lock.json, and its commit must belong to main. This workflow publishes stable versions only.

For a new patch release, start from a clean, up-to-date main with passing CI:

npm ci
npm run release -- patch

release-it updates the version, commits it, and pushes a vX.Y.Z tag. GitHub Actions then builds and publishes the package. No local npm publish token is required. Check the Publish to npm workflow and the version on npm after each release. For a version already committed to main, create and push its matching tag instead of incrementing it again.

Stay in touch

• Author - n0isy
• Maintainer - Leo5878
• Original Author - Tony133
• Framework - https://nestjs.com

License

MIT licensed