@db3.ai/app 0.1.0-beta.1

package/dist/db/Database.d.ts

@@ -0,0 +1,277 @@
+import type { Knex } from 'knex';
+import type { ActiveRecord, ActiveRecordClass } from './ActiveRecord.js';
+import type * as database from './contracts/index.js';
+import { DatabaseMigrationManager } from './migrations/DatabaseMigrationManager.js';
+import { type DatabaseDialect } from './dialects/index.js';
+import type { DbSchemaPart } from './FieldType.js';
+import { type QueryMonitor, type QueryMonitorOptions } from './queryMonitor.js';
+/** App-owned model registry and policies for migrations, query monitoring and schema synchronization. */
+export interface DatabaseOptions {
+    /** Model registry and policy for migrations under the app's server/database directory. */
+    migrations?: database.DatabaseMigrationsConfig;
+    /**
+     * Configures query telemetry for this database connection.
+     */
+    queryMonitor?: false | QueryMonitorOptions;
+    /**
+     * Whether `install()` should add missing model columns and relax existing
+     * columns that are now nullable or safely wider.
+     */
+    syncColumns?: boolean;
+    /**
+     * Whether `install()` should add missing model indexes to existing tables.
+     */
+    syncIndexes?: boolean;
+    /**
+     * Reports schema differences left after `install()` runs safe sync steps.
+     * Defaults to `warn`; set false to silence or pass a custom reporter.
+     */
+    reportSchemaDiff?: DatabaseSchemaDiffReporter;
+}
+export interface DatabaseInstallOptions {
+    /**
+     * Per-install override for adding missing model columns to existing tables.
+     */
+    syncColumns?: boolean;
+    /**
+     * Per-install override for adding missing model indexes to existing tables.
+     */
+    syncIndexes?: boolean;
+    /**
+     * Per-install override for reporting remaining schema differences.
+     */
+    reportSchemaDiff?: DatabaseSchemaDiffReporter;
+}
+export type DatabaseSchemaDifferenceKind = 'missing_table' | 'missing_column' | 'missing_index' | 'type_mismatch' | 'nullable_mismatch';
+export type DatabaseSchemaDiffReporter = false | 'warn' | ((diffs: DatabaseSchemaDiff[], database: Database) => void | Promise<void>);
+export interface DatabaseSchemaDifference {
+    kind: DatabaseSchemaDifferenceKind;
+    table: string;
+    column?: string;
+    index?: string;
+    columns?: string[];
+    databaseValue?: unknown;
+    modelValue?: unknown;
+    rowsWithNull?: number;
+    blocked?: boolean;
+    message: string;
+}
+export interface DatabaseSchemaDiff {
+    model: string;
+    table: string;
+    differences: DatabaseSchemaDifference[];
+}
+/**
+ * App-facing database service.
+ *
+ * This gathers database operations that do not really belong on an individual
+ * record instance, while keeping the existing ActiveRecord model definitions.
+ */
+export declare class Database {
+    #private;
+    private readonly connection;
+    private readonly options;
+    private readonly monitor;
+    /**
+     * Returns migrations from the application's conventional server/database paths.
+     * @returns Lazy migration manager shared by commands, tests and application operations.
+     * @throws When the app has not supplied dbOptions.migrations.
+     */
+    get migrations(): DatabaseMigrationManager;
+    /**
+     * Creates a database service and captures its application directory once.
+     * @param connection - Connection owned by the application or its caller.
+     * @param options - Model registry, migration policy and schema/query settings.
+     * @param directory - App root supplied by App; standalone services default to the current directory.
+     */
+    constructor(connection: Knex, options?: DatabaseOptions, directory?: string);
+    /**
+     * Collects database schema metadata from every field on a model.
+     */
+    static getSchema<TRecord extends ActiveRecord>(Model: ActiveRecordClass<TRecord>, dialect?: DatabaseDialect): Required<DbSchemaPart>;
+    /**
+     * Returns the raw Knex connection for low-level database work.
+     */
+    get knex(): Knex;
+    /**
+     * Returns the query monitor attached to this connection, when enabled.
+     */
+    get queryMonitor(): QueryMonitor | null;
+    /**
+     * Configures the application-owned implementation used by `backup()`.
+     *
+     * @param handler - Function that creates and persists one database backup.
+     * @returns This database service for fluent application wiring.
+     */
+    setBackupHandler(handler: database.DatabaseBackupHandler): this;
+    /**
+     * Creates a database backup through the active application's backup policy.
+     *
+     * @param request - Durable, JSON-safe metadata identifying the backup request.
+     * @returns Application-defined backup result, such as a completed manifest.
+     *
+     * @example
+     * const manifest = await app().db.backup<DatabaseBackupManifest>({
+     * 	backupId,
+     * 	createdAt,
+     * 	trigger: 'manual',
+     * });
+     */
+    backup<TResult = unknown>(request: Record<string, unknown>): Promise<TResult>;
+    /**
+     * Starts a raw Knex query against a table.
+     */
+    table<TRecord extends {} = any, TResult = TRecord[]>(tableName: string): Knex.QueryBuilder<TRecord, TResult>;
+    /**
+     * Creates database tables for one or more ActiveRecord models.
+     */
+    install(...models: ActiveRecordClass[]): Promise<void>;
+    install(options: DatabaseInstallOptions, ...models: ActiveRecordClass[]): Promise<void>;
+    /**
+     * Compares model schema metadata with the live database without changing it.
+     *
+     * This intentionally reports a small, high-signal subset instead of trying to
+     * be a migration planner.
+     */
+    diff(...models: ActiveRecordClass[]): Promise<DatabaseSchemaDiff[]>;
+    /**
+     * Renders schema diffs for logs or CLI output.
+     */
+    formatDiff(diffs: DatabaseSchemaDiff[]): string;
+    /**
+     * Collects database schema metadata from every field on a model.
+     */
+    getSchema<TRecord extends ActiveRecord>(Model: ActiveRecordClass<TRecord>): Required<DbSchemaPart>;
+    /**
+     * Runs work inside a transaction and exposes the transaction as a Database.
+     */
+    transaction<TResult>(callback: (db: Database) => Promise<TResult>): Promise<TResult>;
+    /**
+     * Installs or safely synchronizes one ActiveRecord model.
+     *
+     * Existing column and index metadata is loaded once and shared by every
+     * synchronization step. The return value records whether the initial schema
+     * may have contained a reportable difference that should be checked after
+     * synchronization.
+     *
+     * @param Model - ActiveRecord model whose schema should be installed.
+     * @param options - Per-install synchronization options.
+     * @param currentTableComment - Existing database comment for this table.
+     * @returns Whether a post-install diff may still be useful.
+     */
+    private installModel;
+    /**
+     * Synchronizes a model-owned table comment only when its value changed.
+     *
+     * @param tableName - Existing database table name.
+     * @param comment - Normalized comment declared by the model.
+     * @param currentComment - Comment currently stored by the database.
+     * @returns Promise that resolves when any required comment change completes.
+     */
+    private syncTableComment;
+    /**
+     * Resolves whether model columns should be synchronized for this install.
+     *
+     * @param options - Per-install overrides.
+     * @returns Whether safe column synchronization is enabled.
+     */
+    private shouldSyncColumns;
+    /**
+     * Resolves whether model indexes should be synchronized for this install.
+     *
+     * @param options - Per-install overrides.
+     * @returns Whether missing-index synchronization is enabled.
+     */
+    private shouldSyncIndexes;
+    /**
+     * Adds model columns missing from an existing table.
+     *
+     * @param tableName - Existing database table name.
+     * @param schema - Current model schema.
+     * @param columnInfo - Column metadata captured before synchronization.
+     * @returns Names of columns added during this synchronization pass.
+     */
+    private syncMissingColumns;
+    /**
+     * Relaxes existing columns that are optional in the current model.
+     *
+     * @param tableName - Existing database table name.
+     * @param schema - Current model schema.
+     * @param columnInfo - Column metadata captured before synchronization.
+     * @returns Promise that resolves when nullable columns are synchronized.
+     */
+    private syncNullableColumns;
+    /**
+     * Widens existing non-indexed string columns required by text model fields.
+     *
+     * @param tableName - Existing database table name.
+     * @param schema - Current model schema.
+     * @param installedSchema - Column and index metadata captured before sync.
+     * @returns Promise that resolves when safe text widening completes.
+     */
+    private syncWidenedTextColumns;
+    /**
+     * Adds model indexes missing from an existing table.
+     *
+     * Indexes involving columns added in this pass are skipped here because
+     * `syncMissingColumns()` creates them alongside those columns.
+     * Each remaining index is installed separately so a concurrent application
+     * process can win the same synchronization race without preventing later
+     * indexes from being considered. A failed addition is accepted only when a
+     * fresh schema read confirms that the required index now exists.
+     *
+     * @param tableName - Existing database table name.
+     * @param schema - Current model schema.
+     * @param installedSchema - Column and index metadata captured before sync.
+     * @param addedColumnNames - Columns created earlier in this install pass.
+     * @returns Promise that resolves when missing indexes are synchronized.
+     */
+    private syncMissingIndexes;
+    private countRowsWithNull;
+    /**
+     * Loads reusable column and index metadata for one existing table.
+     *
+     * @param tableName - Existing database table name.
+     * @returns Column and index metadata used by every synchronization step.
+     */
+    private installedTableSchema;
+    /**
+     * Detects whether an existing table may need a post-install schema report.
+     *
+     * This mirrors the inexpensive metadata checks used by `diff()` without
+     * running row-count queries. A fully synchronized table can therefore skip
+     * the second complete inspection previously performed after every install.
+     *
+     * @param tableName - Existing database table name.
+     * @param schema - Current model schema.
+     * @param installedSchema - Reusable live table metadata.
+     * @returns Whether the initial table shape contained a potential difference.
+     */
+    private tableHasPotentialDiff;
+    /**
+     * Reads existing comments for models that declare table comments.
+     *
+     * @param models - Models participating in this install pass.
+     * @returns Existing comments keyed by database table name.
+     */
+    private tableCommentsFor;
+    /**
+     * Reads normalized index metadata for one table through the active dialect.
+     *
+     * @param tableName - Existing database table name.
+     * @returns Normalized primary, unique, normal, and vector indexes.
+     */
+    private getTableIndexes;
+    /**
+     * Reports schema differences that may remain after safe synchronization.
+     *
+     * @param models - Models whose pre-install metadata contained differences.
+     * @param options - Per-install reporting options.
+     * @returns Promise that resolves after reporting completes.
+     */
+    private reportDiffAfterInstall;
+    /**
+     * Returns the dialect associated with this database connection.
+     */
+    private dialect;
+}