Ensure real-time balance guarantees

1. Column Default

Use a SQL default expression so Postgres truly defaults to zero even if TypeORM skips it:

  @Column('numeric', {
    name: 'balance',
    precision: 20,
    scale: 6,
    default: () => "'0'",    // ← wrap in () => to emit as SQL literal
    transformer: { … },
  })
  public balance!: Decimal;

2. Eager vs. Lazy Loading

Right now your join is lazy by default. If you’ll frequently need the balance alongside the account, you could make it eager:

  @OneToOne(() => AccountEntity, (acct) => acct.balance, {
    onDelete: 'CASCADE',
    eager: true,         // load balance automatically with account
    nullable: false,
  })

3. Repository Helper for Concurrency

Rather than letting multiple transactions slip through, add a service/repo method that uses SELECT … FOR UPDATE:

async adjustBalance(
  accountId: string,
  delta: Decimal
): Promise<Decimal> {
  return await this.manager.transaction(async (mgr) => {
    const bal = await mgr.getRepository(AccountBalanceEntity)
      .createQueryBuilder('b')
      .setLock('pessimistic_write')
      .where('b.accountId = :id', { id: accountId })
      .getOneOrFail();

    bal.balance = bal.balance.plus(delta);
    await mgr.save(bal);
    return bal.balance;
  });
}

That guarantees no two concurrent postings can race.

4. Database Trigger for Safety

As a last-line guard, you can add a Postgres trigger so that any insert into ledger_entries (our next table) will atomically update account_balances:

5. Audit Trail (Optional)

If you need to track how balances changed over time, consider a account_balance_history table:

@Entity('account_balance_history')
export class AccountBalanceHistoryEntity extends BaseModel {
  @Column('uuid') accountId!: string;
  @Column('numeric', { precision: 20, scale: 6 }) oldBalance!: Decimal;
  @Column('numeric', { precision: 20, scale: 6 }) newBalance!: Decimal;
  @Column('text') reason!: string;  // e.g. 'posted ledger_entry: …'
}

And have the same trigger insert into it.

Next Up

With AccountBalanceEntity locked down, the natural “Phase 1” step is to implement the SQL trigger above plus the pessimistic-lock helper in your repository. Once that’s in place, balances will stay accurate in real time. After that, we can move on to wiring up your AccountEntity (the one-to-one link) and then build out TransactionTypeEntity and the rest of the stack.

1. Column Default#

2. Eager vs. Lazy Loading#

3. Repository Helper for Concurrency#

4. Database Trigger for Safety#