Database

The database channel writes a notification to a store so you can render an in-app feed — an unread count, a notifications dropdown, a "mark all as read" button. It persists through a NotificationStore abstraction: a bundled in-memory store for development, and ORM adapters (TypeORM, MikroORM, Prisma, Drizzle) for production. The row shape mirrors Laravel's notifications table.

Install

pnpm add @dudousxd/nestjs-notifications-database

npm install @dudousxd/nestjs-notifications-database

Register the channel

import { DatabaseChannelModule } from '@dudousxd/nestjs-notifications-database';

@Module({
  imports: [
    DatabaseChannelModule.forRoot(), // bundled in-memory store
  ],
})
export class AppModule {}

DatabaseChannelModule.forRoot() takes:

There's also DatabaseChannelModule.forFeature(), which registers only the channel and reuses a NOTIFICATION_STORE token provided elsewhere — that's how the ORM adapter modules below wire in.

The notification side

Annotate the payload method with the @Database() handle and return a plain object — that object becomes the persisted data:

import { type Notifiable, Notification } from '@dudousxd/nestjs-notifications-core';
import { Database } from '@dudousxd/nestjs-notifications-database';

@Notification()
export class InvoicePaid {
  constructor(private invoiceId: string, private amount: number) {}

  @Database()
  toDatabase({ notifiable }: ChannelContext): Record<string, unknown> {
    return { invoiceId: this.invoiceId, amount: this.amount };
  }
}

The Database handle also works as a via() token (via() { return [Database]; }) for explicit routing. For compile-time checks, implement DatabaseNotification alongside the decorator.

toDatabase() is optional when you route with an explicit via(). If it's absent the channel falls back to toArray() (Laravel parity), and finally to a structural copy of the notification's own properties.

The notifiable reference

Persisting needs to know whose notification this is, as a { type, id } pair. The channel resolves it in two ways:

1. routeNotificationFor('database') may return a { type, id } reference directly.
2. Otherwise it calls the notifiable's toNotifiableRef().

If neither is available it throws, asking you to provide one:

export class User implements Notifiable {
  constructor(public id: number) {}

  routeNotificationFor() {
    return undefined;
  }

  toNotifiableRef() {
    return { type: 'User', id: this.id };
  }
}

Stored shape

Each persisted notification is a StoredNotification:

interface StoredNotification {
  id: string;
  type: string;            // notification class name, e.g. "InvoicePaid"
  notifiableType: string;  // reference type, e.g. "User"
  notifiableId: string;    // reference id
  data: Record<string, unknown>; // what toDatabase() returned
  readAt: Date | null;
  createdAt: Date;
  updatedAt: Date;
}

The stored type is the notification's notificationName(notification) — an instance-level notificationType() override when implemented, else the class-level @Notification({ name }), else the class name. See notificationType() for when to reach for the instance override (e.g. one generic notification class carrying many event names). This is also the value the ?type= inbox filter matches against.

The store

A store implements NotificationStore. These are the methods you get for reading and managing a feed:

types is absent or an empty array by default, matching every type (unchanged behavior) — it's purely additive. PaginateForNotifiableOptions carries the same types?: string[] for the paginated read path. Every bundled adapter (in-memory, TypeORM, MikroORM, Prisma, Drizzle) implements the filter; see In-app notifications for the higher-level NotificationsQueryService and REST ?type= query param this powers.

Every bundled store implements countUnread. A custom store should implement it too: the React inbox polls the unread count, and without it each poll loads every unread row and its payload.

The store is bound to the NOTIFICATION_STORE token, so inject it to build your feed endpoints:

import { Inject } from '@nestjs/common';
import { NOTIFICATION_STORE, type NotificationStore } from '@dudousxd/nestjs-notifications-database';

constructor(@Inject(NOTIFICATION_STORE) private store: NotificationStore) {}

The bundled InMemoryStore keeps rows in a Map. It's perfect for tests and prototyping — but it's not durable, so use a persistence adapter in production.

Reading notifications in-app

You usually don't inject the raw store. The NotificationsQueryService (provided by the database module) wraps it with the read/manage methods you reach for — all, unread, unreadCount, paginate, markAsRead, markAllAsRead, delete — accepting a notifiable or a { type, id } ref. There's also an optional REST controller you can mount in one call.

See In-app notifications for the full recipe.

Persistence adapters

For real persistence, pair the channel with an adapter. Each adapter provides a store bound to the NOTIFICATION_STORE token, plus the schema it needs (a NotificationEntity for the ORM adapters, a Notification model for Prisma). You register the adapter's store module alongside DatabaseChannelModule.forFeature() — the adapter provides the store token, forFeature() registers the channel that consumes it.

pnpm add @dudousxd/nestjs-notifications-database-typeorm @nestjs/typeorm typeorm

npm install @dudousxd/nestjs-notifications-database-typeorm @nestjs/typeorm typeorm

import { DatabaseChannelModule } from '@dudousxd/nestjs-notifications-database';
import { TypeOrmNotificationStoreModule } from '@dudousxd/nestjs-notifications-database-typeorm';

@Module({
  imports: [
    // ...TypeOrmModule.forRoot({ entities: [NotificationEntity, ...] })
    TypeOrmNotificationStoreModule.forFeature(),
    DatabaseChannelModule.forFeature(),
  ],
})
export class AppModule {}

pnpm add @dudousxd/nestjs-notifications-database-mikro-orm @mikro-orm/core @mikro-orm/decorators @mikro-orm/nestjs

npm install @dudousxd/nestjs-notifications-database-mikro-orm @mikro-orm/core @mikro-orm/decorators @mikro-orm/nestjs

import { DatabaseChannelModule } from '@dudousxd/nestjs-notifications-database';
import { MikroOrmNotificationStoreModule } from '@dudousxd/nestjs-notifications-database-mikro-orm';

@Module({
  imports: [
    // ...MikroOrmModule.forRoot({ entities: [NotificationEntity, ...] })
    MikroOrmNotificationStoreModule.forFeature(),
    DatabaseChannelModule.forFeature(),
  ],
})
export class AppModule {}

pnpm add @dudousxd/nestjs-notifications-database-prisma

npm install @dudousxd/nestjs-notifications-database-prisma

model Notification {
  id             String    @id
  type           String
  notifiableType String
  notifiableId   String
  data           Json
  tenantId       String?
  readAt         DateTime?
  createdAt      DateTime  @default(now())
  updatedAt      DateTime  @updatedAt

  // Backs the inbox reads and the unread count (filter by notifiable, newest first).
  @@index([notifiableType, notifiableId, createdAt])
}

import { DatabaseChannelModule } from '@dudousxd/nestjs-notifications-database';
import { PrismaNotificationStoreModule } from '@dudousxd/nestjs-notifications-database-prisma';

@Module({
  imports: [
    PrismaNotificationStoreModule.forRoot({ client: prisma }),
    DatabaseChannelModule.forFeature(),
  ],
})
export class AppModule {}

pnpm add @dudousxd/nestjs-notifications-database-drizzle drizzle-orm

npm install @dudousxd/nestjs-notifications-database-drizzle drizzle-orm

import { DatabaseChannelModule } from '@dudousxd/nestjs-notifications-database';
import { DrizzleNotificationStoreModule } from '@dudousxd/nestjs-notifications-database-drizzle';

@Module({
  imports: [
    DrizzleNotificationStoreModule.forRootAsync({
      inject: [DB], // your Drizzle database token
      useFactory: (db: Db) => ({ db }),
    }),
    DatabaseChannelModule.forFeature(),
  ],
})
export class AppModule {}

DrizzleModule.forRoot({ drizzle, connection: process.env.DATABASE_URL }),
DrizzleNotificationStoreModule.forRoot({ connectionName: 'default' }),
// or async: the connection name is static, the factory resolves the rest
DrizzleNotificationStoreModule.forRootAsync({
  connectionName: 'default',
  inject: [ConfigService],
  useFactory: (config: ConfigService) => ({ tables: tablesFor(config) }),
}),

Schema

By default the channel is self-contained: on boot it creates the notifications table if it's missing, non-destructively — it only adds what's absent and never drops anything. That's autoCreateSchema: true, the default on both DatabaseChannelModule.forRoot() and DatabaseChannelModule.forFeature(). Install an adapter, register the module, and the feed works on first run with no migration step.

To own the schema with your ORM's migrations instead, disable auto-create and use the exported migration helpers:

DatabaseChannelModule.forFeature({ autoCreateSchema: false }),

import { createNotificationsTable } from '@dudousxd/nestjs-notifications-database-typeorm';
import type { MigrationInterface, QueryRunner } from 'typeorm';

export class AddNotifications1700000000000 implements MigrationInterface {
  async up(queryRunner: QueryRunner): Promise<void> {
    await createNotificationsTable(queryRunner);
  }

  async down(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.dropTable('notifications', true);
  }
}

import { notificationsSchemaSql } from '@dudousxd/nestjs-notifications-database-mikro-orm';
import { Migration } from '@mikro-orm/migrations';

export class AddNotifications extends Migration {
  async up(): Promise<void> {
    this.addSql(await notificationsSchemaSql(this.getEntityManager()));
  }
}

npx prisma migrate dev --name add-notifications

import { createNotificationTables } from '@dudousxd/nestjs-notifications-database-drizzle';

export const notificationTables = createNotificationTables(); // or { tableNames, schema }
export const { notifications, pendingDigests, digestWindows } = notificationTables;

DrizzleNotificationStoreModule.forRootAsync({
  inject: [DB],
  useFactory: (db: Db) => ({ db, tables: notificationTables }),
}),
DatabaseChannelModule.forFeature({ autoCreateSchema: false }),

The inbox index

Every adapter declares notifications_notifiable_idx on (notifiable_type, notifiable_id, created_at). It serves the inbox reads (WHERE notifiable = ? ORDER BY created_at DESC) and the unread count. The tenant column is not part of it, so reads without a tenant keep the created_at ordering from the index.

How an existing notifications table gets it:

• autoCreateSchema on (TypeORM, MikroORM, Drizzle): the next boot creates it. TypeORM matches indexes by name and only adds missing ones; MikroORM's schema fingerprint changes, so the table is healed once; Drizzle's ensureSchema() runs CREATE INDEX IF NOT EXISTS.

• TypeORM migrations: createNotificationsTable() does nothing when the table exists, so add the index in a new migration. Building it from the entity metadata keeps the column names right under any naming strategy:

  import { NotificationEntity } from '@dudousxd/nestjs-notifications-database-typeorm';
  import { type MigrationInterface, type QueryRunner, TableIndex } from 'typeorm';
  
  const INDEX = 'notifications_notifiable_idx';
  
  export class AddNotificationsInboxIndex1730000000000 implements MigrationInterface {
    async up(queryRunner: QueryRunner): Promise<void> {
      const metadata = queryRunner.connection.getMetadata(NotificationEntity);
      const index = metadata.indices.find((i) => i.name === INDEX);
      if (index) await queryRunner.createIndex('notifications', TableIndex.create(index));
    }
  
    async down(queryRunner: QueryRunner): Promise<void> {
      await queryRunner.dropIndex('notifications', INDEX);
    }
  }

• MikroORM migrations: a new migration with this.addSql(await notificationsSchemaSql(this.getEntityManager())) emits the CREATE INDEX, as does MikroORM's own migration:create when NotificationEntity is discovered.

• Prisma: add the @@index line to the model above and run prisma migrate dev.

• Drizzle with drizzle-kit: the index is part of createNotificationTables() (named <table>_notifiable_idx when you pass custom tableNames), so drizzle-kit migrations include it.

import { notificationsManagedTables } from '@dudousxd/nestjs-notifications-database-mikro-orm';

schemaGenerator: { skipTables: notificationsManagedTables() },