@starci/hfs 4.0.8 → 4.0.9

package/templates/be/skeleton/src/modules/domain/note/persistence/connection.ts

@@ -0,0 +1,8 @@
+import { NoteEntity } from "./entities/note.entity"
+import { InitNote1790000000000 } from "./migrations/1790000000000-init-note"
+
+/** The entities of the note capability, for the connection that holds them. */
+export const noteEntities = [NoteEntity]
+
+/** The migrations of the note capability, in the order they run. */
+export const noteMigrations = [InitNote1790000000000]

package/templates/be/skeleton/src/modules/domain/note/persistence/entities/note.entity.ts

@@ -0,0 +1,17 @@
+import { Column, Entity, PrimaryGeneratedColumn } from "typeorm"
+
+@Entity("notes")
+/** One note: a short text and the instant it was written. */
+export class NoteEntity {
+    /** The note id. */
+    @PrimaryGeneratedColumn("uuid", { name: "id" })
+    id!: string
+
+    /** The text of the note. */
+    @Column({ name: "body", type: "text" })
+    body!: string
+
+    /** When the note was written, from the injected clock. */
+    @Column({ name: "created_at", type: "timestamptz" })
+    createdAt!: Date
+}

package/templates/be/skeleton/src/modules/domain/note/persistence/migrations/1790000000000-init-note.ts

@@ -0,0 +1,22 @@
+import type { MigrationInterface, QueryRunner } from "typeorm"
+
+/** Creates the notes table of the primary database. */
+export class InitNote1790000000000 implements MigrationInterface {
+    name = "InitNote1790000000000"
+
+    /** Creates the table and the index the newest-first list reads. */
+    async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`CREATE TABLE notes (
+    id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    body text NOT NULL CHECK (char_length(body) > 0),
+    created_at timestamptz NOT NULL
+)`)
+        await queryRunner.query(`CREATE INDEX ix_notes_created_at ON notes (created_at DESC)`)
+    }
+
+    /** Drops the index and the table. */
+    async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`DROP INDEX ix_notes_created_at`)
+        await queryRunner.query(`DROP TABLE notes`)
+    }
+}

package/templates/be/skeleton/src/modules/domain/note/persistence/note.rows.ts

@@ -0,0 +1,17 @@
+import type { Note } from "../note.contracts"
+
+/** The row INSERT_NOTE answers. */
+export interface NoteRow {
+    /** The note id. */
+    id: string
+    /** The text of the note. */
+    body: string
+    /** When the note was written. */
+    created_at: Date
+}
+
+/** The note of the row an insert answers, or null when it answered none. */
+export const toNote = (rows: ReadonlyArray<NoteRow>): Note | null => {
+    const row = rows[0]
+    return row ? { id: row.id, body: row.body, createdAt: row.created_at.toISOString() } : null
+}

package/templates/be/skeleton/src/modules/domain/note/persistence/note.sql.ts

@@ -0,0 +1,4 @@
+import { sql } from "@modules/platform/database"
+
+/** Writes one note ($1 body, $2 written at) and answers the stored row. */
+export const INSERT_NOTE = sql`INSERT INTO notes (body, created_at) VALUES ($1, $2) RETURNING id, body, created_at`

package/templates/be/skeleton/src/modules/platform/config/env-source.config.ts

@@ -5,6 +5,21 @@ const FILE_SUFFIX = "_FILE"
 const DURATION_UNITS: Readonly<Record<string, number>> = { ms: 1, s: 1000, m: 60_000, h: 3_600_000 }
 const DURATION_PATTERN = /^(\d+)(ms|s|m|h)?$/
 
+/** A secret value (password, token, connection string with credentials): never logged, serialized as a mask. */
+export class Secret {
+    constructor(private readonly value: string) {}
+
+    /** The plain value; call it only where the secret is handed to the library that needs it. */
+    reveal(): string {
+        return this.value
+    }
+
+    /** Masks the value when the object is serialized. */
+    toJSON(): string {
+        return "[secret]"
+    }
+}
+
 /**
  * The only reader of the process environment. Typed readers name the missing or malformed key in the error; a key
  * `<KEY>_FILE` supplies `<KEY>` from a file, so secrets can be mounted instead of exported.
@@ -85,4 +100,9 @@ export class EnvSource {
             throw new ConfigError({ code: ConfigErrorCode.KeyInvalid, params: { key } })
         return Number(match[1]) * unit
     }
+
+    /** A required secret. */
+    secret(key: string): Secret {
+        return new Secret(this.string(key))
+    }
 }

package/templates/be/skeleton/src/modules/platform/config/index.ts

@@ -1,4 +1,4 @@
-export { EnvSource } from "./env-source.config"
+export { EnvSource, Secret } from "./env-source.config"
 export { CONFIG_ERROR_KINDS } from "./errors/config.error"
 export { parseServerConfig } from "./server.config"
 export type { ServerOptions } from "./server.options"

package/templates/be/skeleton/src/modules/platform/cqrs/cqrs.contracts.ts

@@ -1,3 +1,21 @@
+/** The verified caller admitted by the default-deny guard. */
+export interface Principal {
+    /** The provider's stable user identifier. */
+    readonly id: string
+    /** The verified email claim when the provider issued one. */
+    readonly email?: string
+    /** The authenticated provider role. */
+    readonly role: "authenticated"
+}
+
+/** The params of an authenticated operation: its mapped request and verified caller. */
+export interface ExecuteParams<T> {
+    /** The request mapped by the transport. */
+    readonly request: T
+    /** The caller established by the guard. */
+    readonly principal: Principal
+}
+
 /** The params of a public operation (no caller is identified): the request as the transport mapped it. */
 export interface PublicExecuteParams<T> {
     /** The request mapped by the transport. */

package/templates/be/skeleton/src/modules/platform/database/connection-source.client.spec.ts

@@ -0,0 +1,41 @@
+import type { QueryRunner } from "typeorm"
+import { Secret } from "@modules/platform/config"
+import type { DatabaseConnectionOptions } from "./database.options"
+import { openConnectionSource } from "./connection-source.client"
+
+class NoteEntity {}
+
+class CreateNotes {
+    up(_queryRunner: QueryRunner): Promise<void> {
+        return Promise.resolve()
+    }
+
+    down(_queryRunner: QueryRunner): Promise<void> {
+        return Promise.resolve()
+    }
+}
+
+describe("openConnectionSource", () => {
+    it("opens an isolated PostgreSQL data source with the connection's entities and migrations", () => {
+        const connection: DatabaseConnectionOptions = {
+            name: "primary",
+            url: new Secret("postgres://user:password@database.test:5432/primary"),
+            entities: [NoteEntity],
+            migrations: [CreateNotes],
+        }
+
+        const source = openConnectionSource(connection)
+
+        expect(source).toMatchObject({
+            options: {
+                type: "postgres",
+                url: "postgres://user:password@database.test:5432/primary",
+                entities: [NoteEntity],
+                migrations: [CreateNotes],
+                migrationsTableName: "primary_migrations",
+                synchronize: false,
+            },
+            isInitialized: false,
+        })
+    })
+})

package/templates/be/skeleton/src/modules/platform/database/connection-source.client.ts

@@ -0,0 +1,17 @@
+import { DataSource } from "typeorm"
+import type { DatabaseConnectionOptions } from "./database.options"
+import type { ConnectionSource } from "./database.port"
+
+/**
+ * Opens the data source of one connection, uninitialized: its own migration ledger table (`<connection>_migrations`), the
+ * schema changed only by migrations.
+ */
+export const openConnectionSource = (connection: DatabaseConnectionOptions): ConnectionSource =>
+    new DataSource({
+        type: "postgres",
+        url: connection.url.reveal(),
+        entities: [...connection.entities],
+        migrations: [...connection.migrations],
+        migrationsTableName: `${connection.name}_migrations`,
+        synchronize: false,
+    })

package/templates/be/skeleton/src/modules/platform/database/database.module-definition.ts

@@ -0,0 +1,13 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import { DATABASE_OPTIONS } from "./database.port"
+import type { DatabaseOptions } from "./database.options"
+
+/** The configurable-module base of the database capability; `isGlobal` is decided by the app root. */
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = new ConfigurableModuleBuilder<DatabaseOptions>({
+    optionsInjectionToken: DATABASE_OPTIONS,
+})
+    .setExtras({ isGlobal: false }, (definition, extras) => ({
+        ...definition,
+        global: extras.isGlobal,
+    }))
+    .build()

package/templates/be/skeleton/src/modules/platform/database/database.module.ts

@@ -0,0 +1,77 @@
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
+import { TypeOrmModule, getDataSourceToken } from "@nestjs/typeorm"
+import type { DataSource } from "typeorm"
+import { openConnectionSource } from "./connection-source.client"
+import { CONNECTION_SOURCE, DATABASE_OPTIONS, READ_SEED_FILES } from "./database.port"
+import { ConfigurableModuleClass, OPTIONS_TYPE } from "./database.module-definition"
+import { MigrationRunnerService } from "./migration-runner.service"
+import { readSeedFiles } from "./seed-connections.client"
+import { SeedRunnerService } from "./seed-runner.service"
+import { PRIMARY_CONNECTION } from "./primary.connection"
+import { PRIMARY_ENTITY_MANAGER } from "./primary.decorators"
+
+/** The token each declared connection provides its shared EntityManager under. */
+type EntityManagerToken = typeof PRIMARY_ENTITY_MANAGER
+
+const ENTITY_MANAGER_TOKENS: ReadonlyMap<string, EntityManagerToken> = new Map<string, EntityManagerToken>([
+    [PRIMARY_CONNECTION, PRIMARY_ENTITY_MANAGER],
+])
+
+@Module({})
+/**
+ * The database capability: opens one named TypeORM connection per entry of the options and provides its shared
+ * EntityManager, the options and the opener of a one-off data source (the cli migrate and seed commands). The schema never changes here: only migrations change it, and they run only in the cli migrate command.
+ */
+export class DatabaseModule extends ConfigurableModuleClass {
+    /** Registers the capability once per app with the connections it opens. */
+    static register(options: typeof OPTIONS_TYPE): DynamicModule {
+        const base = super.register(options)
+        const managers = options.connections.flatMap((connection) => {
+            const token = ENTITY_MANAGER_TOKENS.get(connection.name)
+            return token === undefined
+                ? []
+                : [
+                      {
+                          provide: token,
+                          inject: [getDataSourceToken(connection.name)],
+                          useFactory: (source: DataSource) => source.manager,
+                      },
+                  ]
+        })
+        return {
+            ...base,
+            imports: [
+                ...(base.imports ?? []),
+                ...options.connections.map((connection) =>
+                    TypeOrmModule.forRoot({
+                        name: connection.name,
+                        type: "postgres",
+                        url: connection.url.reveal(),
+                        entities: [...connection.entities],
+                        synchronize: false,
+                        retryAttempts: 2,
+                    }),
+                ),
+            ],
+            providers: [
+                ...(base.providers ?? []),
+                ...managers,
+                MigrationRunnerService,
+                SeedRunnerService,
+                {
+                    provide: CONNECTION_SOURCE,
+                    useValue: { open: openConnectionSource },
+                },
+                { provide: READ_SEED_FILES, useValue: { read: readSeedFiles } },
+            ],
+            exports: [
+                DATABASE_OPTIONS,
+                CONNECTION_SOURCE,
+                MigrationRunnerService,
+                SeedRunnerService,
+                ...managers.map((manager) => manager.provide),
+            ],
+        }
+    }
+}

package/templates/be/skeleton/src/modules/platform/database/database.options.ts

@@ -0,0 +1,30 @@
+import type { MigrationInterface } from "typeorm"
+import type { Secret } from "@modules/platform/config"
+
+/** An entity class as TypeORM registers it. */
+export type EntityClass = new () => object
+
+/** A migration class as TypeORM runs it. */
+export type MigrationClass = new () => MigrationInterface
+
+/** What a connection config parser reads from the environment: the logical name and where the database is. */
+export interface DatabaseConnectionConfig {
+    /** The logical connection name, as declared in `hfs.json`. */
+    readonly name: string
+    /** The connection URL; it may embed credentials. */
+    readonly url: Secret
+}
+
+/** One connection as the app composes it: its config plus the entities and migrations of the owners whose tables it holds. */
+export interface DatabaseConnectionOptions extends DatabaseConnectionConfig {
+    /** Every entity of the connection, concatenated from the owner indexes. */
+    readonly entities: ReadonlyArray<EntityClass>
+    /** Every migration of the connection, concatenated from the owner indexes. */
+    readonly migrations: ReadonlyArray<MigrationClass>
+}
+
+/** Options of the database capability. */
+export interface DatabaseOptions {
+    /** The connections this app opens; one per physical database. */
+    readonly connections: ReadonlyArray<DatabaseConnectionOptions>
+}

package/templates/be/skeleton/src/modules/platform/database/database.port.ts

@@ -0,0 +1,65 @@
+import { injector } from "@modules/platform/composition"
+import type { TypedParameterDecorator } from "@modules/platform/composition"
+import type { DatabaseConnectionOptions, DatabaseOptions } from "./database.options"
+import type { SqlText } from "./database.sql"
+import type { SeedFile } from "./seed-connections.client"
+
+/** One applied migration, as the data source answers it. */
+export interface AppliedMigration {
+    /** The migration class name. */
+    readonly name: string
+}
+
+/**
+ * The data source of one connection as a one-off action drives it: initialized, migrated or seeded, then destroyed. A typeorm
+ * `DataSource` is one; the cli commands depend on this port alone.
+ */
+export interface ConnectionSource {
+    /** Opens the pool. */
+    initialize(): Promise<unknown>
+    /** Applies the pending migrations and answers the ones it ran. */
+    runMigrations(): Promise<ReadonlyArray<AppliedMigration>>
+    /** Runs SQL text as written. */
+    query(text: SqlText): Promise<unknown>
+    /** Closes the pool. */
+    destroy(): Promise<void>
+}
+
+/**
+ * The port that opens the data source of one connection, uninitialized; the caller initializes, uses and destroys it.
+ * An object, not a bare function, so a unit spec doubles it with `mock<ConnectionOpener>()`.
+ */
+export interface ConnectionOpener {
+    /** Opens the data source of `connection`, uninitialized. */
+    open(connection: DatabaseConnectionOptions): ConnectionSource
+}
+
+/** Token of the options of the database capability: every connection the app declares, with its entities and migrations. */
+export const DATABASE_OPTIONS: unique symbol = Symbol("platform.database.options")
+
+/** Token of the port that opens the data source of one connection. */
+export const CONNECTION_SOURCE: unique symbol = Symbol("platform.database.connection-source")
+
+/** Injects the options of the database capability. Parameter type: DatabaseOptions. */
+export const InjectDatabaseOptions = (): TypedParameterDecorator<DatabaseOptions> =>
+    injector<DatabaseOptions>(DATABASE_OPTIONS)
+
+/** Injects the port that opens the data source of one connection. Parameter type: ConnectionOpener. */
+export const InjectConnectionSource = (): TypedParameterDecorator<ConnectionOpener> =>
+    injector<ConnectionOpener>(CONNECTION_SOURCE)
+
+/**
+ * The port that reads the seed files of a directory. An object, not a bare function, so a unit spec doubles it with
+ * `mock<SeedFileReader>()`.
+ */
+export interface SeedFileReader {
+    /** Reads every seed file of `directory`, sorted by name. */
+    read(directory: string): Promise<ReadonlyArray<SeedFile>>
+}
+
+/** Token of the port that reads the seed files of a directory. */
+export const READ_SEED_FILES: unique symbol = Symbol("platform.database.read-seed-files")
+
+/** Injects the port that reads the seed files of a directory. Parameter type: SeedFileReader. */
+export const InjectReadSeedFiles = (): TypedParameterDecorator<SeedFileReader> =>
+    injector<SeedFileReader>(READ_SEED_FILES)

package/templates/be/skeleton/src/modules/platform/database/database.sql.ts

@@ -0,0 +1,47 @@
+import { DatabaseError, DatabaseErrorCode } from "./errors/database.error"
+
+declare const sqlTextBrand: unique symbol
+declare const sqlIdentBrand: unique symbol
+
+/** SQL text built by the `sql` tag: the only kind of string `EntityManager.query` accepts. */
+export type SqlText = string & { readonly [sqlTextBrand]: true }
+
+/** A checked identifier (table or column name): the only value a `sql` tag substitution accepts. */
+export type SqlIdent = string & { readonly [sqlIdentBrand]: true }
+
+/** The biggest page a client can ask for. */
+export const PAGE_SIZE_MAX = 100
+
+/** The biggest number of rows a server-side list read returns. */
+export const LIST_ROWS_MAX = 500
+
+/** The size of the keyset batches a background scan reads. */
+export const BATCH_ROWS = 500
+
+const IDENT_PATTERN = /^[a-z_][a-z0-9_]*$/
+
+function assertSqlText(_value: string): asserts _value is SqlText {
+    // The brand is compile-time only; the `sql` tag and `seedText` are its callers.
+}
+
+function assertSqlIdent(_value: string): asserts _value is SqlIdent {
+    // The brand is compile-time only; `ident` is the single caller, after it checked the name.
+}
+
+/**
+ * Builds SQL text. Values are `$n` parameters written in the text; the only substitutions are `SqlIdent` values, so a
+ * value can never be concatenated into a statement.
+ */
+{{> be/common/sql-tag.ts.partial}}
+
+/** Checks a dynamic identifier against the names the caller allows and brands it; anything else is refused. */
+{{> be/common/sql-ident.ts.partial}}
+
+/**
+ * Brands the statements of one tracked seed file (`.starcistacks/<env>/seeds/<connection>-<name>.sql`) as SQL text. A seed file
+ * is source reviewed like a migration and run as written by the cli seed command; no value is ever spliced into it.
+ */
+export const seedText = (text: string): SqlText => {
+    assertSqlText(text)
+    return text
+}

package/templates/be/skeleton/src/modules/platform/database/errors/database.error.ts

@@ -0,0 +1,16 @@
+import { DomainError } from "@modules/platform/errors"
+import type { ErrorKind } from "@modules/platform/errors"
+
+/** Codes of the database capability. */
+export enum DatabaseErrorCode {
+    /** A dynamic SQL identifier was not on the list of names its caller allows. */
+    IdentifierRejected = "DATABASE_IDENTIFIER_REJECTED",
+}
+
+/** How each database code travels. */
+export const DATABASE_ERROR_KINDS: Record<DatabaseErrorCode, ErrorKind> = {
+    [DatabaseErrorCode.IdentifierRejected]: "internal",
+}
+
+/** The one error class of the database capability. */
+export class DatabaseError extends DomainError<DatabaseErrorCode> {}

package/templates/be/skeleton/src/modules/platform/database/index.ts

@@ -0,0 +1,9 @@
+export { DatabaseModule } from "./database.module"
+export { MigrationRunnerService } from "./migration-runner.service"
+export { DEFAULT_SEED_ENV } from "./seed-connections.client"
+export { SeedRunnerService } from "./seed-runner.service"
+export type { DatabaseConnectionConfig, DatabaseConnectionOptions } from "./database.options"
+export { LIST_ROWS_MAX, sql } from "./database.sql"
+export { DATABASE_ERROR_KINDS } from "./errors/database.error"
+export { parsePrimaryDatabaseConfig } from "./primary.config"
+export { InjectPrimaryEntityManager, PRIMARY_ENTITY_MANAGER } from "./primary.decorators"

package/templates/be/skeleton/src/modules/platform/database/migrate-connections.client.ts

@@ -0,0 +1,30 @@
+import type { DatabaseConnectionOptions } from "./database.options"
+import type { ConnectionOpener } from "./database.port"
+
+/** What a migrate run applied: the migration names it ran, by connection. */
+export interface AppliedMigrations {
+    /** The names of the migrations run on the connection, in the order they ran. */
+    readonly [connection: string]: ReadonlyArray<string>
+}
+
+/**
+ * Applies the pending migrations of every connection in turn and answers the names it ran, by connection. The one runner of the
+ * schema: the cli migrate command runs it, and a test world runs it over the same connections.
+ */
+export async function migrateConnections(
+    connections: ReadonlyArray<DatabaseConnectionOptions>,
+    opener: ConnectionOpener,
+): Promise<AppliedMigrations> {
+    const applied: Record<string, ReadonlyArray<string>> = {}
+    for (const connection of connections) {
+        const source = opener.open(connection)
+        await source.initialize()
+        try {
+            const ran = await source.runMigrations()
+            applied[connection.name] = ran.map((migration) => migration.name)
+        } finally {
+            await source.destroy()
+        }
+    }
+    return applied
+}

package/templates/be/skeleton/src/modules/platform/database/migration-runner.service.spec.ts

@@ -0,0 +1,84 @@
+import { mock } from "@starci/jest-preset"
+import { Test } from "@nestjs/testing"
+import { Secret } from "@modules/platform/config"
+import { LOGGER, LoggingLogEvent } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { CONNECTION_SOURCE, DATABASE_OPTIONS } from "./database.port"
+import type { ConnectionOpener, ConnectionSource } from "./database.port"
+import type { DatabaseConnectionOptions } from "./database.options"
+import { MigrationRunnerService } from "./migration-runner.service"
+
+const connection = (name: string): DatabaseConnectionOptions => ({
+    name,
+    url: new Secret(`postgres://localhost:5432/${name}`),
+    entities: [],
+    migrations: [],
+})
+
+/** A connection source double whose runMigrations answers `ran`. */
+const source = (ran: ReadonlyArray<string>) => {
+    const double = mock<ConnectionSource>()
+    double.runMigrations.mockResolvedValue(ran.map((name) => ({ name })))
+    return double
+}
+
+const build = async (
+    connections: ReadonlyArray<DatabaseConnectionOptions>,
+    openSource: (target: DatabaseConnectionOptions) => ConnectionSource,
+) => {
+    const logger = mock<Logger>()
+    const opener = mock<ConnectionOpener>()
+    opener.open.mockImplementation((target) => openSource(target))
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            MigrationRunnerService,
+            { provide: DATABASE_OPTIONS, useValue: { connections } },
+            { provide: CONNECTION_SOURCE, useValue: opener },
+            { provide: LOGGER, useValue: logger },
+        ],
+    }).compile()
+    return { runner: moduleRef.get(MigrationRunnerService), logger }
+}
+
+describe("MigrationRunnerService", () => {
+    it("migrates every connection in order and logs the applied names by connection", async () => {
+        const primary = source(["InitNote1"])
+        const archive = source(["InitArchive1", "IndexArchive2"])
+        const sources = new Map([
+            ["primary", primary],
+            ["archive", archive],
+        ])
+        const { runner, logger } = await build(
+            [connection("primary"), connection("archive")],
+            (target) => sources.get(target.name) ?? source([]),
+        )
+
+        await runner.run()
+
+        expect(logger.info).toHaveBeenCalledWith(LoggingLogEvent.MigrationsApplied, {
+            applied: {
+                primary: ["InitNote1"],
+                archive: ["InitArchive1", "IndexArchive2"],
+            },
+        })
+        expect(primary.destroy).toHaveBeenCalledTimes(1)
+        expect(archive.destroy).toHaveBeenCalledTimes(1)
+    })
+
+    it("answers no applied name when there is no connection", async () => {
+        const { runner, logger } = await build([], () => source([]))
+
+        await runner.run()
+
+        expect(logger.info).toHaveBeenCalledWith(LoggingLogEvent.MigrationsApplied, { applied: {} })
+    })
+
+    it("destroys the data source of a connection whose migrations fail, and fails", async () => {
+        const failing = source([])
+        failing.runMigrations.mockRejectedValue(new TypeError("relation exists"))
+        const { runner } = await build([connection("primary")], () => failing)
+
+        await expect(runner.run()).rejects.toThrow("relation exists")
+        expect(failing.destroy).toHaveBeenCalledTimes(1)
+    })
+})

package/templates/be/skeleton/src/modules/platform/database/migration-runner.service.ts

@@ -0,0 +1,23 @@
+import { Injectable } from "@nestjs/common"
+import { InjectLogger, LoggingLogEvent } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { InjectConnectionSource, InjectDatabaseOptions } from "./database.port"
+import type { DatabaseOptions } from "./database.options"
+import type { ConnectionOpener } from "./database.port"
+import { migrateConnections } from "./migrate-connections.client"
+
+@Injectable()
+/** The one migration runner: applies the pending migrations of every connection and logs the names it applied. */
+export class MigrationRunnerService {
+    constructor(
+        @InjectDatabaseOptions() private readonly options: DatabaseOptions,
+        @InjectConnectionSource() private readonly opener: ConnectionOpener,
+        @InjectLogger() private readonly logger: Logger,
+    ) {}
+
+    /** Runs the migrations of every connection and logs the applied names. */
+    async run(): Promise<void> {
+        const applied = await migrateConnections(this.options.connections, this.opener)
+        this.logger.info(LoggingLogEvent.MigrationsApplied, { applied })
+    }
+}

package/templates/be/skeleton/src/modules/platform/database/primary.config.ts

@@ -0,0 +1,9 @@
+import type { EnvSource } from "@modules/platform/config"
+import type { DatabaseConnectionConfig } from "./database.options"
+import { PRIMARY_CONNECTION } from "./primary.connection"
+
+/** Reads the primary connection from the `PRIMARY_DB_*` keys. */
+export const parsePrimaryDatabaseConfig = (env: EnvSource): DatabaseConnectionConfig => ({
+    name: PRIMARY_CONNECTION,
+    url: env.secret("PRIMARY_DB_URL"),
+})

package/templates/be/skeleton/src/modules/platform/database/primary.connection.ts

@@ -0,0 +1,2 @@
+/** The logical name of the primary database connection, as declared in `hfs.json`. */
+export const PRIMARY_CONNECTION = "primary"

package/templates/be/skeleton/src/modules/platform/database/primary.decorators.ts

@@ -0,0 +1,10 @@
+import { injector } from "@modules/platform/composition"
+import type { TypedParameterDecorator } from "@modules/platform/composition"
+import type { EntityManager } from "typeorm"
+
+/** Token of the shared EntityManager of the `primary` database; the database module provides it for the connection it opens. */
+export const PRIMARY_ENTITY_MANAGER: unique symbol = Symbol("platform.database.primary-entity-manager")
+
+/** Injects the shared EntityManager of the `primary` database. Parameter type: EntityManager. */
+export const InjectPrimaryEntityManager = (): TypedParameterDecorator<EntityManager> =>
+    injector<EntityManager>(PRIMARY_ENTITY_MANAGER)