Check health of database replicas

[clintonb]

Is there an existing issue that is already proposing this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe it

My application uses a read replica to help reduce load on the primary. TypeORM health checks work out-of-the-box for the primary, but need extra configuration to work with the replica.

Describe the solution you'd like

I want Terminus to either check the replicas or give me the option to configure checks for the replicas.

Teachability, documentation, adoption, migration strategy

TBD

What is the motivation / use case for changing the behavior?

Ensure all dependencies are monitored as part of health checks.

[temrjan]

I looked into this and wanted to propose a minimal API addition.

Current behavior: pingCheck() calls connection.query('SELECT 1') which always hits the master connection, even when TypeORM replication is configured.

Proposed solution: Add an optional replicationMode to TypeOrmPingCheckSettings:

export interface TypeOrmPingCheckSettings {
  connection?: any;
  timeout?: number;
  replicationMode?: 'master' | 'slave'; // new
}

When set, pingDb would use connection.createQueryRunner(replicationMode) to target the specific connection pool:

if (replicationMode) {
  const queryRunner = connection.createQueryRunner(replicationMode);
  check = queryRunner.query('SELECT 1').finally(() => queryRunner.release());
}

This allows users to set up separate health checks for master and replicas:

async () => this.typeOrm.pingCheck('db-master', { replicationMode: 'master' }),
async () => this.typeOrm.pingCheck('db-replica', { replicationMode: 'slave' }),

Open questions:

• Should we check all replicas (TypeORM round-robins slaves internally) or expose index-based access?
• The mongodb driver doesn't support createQueryRunner with replication mode — should this be a no-op or an error?

Happy to submit a PR if this direction looks right.

[BrunnerLivio]

With the TypeOrmHealthIndicator, you can already explicitly pass connections.
You can find a sample in here: https://github.com/nestjs/terminus/tree/master/sample/006-multi-db-typeorm-app

If you're utilising the TypeOrm replication configuration, for now, I'd suggest going with a custom health indicator (Note: Following sample AI generated -- use at your own risk)

import { Injectable } from '@nestjs/common';
import { HealthIndicatorService, HealthIndicatorResult } from '@nestjs/terminus';
import { InjectDataSource } from '@nestjs/typeorm';
import { DataSource } from 'typeorm';

@Injectable()
export class ReplicaHealthIndicator {
  constructor(
    @InjectDataSource()
    private readonly dataSource: DataSource,
    private readonly healthIndicatorService: HealthIndicatorService,
  ) {}

  async isHealthy(key: string): Promise<HealthIndicatorResult> {
    const indicator = this.healthIndicatorService.check(key);

    const queryRunner = this.dataSource.createQueryRunner('slave');
    try {
      await queryRunner.query('SELECT 1');
      return indicator.up();
    } catch (error) {
      return indicator.down({ message: error.message });
    } finally {
      await queryRunner.release();
    }
  }
}

If this issue gains enough traction, I might consider adding first-class support in the TypeOrmHealthIndicator.