Data Sources

Datasource construction records configuration. Asynchronous initialization acquires the connections. Application lifecycle owns initialization and cleanup, including primary, replica and routing clients.

Configure a datasource

import 'reflect-metadata';
import {DATASOURCE_CONFIG, DataSourceClient, DataSourceDriver, UseConfig, type DataSourceConfig} from '@heronjs/common';
import {AbstractDataSourceClient} from '@heronjs/core';
 
const config: DataSourceConfig = {
  client: DataSourceClient.KNEX,
  config: () => {
    const password = process.env.POSTGRES_PASSWORD;
    if (!password) throw new Error('POSTGRES_PASSWORD is required');
    return {
      driver: DataSourceDriver.POSTGRES,
      host: 'localhost', port: 5432, user: 'app', password,
      database: 'app', pooling: {min: 1, max: 10},
    };
  },
};
 
@UseConfig(DATASOURCE_CONFIG, config)
export class PostgresDatabase extends AbstractDataSourceClient {}

Install the database driver used by your configuration. UseConfig takes a typed metadata key and its matching configuration in 4.0.0. AbstractDataSourceClient no longer needs a caller-selected generic client type.

Registration and use

Declare datasource classes with @DataSources([PostgresDatabase]) on your module. The application awaits initialization before use. For a standalone instance, explicitly await initialize() and later dispose(); database() can be undefined before initialization.

Tenant and replica connections

Use AbstractTenancyDataSourceClient for tenant-aware configuration. Tenant repository with(...) is asynchronous in 4.0.0: await it before querying the selected client. Configure replicas through cluster.secondaries, and set writable: true only on nodes intended to accept writes.

See the Migration Guide for renamed datasource contracts and application ownership changes.