@db3.ai/app 0.1.0-beta.1

package/src/db/commands/makeMigration.ts

@@ -0,0 +1,11 @@
+import { app } from '../../server';
+import type { MakeMigrationOptions, MakeMigrationResult } from '../migrations/contracts';
+
+/**
+ * Generates reviewable migration source from the active app's model changes.
+ * @param options - Optional name and explicitly requested source-generation policy.
+ * @returns Generated source location or blocked changes; production restrictions remain enforced.
+ */
+export default async function makeMigration(options: MakeMigrationOptions = {}): Promise<MakeMigrationResult> {
+	return app().db.migrations.makeMigration(options);
+}

package/src/db/commands/migrate.ts

@@ -0,0 +1,10 @@
+import { app } from '../../server';
+import type { MigrateResult } from '../migrations/contracts';
+
+/**
+ * Applies the active app's committed pending migrations and returns their results.
+ * @returns Applied and baselined filenames without terminal formatting.
+ */
+export default async function migrate(): Promise<MigrateResult> {
+	return app().db.migrations.migrate();
+}

package/src/db/connection.ts

@@ -0,0 +1,68 @@
+import 'dotenv/config';
+import knex, { type Knex } from 'knex';
+import {
+	rememberDatabaseDialect,
+	resolveDatabaseDialect,
+	type DatabaseDialect,
+} from './dialects';
+
+let database: Knex | null = null;
+
+/**
+ * Reads a required environment variable for database connection setup.
+ */
+function requiredEnv(name: string): string {
+	const value = process.env[name];
+
+	if (!value) {
+		throw new Error(`Missing required database environment variable ${name}.`);
+	}
+
+	return value;
+}
+
+/**
+ * Builds a Knex connection value from the current process environment.
+ */
+function databaseConnection(dialect: DatabaseDialect): Knex.Config['connection'] {
+	if (process.env.DATABASE_URL) return process.env.DATABASE_URL;
+
+	return {
+		host: process.env.DB_HOST || '127.0.0.1',
+		port: Number(process.env.DB_PORT || dialect.defaultPort),
+		user: process.env.DB_USER || 'root',
+		password: process.env.DB_PASSWORD || '',
+		database: requiredEnv('DB_DATABASE'),
+	};
+}
+
+/**
+ * Returns the shared application database connection.
+ */
+export function db(): Knex {
+	if (!database) {
+		const dialect = resolveDatabaseDialect();
+
+		database = knex({
+			client: dialect.knexClient,
+			connection: databaseConnection(dialect),
+			pool: {
+				min: Number(process.env.DB_POOL_MIN || 0),
+				max: Number(process.env.DB_POOL_MAX || 10),
+			},
+		});
+		rememberDatabaseDialect(database, dialect);
+	}
+
+	return database;
+}
+
+/**
+ * Closes and clears the shared application database connection.
+ */
+export async function destroyDatabase(): Promise<void> {
+	if (!database) return;
+
+	await database.destroy();
+	database = null;
+}

package/src/db/contracts/ActiveRecordDefinition.ts

@@ -0,0 +1,69 @@
+import type { ActiveRecord, ActiveRecordOptions } from '../ActiveRecord';
+import type { FieldInputMap, FieldInputValue, FieldValue } from '../FieldType';
+import type { FieldBuilder } from '../fields/field';
+
+/** A model constructor whose fields can be extended by `ActiveRecord.define()`. */
+export type ActiveRecordDefinitionBase = (abstract new (input?: Record<string, unknown>, options?: ActiveRecordOptions) => ActiveRecord) & {
+	/** Existing field factory, including definitions inherited by the model. */
+	fields(field: FieldBuilder): FieldInputMap;
+};
+
+/** Field definitions known statically; a dynamic base contributes no inferred keys. */
+export type ActiveRecordDefinedFields<TBase extends ActiveRecordDefinitionBase> =
+	string extends keyof ReturnType<TBase['fields']> ? {} : ReturnType<TBase['fields']>;
+
+/** Complete field map after a definition replaces matching inherited fields. */
+export type ActiveRecordMergedFields<TBase extends ActiveRecordDefinitionBase, TFields extends FieldInputMap> =
+	Omit<ActiveRecordDefinedFields<TBase>, keyof TFields> & TFields;
+
+/**
+ * Schema options for an inferred model. Omitted settings inherit from the base.
+ * Fields use the same builder, field classes and configured definitions as
+ * ordinary static `fields()` declarations.
+ */
+export interface ActiveRecordDefinition<TFields extends FieldInputMap> {
+	table?: string;
+	primaryKey?: string;
+	comment?: string;
+	labelFields?: string[];
+	requestFillable?: readonly string[];
+	requestGuarded?: readonly string[];
+	returning?: boolean;
+	softDeletes?: typeof ActiveRecord.softDeletes;
+	/** Supplies this layer's fields; inherited names replace the whole definition. */
+	fields(field: FieldBuilder): TFields;
+}
+
+/**
+ * Rejects overrides that change application or input types, and fields that
+ * collide with existing non-field members. Inherited methods can therefore
+ * continue to use the properties they were written against.
+ */
+export type ActiveRecordFieldOverrides<TBase extends ActiveRecordDefinitionBase, TFields extends FieldInputMap> = {
+	[TKey in keyof TFields]: [ActiveRecord.ResolvedField<TFields[TKey]>] extends [never]
+		? never
+		: TKey extends keyof ActiveRecordDefinedFields<TBase>
+		? SameFieldBoundary<TFields[TKey], ActiveRecordDefinedFields<TBase>[TKey]>
+		: TKey extends keyof InstanceType<TBase> ? never : TFields[TKey];
+};
+
+/** Compares both directions because inherited methods may read and write values. */
+type SameFieldBoundary<TField, TParent> =
+	[FieldValue<ActiveRecord.ResolvedField<TField>>, FieldInputValue<ActiveRecord.ResolvedField<TField>>] extends
+	[FieldValue<ActiveRecord.ResolvedField<TParent>>, FieldInputValue<ActiveRecord.ResolvedField<TParent>>]
+		? [FieldValue<ActiveRecord.ResolvedField<TParent>>, FieldInputValue<ActiveRecord.ResolvedField<TParent>>] extends
+		[FieldValue<ActiveRecord.ResolvedField<TField>>, FieldInputValue<ActiveRecord.ResolvedField<TField>>] ? TField : never
+		: never;
+
+/**
+ * Inferred subclass with the original static methods and a single constructor
+ * signature. Keeping statics generic in their receiver preserves later ordinary
+ * subclasses, their custom methods, and further calls to `define()`.
+ */
+export type DefinedActiveRecord<TBase extends ActiveRecordDefinitionBase, TFields extends FieldInputMap> =
+	Omit<TBase, 'prototype' | 'fields'> & {
+		/** Creates a record in memory; persistence still requires `save()`. */
+		new(input?: Partial<ActiveRecord.InferInput<{ fields: (field: FieldBuilder) => ActiveRecordMergedFields<TBase, TFields> }>>, options?: ActiveRecordOptions): InstanceType<TBase> & ActiveRecord.InferValue<{ fields: (field: FieldBuilder) => ActiveRecordMergedFields<TBase, TFields> }>;
+		/** Preserves concrete field types for inference and future bound-field APIs. */
+		fields(field: FieldBuilder): ActiveRecordMergedFields<TBase, TFields>;
+	};

package/src/db/contracts/DatabaseBackup.ts

@@ -0,0 +1,7 @@
+/**
+ * Application-provided implementation behind the database backup API.
+ *
+ * The database package owns the stable invocation surface while each app owns
+ * the concrete dump format, storage destinations, and retention policy.
+ */
+export type DatabaseBackupHandler = (request: Record<string, unknown>) => Promise<unknown>;

package/src/db/contracts/DatabaseMigrationsConfig.ts

@@ -0,0 +1,10 @@
+import type { DatabaseMigrationManagerOptions } from '../migrations/contracts';
+
+/**
+ * App-owned model registry and migration policy.
+ *
+ * The database service supplies its connection and dialect. Committed migrations
+ * always live in server/database/migrations and the snapshot in
+ * server/database/schema.snapshot.json, relative to the application directory.
+ */
+export type DatabaseMigrationsConfig = Omit<DatabaseMigrationManagerOptions, 'db' | 'dialect' | 'migrationsDirectory' | 'snapshotFile'>;

package/src/db/contracts/index.ts

@@ -0,0 +1,3 @@
+export * from './DatabaseBackup';
+export * from './ActiveRecordDefinition';
+export * from './DatabaseMigrationsConfig';

package/src/db/dialects/columnTypes.ts

@@ -0,0 +1,103 @@
+/**
+ * SQL column type helpers owned by each database dialect.
+ */
+export interface DatabaseColumnTypes {
+	varchar(length: number): string;
+	char(length: number): string;
+	text(): string;
+	longText(): string;
+	json(): string;
+	boolean(): string;
+	integer(options?: { unsigned?: boolean; big?: boolean }): string;
+	bigIncrements(): string;
+	decimal(precision: number, scale: number): string;
+	timestamp(precision?: number): string;
+}
+
+export const mysqlColumnTypes: DatabaseColumnTypes = {
+	varchar(length: number): string {
+		return `varchar(${length})`;
+	},
+
+	char(length: number): string {
+		return `char(${length})`;
+	},
+
+	text(): string {
+		return 'text';
+	},
+
+	longText(): string {
+		return 'longtext';
+	},
+
+	json(): string {
+		return 'json';
+	},
+
+	boolean(): string {
+		return 'boolean';
+	},
+
+	integer(options: { unsigned?: boolean; big?: boolean } = {}): string {
+		if (options.unsigned) {
+			return options.big ? 'bigint unsigned' : 'int unsigned';
+		}
+
+		return options.big ? 'bigint' : 'int';
+	},
+
+	bigIncrements(): string {
+		return 'bigint unsigned auto_increment';
+	},
+
+	decimal(precision: number, scale: number): string {
+		return `decimal(${precision},${scale})`;
+	},
+
+	timestamp(precision = 0): string {
+		return precision > 0 ? `timestamp(${precision})` : 'timestamp';
+	},
+};
+
+export const postgresColumnTypes: DatabaseColumnTypes = {
+	varchar(length: number): string {
+		return `varchar(${length})`;
+	},
+
+	char(length: number): string {
+		return `char(${length})`;
+	},
+
+	text(): string {
+		return 'text';
+	},
+
+	longText(): string {
+		return 'text';
+	},
+
+	json(): string {
+		return 'jsonb';
+	},
+
+	boolean(): string {
+		return 'boolean';
+	},
+
+	integer(options: { unsigned?: boolean; big?: boolean } = {}): string {
+		return options.big ? 'bigint' : 'integer';
+	},
+
+	bigIncrements(): string {
+		return 'bigserial';
+	},
+
+	decimal(precision: number, scale: number): string {
+		return `decimal(${precision},${scale})`;
+	},
+
+	timestamp(precision = 0): string {
+		return precision > 0 ? `timestamp(${precision})` : 'timestamp';
+	},
+};

package/src/db/dialects/index.ts

@@ -0,0 +1,6 @@
+export * from './columnTypes';
+export * from './types';
+export * from './mysql';
+export * from './mariadb';
+export * from './postgres';
+export * from './resolveDialect';

package/src/db/dialects/mariadb.ts

@@ -0,0 +1,51 @@
+import type { Knex } from 'knex';
+import type { DatabaseDialect } from './types';
+import {
+	mysqlDialect,
+	vectorFromDbValue,
+} from './mysql';
+
+/**
+ * MariaDB dialect used by the framework database layer.
+ */
+export const mariaDbDialect: DatabaseDialect = {
+	...mysqlDialect,
+	name: 'mariadb',
+	knexClient: 'mysql2',
+	supportsVectorIndexes: true,
+	vectorToDbValue: vectorToMariaDbValue,
+};
+
+/**
+ * Converts app-memory vectors into MariaDB's native VECTOR constructor.
+ */
+function vectorToMariaDbValue(
+	vector: readonly number[],
+	db?: Knex,
+): unknown {
+	const vectorText = JSON.stringify(validateVector(vector));
+
+	if (!db) {
+		return vectorText;
+	}
+
+	// translates strings like [0.1, -0.5, 0.8] into the little-endian IEEE float sequence of bytes required by the VECTOR data type
+	return db.raw('VEC_FromText(?)', [vectorText]);
+}
+
+/**
+ * Validates a vector before serializing it for MariaDB.
+ */
+function validateVector(vector: readonly number[]): readonly number[] {
+	for (let index = 0; index < vector.length; index += 1) {
+		const value = vector[index];
+
+		if (typeof value !== 'number' || !Number.isFinite(value)) {
+			throw new Error(`Vector value at index ${index} must be a finite number.`);
+		}
+	}
+
+	return vector;
+}
+
+export { vectorFromDbValue };

package/src/db/dialects/mysql.ts

@@ -0,0 +1,277 @@
+import { Buffer } from 'node:buffer';
+import type { Knex } from 'knex';
+import type {
+	DatabaseDialect,
+	TableIndexSpec,
+} from './types';
+import { mysqlColumnTypes } from './columnTypes';
+
+const VECTOR_BYTES_PER_ENTRY = 4;
+const VECTOR_MAX_DIMENSIONS = 16383;
+
+interface MySqlIndexRow {
+	Key_name?: unknown;
+	Column_name?: unknown;
+	Seq_in_index?: unknown;
+	Non_unique?: unknown;
+	Collation?: unknown;
+	Index_type?: unknown;
+}
+
+interface MySqlTableCommentRow {
+	tableName?: unknown;
+	comment?: unknown;
+}
+
+/**
+ * MySQL dialect used by the framework database layer.
+ */
+export const mysqlDialect: DatabaseDialect = {
+	name: 'mysql',
+	knexClient: 'mysql2',
+	defaultPort: 3306,
+	supportsReturningRows: false,
+	supportsTableComments: true,
+	supportsVectorIndexes: false,
+	vectorMaxDimensions: VECTOR_MAX_DIMENSIONS,
+	columnTypes: mysqlColumnTypes,
+	vectorColumnType,
+	vectorToDbValue: vectorToMysqlBuffer,
+	vectorFromDbValue,
+	createDatabase: createMysqlDatabase,
+	dropDatabase: dropMysqlDatabase,
+	quoteIdentifier: quoteMysqlIdentifier,
+	getTableIndexes: getMysqlTableIndexes,
+	getTableComments: getMysqlTableComments,
+};
+
+/**
+ * Returns the native MySQL VECTOR column type for configured dimensions.
+ */
+function vectorColumnType(dimensions?: number): string {
+	return dimensions === undefined ? 'vector' : `vector(${dimensions})`;
+}
+
+/**
+ * Creates a UTF-8 MySQL database for isolated integration tests.
+ */
+async function createMysqlDatabase(
+	db: Knex,
+	databaseName: string,
+): Promise<void> {
+	await db.raw(
+		`CREATE DATABASE ${quoteMysqlIdentifier(databaseName)} CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci`,
+	);
+}
+
+/**
+ * Drops an isolated MySQL integration-test database.
+ */
+async function dropMysqlDatabase(
+	db: Knex,
+	databaseName: string,
+): Promise<void> {
+	await db.raw(`DROP DATABASE IF EXISTS ${quoteMysqlIdentifier(databaseName)}`);
+}
+
+/**
+ * Quotes a MySQL identifier after the caller has validated its shape.
+ */
+function quoteMysqlIdentifier(identifier: string): string {
+	return `\`${identifier.replace(/`/g, '``')}\``;
+}
+
+/**
+ * Reads MySQL or MariaDB index metadata and normalizes it for schema diffing.
+ */
+async function getMysqlTableIndexes(
+	db: Knex,
+	tableName: string,
+): Promise<TableIndexSpec[]> {
+	const result = await db.raw('SHOW INDEX FROM ??', [tableName]);
+	const rows = extractMysqlRows(result) as MySqlIndexRow[];
+	const indexes = new Map<string, TableIndexSpec>();
+
+	for (const row of rows) {
+		const name = stringValue(row.Key_name);
+		const column = stringValue(row.Column_name);
+
+		if (!name || !column) continue;
+
+		const index = indexes.get(name) ?? {
+			name,
+			columns: [],
+			unique: Number(row.Non_unique ?? 1) === 0,
+			primary: name === 'PRIMARY',
+			type: indexType(row.Index_type),
+		};
+
+		index.columns.push({
+			name: column,
+			order: indexColumnOrder(row.Collation),
+		});
+		indexes.set(name, index);
+	}
+
+	return [...indexes.values()].map(index => {
+		return {
+			...index,
+			columns: index.columns.sort((a, b) => {
+				const aRow = rows.find(row => {
+					return stringValue(row.Key_name) === index.name
+						&& stringValue(row.Column_name) === a.name;
+				});
+				const bRow = rows.find(row => {
+					return stringValue(row.Key_name) === index.name
+						&& stringValue(row.Column_name) === b.name;
+				});
+
+				return Number(aRow?.Seq_in_index ?? 0) - Number(bRow?.Seq_in_index ?? 0);
+			}),
+		};
+	});
+}
+
+/**
+ * Reads MySQL or MariaDB table comments in one metadata query.
+ *
+ * @param db - Database connection used for metadata inspection.
+ * @param tableNames - Existing table names whose comments are required.
+ * @returns Existing comments keyed by table name.
+ */
+async function getMysqlTableComments(
+	db: Knex,
+	tableNames: string[],
+): Promise<Map<string, string | null>> {
+	if (tableNames.length === 0) {
+		return new Map();
+	}
+
+	const rows = await db<MySqlTableCommentRow>('information_schema.TABLES')
+		.select({
+			tableName: 'TABLE_NAME',
+			comment: 'TABLE_COMMENT',
+		})
+		.whereRaw('TABLE_SCHEMA = DATABASE()')
+		.whereIn('TABLE_NAME', tableNames);
+
+	return new Map(rows.flatMap(row => {
+		const tableName = stringValue(row.tableName);
+
+		if (!tableName) return [];
+
+		return [[
+			tableName,
+			stringValue(row.comment),
+		]];
+	}));
+}
+
+/**
+ * Converts database index-type metadata into a framework index kind.
+ *
+ * @param input - Raw index type from `SHOW INDEX`.
+ * @returns Framework index type.
+ */
+function indexType(input: unknown): 'normal' | 'vector' {
+	const value = String(input ?? '').trim().toLowerCase();
+
+	return value === 'vector' ? 'vector' : 'normal';
+}
+
+/**
+ * Encodes a numeric vector as little-endian float32 bytes.
+ */
+export function vectorToMysqlBuffer(vector: readonly number[]): Buffer {
+	const buffer = Buffer.allocUnsafe(vector.length * VECTOR_BYTES_PER_ENTRY);
+
+	for (let index = 0; index < vector.length; index += 1) {
+		const value = vector[index];
+
+		if (typeof value !== 'number' || !Number.isFinite(value)) {
+			throw new Error(`Vector value at index ${index} must be a finite number.`);
+		}
+
+		buffer.writeFloatLE(value, index * VECTOR_BYTES_PER_ENTRY);
+	}
+
+	return buffer;
+}
+
+/**
+ * Decodes a vector from a binary value, text JSON, or already-decoded array.
+ */
+export function vectorFromDbValue(input: unknown): number[] | null {
+	if (input === null || input === undefined || input === '') {
+		return null;
+	}
+
+	if (input instanceof Uint8Array) {
+		return vectorFromMysqlBuffer(input);
+	}
+
+	if (typeof input === 'string') {
+		const value = input.trim();
+
+		if (!value) return null;
+
+		return JSON.parse(value) as number[] | null;
+	}
+
+	return input as number[] | null;
+}
+
+/**
+ * Decodes little-endian float32 vector bytes into app-memory numbers.
+ */
+function vectorFromMysqlBuffer(input: Buffer | Uint8Array): number[] {
+	const buffer = Buffer.isBuffer(input) ? input : Buffer.from(input);
+
+	if (buffer.length % VECTOR_BYTES_PER_ENTRY !== 0) {
+		throw new Error('VECTOR binary data length must be divisible by 4.');
+	}
+
+	const vector: number[] = [];
+
+	for (
+		let offset = 0;
+		offset < buffer.length;
+		offset += VECTOR_BYTES_PER_ENTRY
+	) {
+		vector.push(buffer.readFloatLE(offset));
+	}
+
+	return vector;
+}
+
+/**
+ * Extracts row arrays from mysql2 raw result tuples.
+ */
+function extractMysqlRows(result: unknown): unknown[] {
+	if (!Array.isArray(result)) return [];
+
+	const [rows] = result;
+
+	return Array.isArray(rows) ? rows : [];
+}
+
+/**
+ * Returns a non-empty string value from database metadata.
+ */
+function stringValue(input: unknown): string | null {
+	return typeof input === 'string' && input !== '' ? input : null;
+}
+
+/**
+ * Converts MySQL index collation metadata into an order direction.
+ */
+function indexColumnOrder(input: unknown): 'asc' | 'desc' | undefined {
+	if (typeof input !== 'string') return undefined;
+
+	const value = input.trim().toUpperCase();
+
+	if (value === 'A') return 'asc';
+	if (value === 'D') return 'desc';
+
+	return undefined;
+}