@zerotal/orm 1.8.1 → 1.9.0

package/CHANGELOG.md

@@ -8,6 +8,51 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.9.0] — 2026-08-29
+
+### Changed
+
+- **INTERNAL: 41 framework-wiring exports are marked `@internal`.** The connection and context
+  plumbing (`_getConnection`, `setConnectionResolver`, `useOrmContext`, `createReadWriteRouter`,
+  `registerImplicitBinding`, …), the schema-diff machinery behind `migrate:generate` and
+  `synchronize` (`SchemaDiffer`, `SchemaInspector`, `ModelInspector`, `synchronizeSchema`, and
+  their result shapes), and the dialect layer (`SqliteDialect`, `PostgresDialect`,
+  `MysqlDialect`, `getDialect`).
+
+  **Nothing is removed and nothing breaks** — they are still exported and still work. What
+  changes is the promise: they leave the recorded API surface, because an app never calls any of
+  them, and the only callers outside `@zerotal/orm` are `@zerotal/testing`, `@zerotal/tenancy`
+  and `@zerotal/arch` wiring themselves in.
+
+  Everything an app does use is unaffected, and the parts of it that were undocumented are now
+  documented: the relation types and option shapes in
+  [Relationships](/docs/orm/relationships#types), and the column builders plus `MigrationRunner`
+  in [Migrations](/docs/migrations#types).
+
+- **`doctor` warns when migrations have not run**, and names them. The development error
+  overlay already answers this after a request has failed with `no such table`; the check asks
+  it before anything breaks, which is the cheaper moment to hear it. A warning rather than a
+  failure, because pending migrations are the ordinary state of a checkout that just pulled,
+  and a doctor that fails there is one people learn to ignore.
+
+### Added
+
+- **`zt db:backup`** — a verified snapshot of the SQLite database. SQLite is the default
+  driver, which makes the database one file and makes `cp` look like a backup; it is not one,
+  because copying a live database can capture a half-written page and produce a file that
+  restores as corrupt, months later, from the one file you were relying on. This uses
+  `VACUUM INTO`, which takes a read lock and writes a complete database while the server
+  keeps serving, and needs no `sqlite3` binary on the box.
+
+  Every snapshot is opened and integrity-checked the moment it is written, and every failure
+  path exits non-zero — a backup job that reports success while writing nothing buys the
+  confidence without the file. `--require-rows` names the tables whose loss would end the
+  business and fails when the snapshot has none of them; `--rehearse` performs the actual
+  restore, because a backup nobody has restored is a hope. A snapshot that fails any check is
+  removed rather than left in the retention directory, where it would be indistinguishable
+  from a good one and, being newest, would push a verified older one out on the next prune.
+  Retention (`--keep`) only ever touches files this command wrote.
+
 ## [1.7.4] — 2026-08-21
 
 ### Fixed

package/api-surface.md

@@ -554,22 +554,6 @@ class ModelQueryBuilder = {
   withoutTenancy: () => ModelQueryBuilder<M>
 }
 
-class MysqlDialect = {
-  new (): MysqlDialect
-  advisoryLockSql: (key: number) => DialectQuery
-  advisoryUnlockSql: (key: number) => DialectQuery
-  autoIncrementColumn: (column: string) => string
-  booleanLiteral: (value: boolean) => string
-  dateExpr: (part: DatePart, column: string) => string
-  hasColumnSql: (table: string, column: string) => DialectQuery
-  hasTableSql: (table: string) => DialectQuery
-  readonly booleanType: 'INTEGER'
-  readonly name: 'mysql'
-  readonly supportsAdvisoryLocks: true
-  readonly supportsTransactionalDdl: false
-  stringType: (length: number) => string
-}
-
 class NPlusOneDetected = {
   new (fingerprint: string, count: number, ctx: object | undefined): NPlusOneDetected
   readonly count: number
@@ -587,31 +571,6 @@ class NPlusOneError = {
   readonly status: number
 }
 
-class OrmContext = {
-  new (): OrmContext
-  globalScopes: Map<ClassRef, Map<string, unknown>>
-  hooks: Map<ClassRef, Map<string, unknown[]>>
-  namedConnections: Map<string, SQLInstance>
-  overrideConnection: SQLInstance | null
-  transitionCallbacks: Map<ClassRef, Map<string, unknown[]>>
-}
-
-class PostgresDialect = {
-  new (): PostgresDialect
-  advisoryLockSql: (key: number) => DialectQuery
-  advisoryUnlockSql: (key: number) => DialectQuery
-  autoIncrementColumn: (column: string) => string
-  booleanLiteral: (value: boolean) => string
-  dateExpr: (part: DatePart, column: string) => string
-  hasColumnSql: (table: string, column: string) => DialectQuery
-  hasTableSql: (table: string) => DialectQuery
-  readonly booleanType: 'BOOLEAN'
-  readonly name: 'postgres'
-  readonly supportsAdvisoryLocks: true
-  readonly supportsTransactionalDdl: true
-  stringType: () => string
-}
-
 class QueryBuilder = {
   new (table: string, sql: SQLInstance): QueryBuilder
   _markUserWhereStart: () => void
@@ -736,22 +695,6 @@ class Seeder = {
   run: () => Promise<void>
 }
 
-class SqliteDialect = {
-  new (): SqliteDialect
-  advisoryLockSql: () => DialectQuery | null
-  advisoryUnlockSql: () => DialectQuery | null
-  autoIncrementColumn: (column: string) => string
-  booleanLiteral: (value: boolean) => string
-  dateExpr: (part: DatePart, column: string) => string
-  hasColumnSql: (table: string, column: string) => DialectQuery
-  hasTableSql: (table: string) => DialectQuery
-  readonly booleanType: 'INTEGER'
-  readonly name: 'sqlite'
-  readonly supportsAdvisoryLocks: false
-  readonly supportsTransactionalDdl: true
-  stringType: () => string
-}
-
 class StateError = {
   new (model: string, from: string, to: string, detail?: string): StateError
   readonly code: string
@@ -796,30 +739,12 @@ class UnsupportedDialectError = {
 
 const DB = {    table(tableName: string): QueryBuilder;    raw<T = Record<string, unknown>>(sql: TemplateStringsArray | string, ...rest: unknown[]): Promise<T[]>;    transaction<T>(callback: (tx?: SQLInstance) => Promise<T>, attempts?: number): Promise<T>;    beginTransaction(): Promise<ManualTransaction>;    onPrimary(): {        table(name: string): QueryBuilder;    };    currentTx(): unknown | undefined;    advisoryLock<T>(key: number, callback: () => Promise<T>): Promise<T>;    preventNPlusOne(options?: NPlusOneOptions): void;    allowNPlusOne(pattern: string, options?: {        once?: boolean;    }): void;}
 
-const ModelInspector = {    load(pattern: string, cwd?: string): Promise<void>;    all(): ModelSchema[];    fromClass(ctor: ClassRef): ModelSchema | null;}
-
 const relationRegistry = Map<ClassRef, Map<string, RelationMetadata>>
 
 const Schema = {    create(table: string, callback: (bp: Blueprint) => void): Promise<void>;    createIfNotExists(table: string, callback: (bp: Blueprint) => void): Promise<void>;    table(name: string, callback: (bp: Blueprint) => void): Promise<void>;    alter(name: string, callback: (bp: Blueprint) => void): Promise<void>;    drop(table: string): Promise<void>;    dropIfExists(table: string): Promise<void>;    rename(from: string, to: string): Promise<void>;    hasTable(table: string): Promise<boolean>;    hasColumn(table: string, column: string): Promise<boolean>;}
 
-const SchemaDiffer = {    diff(schemas: ModelSchema[]): Promise<DiffResult>;    isEmpty(diff: DiffResult): boolean;}
-
-const SchemaInspector = {    tables(): Promise<string[]>;    columns(table: string): Promise<LiveColumn[] | null>;    describe(table: string): Promise<LiveTable | null>;}
-
 const TransactionContext = AsyncLocalStorage<SQLInstance>
 
-function _getConnection = () => SQLInstance
-
-function _getDbConnectionOverride = () => SQLInstance | null
-
-function _globalScopeRegistry = () => Map<ClassRef, Map<string, GlobalScopeCallback>>
-
-function _setDbConnection = (conn: SQLInstance | null) => void
-
-function _setReadReplicas = (primary: SQLInstance, replicas: SQLInstance[]) => void
-
-function _suppressHooks = <T>(fn: () => Promise<T>) => Promise<T>
-
 function allowNPlusOne = (pattern: string, options?: {    once?: boolean;}, ctx?: object | null) => void
 
 function arrayOf = <T = unknown>(mapper?: CastMapper<T>) => ArrayCast<T>
@@ -828,16 +753,8 @@ function belongsTo = (related: () => unknown, options: BelongsToOptions) => (_va
 
 function column = {    (): ColumnDecorator;    (type: ColumnShorthand): ColumnDecorator;    (options: ColumnOptions): ColumnDecorator;    (type: ColumnShorthand, options: Omit<ColumnOptions, 'type'>): ColumnDecorator;}
 
-function createReadWriteRouter = (primary: SQLInstance, replicas: SQLInstance[]) => SQLInstance
-
-function currentOrmContext = () => OrmContext
-
 function DatabaseConfig = (options?: Partial<DatabaseConfigShape>) => DatabaseConfigShape
 
-function generateMigrationContent = (className: string, diff: DiffResult) => string
-
-function getDialect = (name: DialectName) => SqlDialect
-
 function hasMany = (related: () => unknown, options: HasManyOptions) => (_value: unknown, context: ClassFieldDecoratorContext) => void
 
 function hasManyThrough = (related: () => unknown, through: () => unknown, options: HasManyThroughOptions) => (_value: unknown, context: ClassFieldDecoratorContext) => void
@@ -846,8 +763,6 @@ function hasOne = (related: () => unknown, options: HasOneOptions) => (_value: u
 
 function hasOneThrough = (related: () => unknown, through: () => unknown, options: HasManyThroughOptions) => (_value: unknown, context: ClassFieldDecoratorContext) => void
 
-function installOrmObservability = (app: Application) => () => void
-
 function isEncryptedCast = (cast: unknown) => cast is EncryptedCastName
 
 function json = <T = unknown>(mapper?: CastMapper<T>) => JsonCast<T>
@@ -868,30 +783,12 @@ function objectOf = <T = unknown>(mapper?: CastMapper<T>) => JsonCast<T>
 
 function preventNPlusOne = (options?: NPlusOneOptions) => void
 
-function registerConnectionResolver = (fn: ContextConnectionResolver | null) => void
-
-function registerImplicitBinding = () => void
-
-function registerModelConnection = (name: string, conn: SQLInstance, dialect?: Dialect) => void
-
-function resetOrmContext = () => void
-
-function resolveContainerConnection = () => SQLInstance | undefined
-
-function resolveSyncOptions = (raw: unknown) => ResolvedSyncOptions
-
-function setConnectionResolver = (fn: ConnectionResolver | null) => void
-
 function SoftDeletes = <TBase extends Constructor>(Base: TBase) => {    new (...args: any[]): SoftDeletes;    prototype: SoftDeletes<any>.SoftDeletes;    softDeletes: boolean;    withTrashed<T extends BaseModel>(this: SoftDeleteModelClass<T>): ModelQueryBuilder<T>;    onlyTrashed<T extends BaseModel>(this: SoftDeleteModelClass<T>): ModelQueryBuilder<T>;} & TBase
 
 function State = <TBase extends Constructor>(Base: TBase) => {    new (...args: any[]): State;    prototype: State<any>.State;    stateField: string;    states?: Record<string, StateDefinition<string, any>>;    onTransition<T>(this: {        new (...args: any[]): T;    }, toState: string, callback: TransitionCallback<T>): void;} & TBase
 
-function synchronizeSchema = (options?: SynchronizeOptions) => Promise<DiffResult>
-
 function table = (tableName: string, options?: TableOptions) => TableDecoratorBuilder
 
-function useOrmContext = (ctx?: OrmContext) => OrmContext
-
 interface BelongsTo = {
   __@___relation__: 'belongsTo'
   __type__: T
@@ -946,22 +843,6 @@ interface DatabaseConfigShape = {
   url: string
 }
 
-interface DialectQuery = {
-  params: unknown[]
-  sql: string
-}
-
-interface DiffResult = {
-  droppedColumns: DroppedColumn[]
-  newColumns: NewColumn[]
-  newTables: NewTable[]
-}
-
-interface DroppedColumn = {
-  column: string
-  table: string
-}
-
 interface HasMany = {
   __@___relation__: 'hasMany'
   __type__: T
@@ -991,18 +872,6 @@ interface KeysetPaginateResult = {
   nextCursor: string | null
 }
 
-interface LiveColumn = {
-  name: string
-  nullable: boolean
-  primary: boolean
-  rawType: string
-}
-
-interface LiveTable = {
-  columns: LiveColumn[]
-  name: string
-}
-
 interface ManualTransaction = {
   commit: () => Promise<void>
   readonly sql: SQLInstance
@@ -1047,16 +916,6 @@ interface MigrationStatus = {
   ranAt?: Date
 }
 
-interface ModelColumn = {
-  default: unknown
-  index?: boolean
-  name: string
-  nullable: boolean
-  primary: boolean
-  type: 'string' | 'number' | 'boolean' | 'text' | 'datetime' | 'json' | undefined
-  unique?: boolean
-}
-
 interface ModelObserver = {
   created?: (model: T) => Promise<void> | void
   creating?: (model: T) => Promise<void> | void
@@ -1069,14 +928,6 @@ interface ModelObserver = {
   updating?: (model: T) => Promise<void> | void
 }
 
-interface ModelSchema = {
-  columns: ModelColumn[]
-  primaryKey: string
-  softDeletes: boolean
-  table: string
-  timestamps: boolean
-}
-
 interface MorphedByManyOptions = {
   morphName: string
   parentPivotKey: string
@@ -1124,15 +975,6 @@ interface MorphToOptions = {
   morphTypeColumn?: string
 }
 
-interface NewColumn = {
-  column: ModelColumn
-  table: string
-}
-
-interface NewTable = {
-  schema: ModelSchema
-}
-
 interface NPlusOneOptions = {
   mode?: 'warn' | 'throw'
   threshold?: number
@@ -1189,11 +1031,6 @@ interface RelationMetadata = {
   withDefault?: boolean | Record<string, unknown> | ((model: unknown) => void)
 }
 
-interface ResolvedSyncOptions = {
-  disruptive: boolean
-  enabled: boolean
-}
-
 interface ScopeApplicator = {
   apply: (query: QueryBuilder) => void
 }
@@ -1211,21 +1048,6 @@ interface SimplePaginateResult = {
   url: (page: number, baseUrl?: string, query?: Record<string, string>) => string
 }
 
-interface SqlDialect = {
-  advisoryLockSql: (key: number) => DialectQuery | null
-  advisoryUnlockSql: (key: number) => DialectQuery | null
-  autoIncrementColumn: (column: string) => string
-  booleanLiteral: (value: boolean) => string
-  dateExpr: (part: DatePart, column: string) => string
-  hasColumnSql: (table: string, column: string) => DialectQuery
-  hasTableSql: (table: string) => DialectQuery
-  readonly booleanType: string
-  readonly name: DialectName
-  readonly supportsAdvisoryLocks: boolean
-  readonly supportsTransactionalDdl: boolean
-  stringType: (length: number) => string
-}
-
 interface SQLInstance = {
   <T = Record<string, unknown>>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T[]>
   begin: <T>(fn: (tx: SQLInstance) => Promise<T>) => Promise<T>
@@ -1237,10 +1059,6 @@ interface StateDefinition = {
   guard?: StateGuard<T>
 }
 
-interface SynchronizeOptions = {
-  disruptive?: boolean
-}
-
 interface TableDecoratorBuilder = {
   (target: ClassRef, context?: unknown): void
   primaryKey: (key: string) => TableDecoratorBuilder
@@ -1267,12 +1085,8 @@ type ColumnShorthand = 'string' | 'text' | 'integer' | 'number' | 'float' | 'boo
 
 type Constructor = new (...args: any[]) => T
 
-type ContextConnectionResolver = (ModelClass?: typeof BaseModel) => SQLInstance | null
-
 type DatePart = 'date' | 'time' | 'day' | 'month' | 'year'
 
-type DialectName = 'sqlite' | 'postgres' | 'mysql'
-
 type EncryptedCastName = 'encrypted' | 'encrypted:json'
 
 type FKAction = 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/orm",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -31,8 +31,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.8.1",
-    "@zerotal/validator": "1.8.1"
+    "@zerotal/core": "1.9.0",
+    "@zerotal/validator": "1.9.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0"

package/src/commands/DbBackupCommand.ts

@@ -0,0 +1,143 @@
+import { Command, type FlagDef } from "@zerotal/core";
+import type { ConfigManager } from "@zerotal/core/config";
+import { _rawStatement } from "../db/DB.ts";
+import { takeBackup, BackupError, type BackupResult } from "./_backup.ts";
+
+/**
+ * `bun zt db:backup` — take a verified snapshot of the SQLite database.
+ *
+ * SQLite is the framework's default, and `migrate`, `migrate:fresh` and `db:seed`
+ * all assume the file will be there. This is the command that makes that
+ * assumption survivable. It uses `VACUUM INTO`, which is safe to run against a
+ * database the server is still writing to, then opens what it wrote and checks it
+ * before saying the word "backed up".
+ *
+ * It exits non-zero on every failure, so a systemd timer that wraps it leaves a
+ * failed unit somebody can see. That is deliberate and it is the whole design: a
+ * backup job that prints a problem and exits 0 buys the confidence without the
+ * file, which is worse than having no job at all.
+ *
+ * @example
+ * ```bash
+ * bun zt db:backup
+ * bun zt db:backup --dir=/var/backups/app --keep=30
+ * bun zt db:backup --require-rows=bookings,invoices     # nightly
+ * bun zt db:backup --rehearse --require-rows=bookings   # weekly
+ * ```
+ *
+ * @category Database
+ */
+export class DbBackupCommand extends Command {
+  static commandName = "db:backup";
+  static description = "Take a verified snapshot of the SQLite database";
+  static needsApp = true;
+
+  /** Where snapshots go when nothing says otherwise. */
+  static readonly DEFAULT_DIR = "storage/backups";
+
+  /**
+   * Snapshots kept by default.
+   *
+   * Two weeks: long enough that corruption introduced on a Friday is still
+   * recoverable after somebody notices it on the following Monday week, short
+   * enough that nobody turns retention off to reclaim a disk.
+   */
+  static readonly DEFAULT_KEEP = 14;
+
+  static flags: FlagDef[] = [
+    {
+      name: "dir",
+      type: "string",
+      description: `Directory to write snapshots into (default ${DbBackupCommand.DEFAULT_DIR})`,
+      default: DbBackupCommand.DEFAULT_DIR,
+    },
+    {
+      name: "keep",
+      type: "number",
+      description: `Snapshots to keep, newest first; 0 keeps every one (default ${DbBackupCommand.DEFAULT_KEEP})`,
+      default: DbBackupCommand.DEFAULT_KEEP,
+    },
+    {
+      name: "require-rows",
+      type: "string",
+      description:
+        "Comma-separated tables that must not be empty in the snapshot, e.g. bookings,invoices",
+      default: "",
+    },
+    {
+      name: "rehearse",
+      type: "boolean",
+      description: "Also perform the restore: copy the snapshot, open the copy, and check it",
+      default: false,
+    },
+  ];
+
+  async run(): Promise<void> {
+    const dir = String(this.flags["dir"] ?? DbBackupCommand.DEFAULT_DIR);
+    const keep = Number(this.flags["keep"] ?? DbBackupCommand.DEFAULT_KEEP);
+    const requireRows = String(this.flags["require-rows"] ?? "")
+      .split(",")
+      .map((t) => t.trim())
+      .filter(Boolean);
+    const rehearse = this.flags["rehearse"] === true;
+
+    const source = this.#databaseUrl();
+
+    this.section("Database backup");
+    this.dim(`source     ${source}`);
+    this.dim(`directory  ${dir}`);
+    this.dim(`keep       ${keep === 0 ? "all" : keep}`);
+
+    let result: BackupResult;
+    try {
+      result = await takeBackup((sql) => _rawStatement(sql), {
+        source,
+        dir,
+        keep,
+        requireRows,
+        rehearse,
+      });
+    } catch (error) {
+      // Rethrown, not printed. The runner turns a throw into a non-zero exit, and
+      // a non-zero exit is the only part of this a timer can act on.
+      if (error instanceof BackupError) throw error;
+      throw new BackupError(`Backup failed: ${(error as Error).message}`);
+    }
+
+    this.newLine();
+    this.info(`Wrote ${result.path}`);
+    const rows: [string, string][] = [
+      ["size", `${(result.bytes / 1024 / 1024).toFixed(2)} MB`],
+      ["tables", String(result.tables.length)],
+      ["integrity", "ok"],
+    ];
+    for (const [table, count] of Object.entries(result.rows)) {
+      rows.push([`rows in ${table}`, String(count)]);
+    }
+    rows.push(["restore rehearsed", result.rehearsed ? "yes" : "no (pass --rehearse)"]);
+    if (result.pruned.length > 0) {
+      rows.push(["pruned", `${result.pruned.length} older snapshot(s)`]);
+    }
+    this.table(rows);
+
+    if (requireRows.length === 0) {
+      this.newLine();
+      this.warn(
+        "Nothing was asserted about the contents. Pass --require-rows with the tables " +
+          "whose loss would end the business, so an empty snapshot fails here.",
+      );
+    }
+  }
+
+  /** The configured database URL, or `:memory:` when there is no config to read. */
+  #databaseUrl(): string {
+    try {
+      const config = (
+        this.app as { container: { makeSync(k: string): unknown } }
+      ).container.makeSync("config") as ConfigManager;
+      return config.get<string>("database.url", ":memory:");
+    } catch {
+      return ":memory:";
+    }
+  }
+}