TypeORM Integration

DolphJS provides full integration for SQL databases via TypeORM. You get auto-initialization from the dolph_config.yaml file, and direct access to the DataSource object without having to build boilerplate setup scripts.

Configuration

To connect to your database via TypeORM, simply declare the typeorm block in your dolph_config.yaml.

The options object provided maps exactly to TypeORM’s official DataSourceOptions. This guarantees that you can use every single TypeORM feature, such as synchronize, logging, subscribers, migrations, and more.

dolph_config.yaml

database:
  typeorm:
    options:
      type: postgres
      host: localhost
      port: 5432
      username: root
      password: sensitive
      database: dolph_db
      synchronize: true
      logging: false
      entities:
        - "src/models/*.ts"

Note

Sensitive Credentials: Notice we set password: sensitive in the config above. When you set properties like username, password, host, or url to "sensitive", DolphJS automatically intercepts this and injects the corresponding environment variable from your .env file (SQL_USER, SQL_PASSWORD, SQL_HOST, SQL_URL). This ensures your credentials never leak into your source code!

When you start your DolphJS application, the DolphFactory reads this block and automatically connects the DataSource — but not before your services are constructed. See the callout below before wiring up getDataSource() in a service.

Defining the Entity

Let’s create a standard TypeORM entity.

src/models/user.entity.ts

import { Entity, PrimaryGeneratedColumn, Column } from 'typeorm';

@Entity()
export class User {
    @PrimaryGeneratedColumn()
    id: number;

    @Column()
    firstName: string;

    @Column()
    lastName: string;

    @Column({ default: true })
    isActive: boolean;
}

Using TypeORM in Services

Since TypeORM is globally auto-initialized by DolphJS, you can easily access the underlying DataSource anywhere inside your services using the getDataSource() function from @dolphjs/dolph/packages/typeorm.

Caution

Call getDataSource() lazily, not as a field initializer. If a service is wired up through @Component({ services: [...] }), that component resolves and constructs every listed service the moment its module is imported — which happens before new DolphFactory(...) ever runs, since imports are evaluated first. autoInitTypeOrm() (which is what actually creates the DataSource) only runs once DolphFactory’s constructor executes. A field initializer like private userRepo = getDataSource().getRepository(User) therefore throws TypeORM DataSource has not been initialized at construction time — caught internally and logged, so the app still appears to boot, but the service silently never finishes constructing. A getter defers the call until the service is actually used (a request being handled), by which point DolphFactory has run and the DataSource exists.

src/user/user.service.ts

import { DService } from '@dolphjs/dolph/decorators';
import { getDataSource } from '@dolphjs/dolph/packages/typeorm';
import { User } from '../models/user.entity';

@DService('userService')
export class UserService {
  // A getter, not a field initializer — see the caution above.
  private get userRepo() {
    return getDataSource().getRepository(User);
  }

  async createUser(firstName: string, lastName: string) {
    const user = new User();
    user.firstName = firstName;
    user.lastName = lastName;

    // Save to the database
    return await this.userRepo.save(user);
  }

  async getAllActiveUsers() {
    return await this.userRepo.find({
      where: { isActive: true },
    });
  }
}

Wrapping Up

By passing configuration down via the native options block, your dolph_config.yaml becomes the central source of truth, and TypeORM fits naturally into your standard DolphJS architecture.