Database

Quark ERP uses TypeORM on PostgreSQL. Prefer the shared default DataSource for most tables. A plugin can also open one or more custom connections with @Database — and any other plugin can inject those connections by owner plugin name (and optional connection name).

Stack

PostgreSQL — primary persistent store (env via PluginEnv / base .env)
TypeORM — entities, repositories, QueryRunner, migrations
Default datasource — shared core connection; most plugins merge into it with plugin: "default"
Custom datasource — @Database on the root @Module; one plugin may declare multiple named connections
Cross-plugin reuse — inject another plugin’s connection with @InjectDatabaseSource("other-plugin", "connection-name?")

@InjectDatabaseSource

Inject a TypeORM DataSource on a service property (constructor injection is not supported). The first argument is the plugin that owns the connection; the second is the optional connection name when that plugin opened more than one DB.

DataSourceManager.DEFAULT_PLUGIN — primary core datasource
metadata.name — this plugin’s own default custom connection (if it declared @Database)
"other-plugin" — a connection created by another plugin (same process / DI registry)
Second arg name — named connection when the owner plugin declares multiple @Database entries (e.g. "analytics")

TSXinject

import { DataSource } from "typeorm";
import {
  InjectDatabaseSource,
  DataSourceManager,
  Service,
} from "@quan-erp/shared-backend-core";
import metadata from "../../module.metadata.json" with { type: "json" };
import { OrderEntity } from "./order.entity.js";

@Service()
export class OrderService {
  // Shared core Postgres
  @InjectDatabaseSource(DataSourceManager.DEFAULT_PLUGIN)
  source: DataSource;

  // This plugin’s own connection (default name)
  @InjectDatabaseSource(metadata.name)
  pluginSource: DataSource;

  // This plugin’s named connection
  @InjectDatabaseSource(metadata.name, "analytics")
  analyticsSource: DataSource;

  // Connection owned by another plugin
  @InjectDatabaseSource("warehouse", "replica")
  warehouseReplica: DataSource;

  private get repo() {
    return this.source.getRepository(OrderEntity);
  }
}

Define an entity

Table names MUST start with the plugin name. Use metadata.name in a template literal. Always extend BaseEntity for create/update/soft-delete columns.

TSXentity

import { BaseEntity } from "@quan-erp/shared-backend-core";
import { Entity, PrimaryGeneratedColumn, Column } from "typeorm";
import metadata from "../../../../module.metadata.json" with { type: "json" };

@Entity(`${metadata.name}_driver_document`)
export class DriverDocumentEntity extends BaseEntity {
  @PrimaryGeneratedColumn("increment")
  id: number;

  @Column()
  documentName: string;
}

Register on the module

Group entities by datasource. Use plugin: "default" so tables join the primary shared connection. For a custom @Database, set plugin (and optional name) to match that connection — not "default".

TSXdefault datasource

import { Module } from "@quan-erp/shared-backend-core";
import metadata from "../../module.metadata.json" with { type: "json" };
import { OrderController } from "./order.controller.js";
import { OrderService } from "./order.service.js";
import { DriverDocumentEntity } from "./driver-document.entity.js";

@Module({
  name: metadata.name,
  providers: [OrderService],
  controllers: [OrderController],
  entities: [
    {
      plugin: "default",
      entities: [DriverDocumentEntity],
    },
  ],
})
export class MyPluginModule {}

Custom datasource (@Database)

Declare one or more TypeORM connections on the root module with @Database. Prefer the shared default unless you need isolation (separate host/schema, reporting DB, replica, …). Connection options come from TypeORM DataSourceOptions — load host/credentials from env (PluginEnv / base .env), not hard-coded secrets.

@Database({ name?, options }) on the root @Module class — plugin is filled automatically from the loading plugin
name — optional connection id (default DataSourceManager.DEFAULT_NAME); required when one plugin opens multiple DBs
options — TypeORM DataSourceOptions (type, host, port, username, password, database, synchronize, …)
Entities — register via @Module entities with matching plugin + name; do not rely on options.entities (runtime overwrites with the entity registry)
Inject in the same plugin — @InjectDatabaseSource(metadata.name) or @InjectDatabaseSource(metadata.name, "analytics")
Multiple @Database decorators are allowed on the same module class — each becomes a separate connection

TSXmultiple connections in one plugin

import {
  Database,
  Module,
} from "@quan-erp/shared-backend-core";
import metadata from "../../module.metadata.json" with { type: "json" };
import { AnalyticsEntity } from "./analytics.entity.js";
import { WarehouseEntity } from "./warehouse.entity.js";
import { AnalyticsService } from "./analytics.service.js";

@Database({
  name: "analytics",
  options: {
    type: "postgres",
    host: process.env.ANALYTICS_DB_HOST,
    port: Number(process.env.ANALYTICS_DB_PORT ?? 5432),
    username: process.env.ANALYTICS_DB_USERNAME,
    password: process.env.ANALYTICS_DB_PASSWORD,
    database: process.env.ANALYTICS_DB_SCHEMA,
    synchronize: process.env.ANALYTICS_DB_SYNC === "true",
  },
})
@Database({
  name: "replica",
  options: {
    type: "postgres",
    host: process.env.REPLICA_DB_HOST,
    port: Number(process.env.REPLICA_DB_PORT ?? 5432),
    username: process.env.REPLICA_DB_USERNAME,
    password: process.env.REPLICA_DB_PASSWORD,
    database: process.env.REPLICA_DB_SCHEMA,
    synchronize: false,
  },
})
@Module({
  name: metadata.name,
  providers: [AnalyticsService],
  controllers: [],
  entities: [
    {
      plugin: metadata.name,
      name: "analytics",
      entities: [AnalyticsEntity],
    },
    {
      plugin: metadata.name,
      name: "replica",
      entities: [WarehouseEntity],
    },
  ],
})
export class MyPluginModule {}

Use another plugin’s connection

Connections live in the process-wide DataSource registry keyed by owner plugin (+ optional name). A consumer plugin does not re-declare @Database for that DB — it injects the owner’s connection and registers its own entities against that same plugin + name scope when needed.

Owner plugin — declares @Database({ name, options }) and boots first (list it in pluginDependencies)
Consumer plugin — @InjectDatabaseSource("owner-plugin", "connection-name")
Entities on a foreign connection — @Module entities entry uses plugin: "owner-plugin" and name: "connection-name" (not "default")
Do not hard-code a second identical @Database in every consumer — reuse the owner’s connection
Ensure the owner plugin is installed and loaded before consumers that inject its DataSource

TSXconsumer plugin service

import { DataSource } from "typeorm";
import { InjectDatabaseSource, Service } from "@quan-erp/shared-backend-core";

@Service()
export class ReportService {
  // "warehouse" plugin declared @Database({ name: "replica", ... })
  @InjectDatabaseSource("warehouse", "replica")
  warehouseReplica: DataSource;
}

TSXconsumer module entities on foreign connection

@Module({
  name: metadata.name,
  providers: [ReportService],
  controllers: [],
  entities: [
    {
      plugin: "warehouse",
      name: "replica",
      entities: [ReportSnapshotEntity],
    },
  ],
})
export class ReportPluginModule {}

CRUD patterns

Create: repo.insert(...) → return { id } from identifiers (no post-insert findOne)
Update: repo.update({ id }, { ...data, updateDate }) and check affected
Delete: prefer repo.softDelete + affected check (BaseEntity soft-delete)