Slonik module for Nest 8/9/10
This module is based on @nestjs/typeorm and @nestjs/sequelize modules.
This README is based on nest.js documentation.
npm i --save nestjs-slonik slonikyarn add nestjs-slonik slonikOnce the installation process is complete, we can import the SlonikModule into the root AppModule.
app.module.ts
import { Module } from '@nestjs/common';
import { SlonikModule } from 'nestjs-slonik';
@Module({
imports: [
SlonikModule.forRoot({
connectionUri: 'postgres://root:root@localhost/test',
}),
],
})
export class AppModule {}The forRoot() method supports configuration properties described below.
| Slonik options | |
connectionUri |
Connection URI |
clientConfiguration |
Slonik configuration object |
| SlonikModule options | |
name |
Connection pool name. Used to inject different db connections (default: default) |
toRetry |
Function that determines whether the module should attempt to connect upon failure
(err: any) => boolean
err parameter is error that was thrown |
verboseRetryLog |
If true, will show verbose error messages on each connection retry (default: false) |
retryAttempts |
Number of attempts to connect to the database (default: 10) |
retryDelay |
Delay between connection retry attempts (ms) (default: 3000) |
Once this is done, the Slonik pool will be available to inject across the entire project (without needing to import any modules), for example:
app.service.ts
import { Injectable } from '@nestjs/common';
import { InjectPool } from 'nestjs-slonik';
import { DatabasePool, sql } from 'slonik';
@Injectable()
export class AppService {
constructor(@InjectPool() private pool: DatabasePool) {}
getHello(): Promise<string> {
return this.pool.oneFirst<string>(sql`SELECT 'Hello World!';`);
}
}Some projects require multiple database connections. This can also be achieved with this module. To work with multiple pools, first create the pools. In this case, pool naming becomes mandatory.
@Module({
imports: [
SlonikModule.forRoot({
connectionUri: 'postgres://user:pwd@user_db_host:5432/users',
}),
SlonikModule.forRoot({
name: 'albumsConnection',
connectionUri: 'postgres://user:pwd@album_db_host:5432/albums',
}),
],
})
export class AppModule {}Notice If you don't set the
namefor a pool, its name is set todefault. Please note that you shouldn't have multiple pools without a name, or with the same name, otherwise they will get overridden.
Now you can inject the Slonik pool for a given pool name:
@Injectable()
export class AlbumsService {
constructor(
@InjectPool()
private usersPool: DatabasePool,
@InjectPool('albumsConnection')
private albumsPool: DatabasePool,
) {}
}It's also possible to inject any Slonik pool instance to the providers:
import { DatabasePool } from 'slonik';
import { getPoolToken } from 'nestjs-slonik';
@Module({
providers: [
{
provide: AlbumsService,
useFactory: (albumsConnection: DatabasePool) => {
return new AlbumsService(albumsConnection);
},
inject: [getPoolToken('albumsConnection')],
},
],
})
export class AlbumsModule {}When it comes to unit testing an application, we usually want to avoid making a database connection,
keeping our test suites independent and their execution process as fast as possible. But our classes might
depend on Slonik pool instance. How do we handle that? The solution is to create mock pool. In order to achieve
that, we set up custom providers.
Each registered pool is automatically represented by an <poolName='default'>SlonikPool token.
The nestjs-slonik package exposes the getPoolToken() function which returns a prepared token based on a given
pool name.
@Module({
providers: [
UsersService,
{
provide: getPoolToken(),
useValue: mockPool,
},
],
})
export class UsersModule {}Now a substitute mockPool will be used as the Slonik pool. Whenever any class asks for Slonik pool using
an @InjectPool() decorator, Nest will use the registered mockPool object.
- https://github.com/gajus/slonik#mocking-slonik
- https://github.com/oguimbal/pg-mem/wiki/Libraries-adapters#-slonik
example of pg-mem usage
import { newDb } from 'pg-mem';
const mockDb = newDb();
mockDb.public.none(`create table users(id text);
insert into users values ('john doe');`);
const mockPool = mockDb.adapters.createSlonik();You can read more about pg-mem here
You may want to pass your SlonikModule options asynchronously instead of statically.
In this case, use the forRootAsync() method, which provides several ways to deal with async configuration.
One approach is to use a factory function:
SlonikModule.forRootAsync({
useFactory: () => ({
connectionUri: 'postgres://root:root@0.0.0.0:5432/test',
}),
});Our factory behaves like any other asynchronous provider
(e.g., it can be async and it's able to inject dependencies through inject).
SlonikModule.forRootAsync({
imports: [ConfigModule],
useFactory: (configService: ConfigService) => ({
connectionUri: configService.get('DATABASE_URL'),
clientConfigurationInput: {
interceptors: [
createFieldNameTransformationInterceptor({ format: 'CAMEL_CASE' }),
],
},
}),
inject: [ConfigService],
});Alternatively, you can use the useClass syntax:
SlonikModule.forRootAsync({
useClass: SlonikConfigService,
});The construction above will instantiate SlonikConfigService inside SlonikModule and use it to provide
an options object by calling createSlonikOptions(). Note that this means that the SlonikConfigService
has to implement the SlonikOptionsFactory interface, as shown below:
@Injectable()
class SlonikConfigService implements SlonikOptionsFactory {
createSlonikOptions(): SlonikModuleOptions {
return {
connectionUri: 'postgres://root:root@localhost/test',
};
}
}In order to prevent the creation of SlonikConfigService inside SlonikModule and use a provider imported
from a different module, you can use the useExisting syntax.
SlonikModule.forRootAsync({
imports: [ConfigModule],
useExisting: ConfigService,
});This construction works the same as useClass with one critical difference - SlonikModule will lookup
imported modules to reuse an existing ConfigService instead of instantiating a new one.
Make sure that the
nameproperty is defined at the same level as theuseFactory,useClass, oruseValueproperty. This will allow Nest to properly register the pool under the appropriate injection token.
Read more about this pattern here: Slonik docs
@Module({
imports: [
SlonikModule.forRoot({
name: 'slave',
connectionUri: 'postgres://slave',
}),
SlonikModule.forRootAsync({
inject: [getPoolToken('slave')],
useFactory: (slavePool: DatabasePool) => ({
connectionUri: 'postgres://master',
clientConfigurationInput: {
interceptors: [
{
beforePoolConnection: async (connectionContext) => {
if (connectionContext?.query?.sql?.includes('SELECT')) {
return slavePool;
}
},
},
],
},
}),
}),
],
controllers: [AppController],
})
export class AppModule {}We register master pool as the default pool, but use Slonik interceptors to return
slave pool on SELECT queries.
app.controller.ts
import { Controller, Get } from '@nestjs/common';
import { InjectPool } from 'nestjs-slonik';
import { DatabasePool, sql } from 'slonik';
@Controller()
export class AppController {
constructor(@InjectPool() private readonly pool: DatabasePool) {}
@Get()
async getHello() {
await this.pool.query(sql`UPDATE 1`);
return this.pool.oneFirst(sql`SELECT 1`);
}
}The first query will use postgres://master connection.
The second query will use postgres://slave connection.
