@ace-common/database

TypeORM wrapper for NestJS with health checks and auto-migrations.

Installation

pnpm add @ace-common/database

Peer dependencies: @nestjs/common, @nestjs/core, @nestjs/typeorm, typeorm, reflect-metadata.

Quick Start

Sync config

import { configureDatabase } from '@ace-common/database';

@Module({
  imports: [
    configureDatabase({
      type: 'mysql',
      host: '127.0.0.1',
      port: 3306,
      username: 'root',
      password: '',
      database: 'myapp',
      entities: [UserEntity],
      synchronize: true,
    }),
  ],
})
export class AppModule {}

Async config (with @ace-common/config)

import { configureDatabaseAsync } from '@ace-common/database';
import { ACE_CONFIG } from '@ace-common/config';

@Module({
  imports: [
    configureConfig({ schema: AppConfig }),
    configureDatabaseAsync({
      inject: [ACE_CONFIG],
      useFactory: (config: AppConfig) => ({
        type: 'mysql',
        host: config.MYSQL_HOST,
        port: config.MYSQL_PORT,
        username: config.MYSQL_USER,
        password: config.MYSQL_PASSWORD,
        database: config.MYSQL_DATABASE,
        entities: [UserEntity],
        synchronize: config.NODE_ENV !== 'production',
        runMigrations: config.NODE_ENV === 'production',
      }),
    }),
  ],
})
export class AppModule {}

Registering entities per module

Use TypeOrmModule.forFeature() from @nestjs/typeorm as usual:

@Module({
  imports: [TypeOrmModule.forFeature([UserEntity])],
  providers: [UserService],
})
export class UserModule {}

Health Check

DatabaseHealthIndicator is registered globally and can be injected anywhere:

import { DatabaseHealthIndicator } from '@ace-common/database';

@Controller('health')
export class HealthController {
  constructor(private readonly dbHealth: DatabaseHealthIndicator) {}

  @Get()
  async check() {
    return this.dbHealth.check();
    // { "database": { "status": "up" } }
  }
}

Methods:

| Method | Returns | Description | |---|---|---| | isHealthy() | Promise<boolean> | Simple boolean ping | | check(key?) | Promise<Record<string, HealthCheckResult>> | Structured result with status and error message |

Auto-Migrations

Set runMigrations: true to automatically run pending TypeORM migrations when the app starts:

configureDatabase({
  // ...connection options
  migrations: ['dist/migrations/*.js'],
  runMigrations: true,
});

Each migration runs in its own transaction. The app logs applied migration names on startup.

Options

All standard TypeOrmModuleOptions are supported, plus:

| Option | Default | Description | |---|---|---| | runMigrations | false | Run pending migrations on startup |

Exports

| Export | Description | |---|---| | configureDatabase | Sync module configuration helper | | configureDatabaseAsync | Async module configuration helper | | AceDatabaseModule | NestJS dynamic module (forRoot / forRootAsync) | | DatabaseHealthIndicator | Injectable health check service | | MigrationRunner | Startup migration runner | | DatabaseModuleOptions | Options type (extends TypeOrmModuleOptions) | | DatabaseAsyncOptions | Async options type |

License

MIT