@c15t/backend 0.0.1-rc.10

package/src/db/migration/migration-builders.ts

@@ -0,0 +1,170 @@
+import type { ColumnDataType, Expression, Kysely } from 'kysely';
+import type {
+	Database,
+	KyselyDatabaseType,
+} from '~/db/adapters/kysely-adapter/types';
+import type { C15TOptions } from '~/types';
+import { createLogger } from '~/utils/logger';
+import { getType } from './type-mapping';
+import type { ColumnsToAdd, MigrationOperation, TableToCreate } from './types';
+
+/**
+ * Builds migrations for adding columns to existing tables
+ *
+ * This function creates ALTER TABLE statements to add missing columns
+ * to existing tables in the database.
+ *
+ * @param db - Kysely database instance used to build SQL operations
+ * @param toBeAdded - Collection of tables and columns that need to be added
+ * @param dbType - Database type to determine appropriate column types
+ * @returns Array of migration operations ready to be executed
+ */
+export function buildColumnAddMigrations(
+	db: Kysely<Database>,
+	toBeAdded: ColumnsToAdd[],
+	dbType: KyselyDatabaseType
+): MigrationOperation[] {
+	// Array to collect all migration operations
+	const migrations: MigrationOperation[] = [];
+
+	// Process each table that needs columns added
+	for (const table of toBeAdded) {
+		// For each field in the table that needs to be added
+		for (const [fieldName, field] of Object.entries(table.fields)) {
+			// Get the appropriate database-specific type for this field
+			const type = getType(field, dbType) as
+				| ColumnDataType
+				| Expression<C15TOptions['database']>;
+
+			// Build an ALTER TABLE statement using Kysely's fluent API
+			const exec = db.schema
+				.alterTable(table.table)
+				// Add the column with the appropriate name and type
+				.addColumn(fieldName, type, (col) => {
+					// Start with nullability constraint based on field requirements
+					let column = field.required !== false ? col.notNull() : col;
+
+					// Add foreign key reference if specified
+					if (field.references) {
+						column = column.references(
+							`${field.references.model}.${field.references.field}`
+						);
+					}
+
+					// Add unique constraint if specified
+					if (field.unique) {
+						column = column.unique();
+					}
+
+					return column;
+				});
+
+			// Add this migration operation to our collection
+			migrations.push(exec);
+		}
+	}
+
+	return migrations;
+}
+
+/**
+ * Builds migrations for creating new tables
+ *
+ * This function creates CREATE TABLE statements for tables
+ * that don't exist in the database but are defined in the schema.
+ *
+ * @param db - Kysely database instance used to build SQL operations
+ * @param toBeCreated - Collection of tables that need to be created
+ * @param dbType - Database type to determine appropriate column types
+ * @returns Array of migration operations ready to be executed
+ */
+export function buildTableCreateMigrations(
+	db: Kysely<Database>,
+	toBeCreated: TableToCreate[],
+	dbType: KyselyDatabaseType
+): MigrationOperation[] {
+	const logger = createLogger();
+	const migrations: MigrationOperation[] = [];
+
+	// Process each table that needs to be created
+	for (const table of toBeCreated) {
+		// Log all field names to detect potential duplicate 'id' issues
+		const fieldNames = Object.keys(table.fields);
+		logger.info(
+			`Creating table ${table.table} with fields: ${fieldNames.join(', ')}`
+		);
+
+		// Check for potential ID field conflict - warning for explicit 'id' field
+		// This is important because we automatically add an 'id' primary key
+		if (fieldNames.includes('id')) {
+			logger.warn(
+				`⚠️ Table ${table.table} already has an explicit 'id' field, which may conflict with the auto-generated primary key`
+			);
+		}
+
+		// Check for another potential issue: field with fieldName 'id' but different key
+		// This could cause column duplication errors
+		for (const [fieldName, field] of Object.entries(table.fields)) {
+			if (field.fieldName === 'id' && fieldName !== 'id') {
+				logger.error(
+					`❌ ERROR: Table ${table.table} has field '${fieldName}' with fieldName 'id' - this will cause a duplicate column error`
+				);
+			}
+		}
+
+		// Start building the CREATE TABLE statement
+		// Always add an 'id' primary key column first
+		let dbT = db.schema.createTable(table.table).addColumn(
+			'id',
+			// Choose appropriate ID type based on database
+			// MySQL and MSSQL use varchar(36) for UUIDs, others use text
+			dbType === 'mysql' || dbType === 'mssql' ? 'varchar(36)' : 'text',
+			// Make it a primary key and non-nullable
+			(col) => col.primaryKey().notNull()
+		);
+
+		// Now add all the subject-defined fields to the table
+		for (const [fieldName, field] of Object.entries(table.fields)) {
+			// Get appropriate database-specific type for this field
+			const type = getType(field, dbType) as
+				| ColumnDataType
+				| Expression<C15TOptions['database']>;
+
+			// Log what we're doing for debugging purposes
+			logger.info(
+				`Adding column ${fieldName} (fieldName: ${field.fieldName || fieldName}) to table ${table.table}`
+			);
+
+			// Add this column to the CREATE TABLE statement
+			dbT = dbT.addColumn(fieldName, type, (col) => {
+				// Apply constraints to the column
+
+				// 1. Nullability constraint - make NOT NULL if field is required
+				let column = field.required !== false ? col.notNull() : col;
+
+				// 2. Foreign key constraint - add REFERENCES if field references another table
+				if (field.references) {
+					column = column.references(
+						`${field.references.model}.${field.references.field}`
+					);
+				}
+
+				// 3. Uniqueness constraint - add UNIQUE if the field must have unique values
+				if (field.unique) {
+					column = column.unique();
+				}
+
+				return column;
+			});
+		}
+
+		// Generate and log the raw SQL for debugging/preview
+		const sqlDebug = dbT.compile().sql;
+		logger.info(`SQL for table ${table.table}:\n${sqlDebug}`);
+
+		// Add this completed CREATE TABLE statement to our migrations collection
+		migrations.push(dbT);
+	}
+
+	return migrations;
+}

package/src/db/migration/migration-execution.ts

@@ -0,0 +1,79 @@
+/**
+ * Migration execution functionality
+ *
+ * This module handles executing or compiling migrations.
+ *
+ * @module migration/migration-execution
+ */
+import { createLogger } from '../../utils/logger';
+import type { MigrationOperation } from './types';
+
+/**
+ * Creates functions to run or compile the generated migrations
+ *
+ * @param migrations - Migration operations to execute
+ * @returns Object with runMigrations and compileMigrations functions
+ */
+export function createMigrationExecutors(migrations: MigrationOperation[]) {
+	const logger = createLogger();
+
+	/**
+	 * Executes all migration operations against the database
+	 *
+	 * This function runs each migration in sequence, executing the SQL operations
+	 * directly against the connected database. If any migration fails, the
+	 * process is halted with an error.
+	 *
+	 * @remarks
+	 * Migrations are executed in the order they were added to the migrations array.
+	 * Column additions are typically executed before table creations to ensure
+	 * any references between them are properly established.
+	 *
+	 * Error handling includes:
+	 * - Detailed logging of which migration failed
+	 * - Capturing the exact SQL that caused the error
+	 * - Rethrowing the error to allow callers to implement recovery strategies
+	 *
+	 * @throws Will throw the original database error with additional context
+	 *
+	 * @returns A promise that resolves when all migrations are complete
+	 *
+	 * @example
+	 * ```typescript
+	 * try {
+	 *   await runMigrations();
+	 *   console.log('All migrations completed successfully');
+	 * } catch (error) {
+	 *   console.error('Migration failed:', error);
+	 * }
+	 * ```
+	 */
+	async function runMigrations() {
+		// Loop through each migration operation in sequence
+		for (const migration of migrations) {
+			try {
+				// Execute this migration against the database
+				await migration.execute();
+			} catch (error) {
+				// If a migration fails, log the specific SQL that failed
+				const sql = migration.compile().sql;
+				logger.error(`Migration failed! SQL:\n${sql}`);
+
+				// Rethrow the error to allow the caller to handle it
+				throw error;
+			}
+		}
+	}
+
+	/**
+	 * Compiles all migrations to SQL without executing them
+	 *
+	 * @returns SQL string of all migrations
+	 */
+	async function compileMigrations() {
+		const compiled = migrations.map((m) => m.compile().sql);
+		return `${compiled.join(';\n\n')};`;
+	}
+
+	return { runMigrations, compileMigrations };
+}

package/src/db/migration/schema-comparison.ts

@@ -0,0 +1,216 @@
+import type { TableMetadata } from 'kysely';
+import type { Field } from '~/db/core/fields';
+/**
+ * Schema comparison functionality for database migrations
+ *
+ * This module analyzes differences between the expected schema definition and the
+ * actual database schema to determine what tables need to be created and what
+ * columns need to be added to existing tables.
+ *
+ * The comparison process follows these steps:
+ * 1. Load the expected schema from configuration
+ * 2. Compare it with tables in the actual database
+ * 3. Identify tables that don't exist but should be created
+ * 4. Identify columns that need to be added to existing tables
+ *
+ * @remarks
+ * This is a core part of the migration system and is used by the main migration
+ * generator to determine what database changes are needed.
+ *
+ * @module migration/schema-comparison
+ */
+import type { C15TOptions } from '~/types';
+import { createLogger } from '../../utils/logger';
+import type { KyselyDatabaseType } from '../adapters/kysely-adapter/types';
+import { getSchema } from '../core/get-schema';
+import type { TableSchemaDefinition } from './get-schema/types';
+import { matchType } from './type-mapping';
+import type { ColumnsToAdd, TableToCreate } from './types';
+
+/**
+ * Analyzes schema differences between the expected schema and actual database
+ *
+ * This function compares the schema defined in the application with the
+ * actual database structure to determine what changes need to be made.
+ *
+ * @param config - c15t configuration containing the schema definition
+ * @param tableMetadata - Database table metadata from introspection, containing
+ *                        information about existing tables and columns
+ * @param dbType - The database type (postgres, mysql, sqlite, mssql) which affects
+ *                 how types are compared and mapped
+ *
+ * @returns An object containing tables to be created and columns to be added
+ *
+ * @example
+ * ```typescript
+ * const changes = analyzeSchemaChanges(
+ *   appConfig,
+ *   databaseMetadata,
+ *   'postgres'
+ * );
+ *
+ * console.log(`Need to create ${changes.toBeCreated.length} tables`);
+ * console.log(`Need to add columns to ${changes.toBeAdded.length} tables`);
+ * ```
+ */
+export function analyzeSchemaChanges(
+	config: C15TOptions,
+	tableMetadata: TableMetadata[],
+	dbType: KyselyDatabaseType
+): { toBeCreated: TableToCreate[]; toBeAdded: ColumnsToAdd[] } {
+	const betterAuthSchema = getSchema(config);
+	const logger = createLogger(config.logger);
+	const toBeCreated: TableToCreate[] = [];
+	const toBeAdded: ColumnsToAdd[] = [];
+
+	for (const [key, value] of Object.entries(betterAuthSchema)) {
+		const table = tableMetadata.find((t: { name: string }) => t.name === key);
+		if (!table) {
+			handleNewTable(key, value as TableSchemaDefinition, toBeCreated);
+			continue;
+		}
+
+		handleExistingTable(
+			key,
+			value as TableSchemaDefinition,
+			table,
+			toBeAdded,
+			dbType,
+			logger
+		);
+	}
+
+	return { toBeCreated, toBeAdded };
+}
+
+/**
+ * Handles logic for a table that needs to be created
+ *
+ * This function adds a new table to the list of tables to be created,
+ * handling cases where the table might already be in the list, or
+ * where it needs to be inserted at a specific position based on order.
+ *
+ * @param tableName - The name of the table to be created
+ * @param value - Table definition containing fields and order
+ * @param toBeCreated - Array of tables to be created, modified in-place
+ *
+ * @remarks
+ * The function uses the table's order property to maintain dependencies
+ * between tables. Tables with lower order values are created first.
+ *
+ * If a table with the same name already exists in the list, its fields
+ * will be merged with the new fields rather than replacing the entry.
+ */
+function handleNewTable(
+	tableName: string,
+	value: TableSchemaDefinition,
+	toBeCreated: TableToCreate[]
+): void {
+	const tIndex = toBeCreated.findIndex((t) => t.table === tableName);
+	const tableData = {
+		table: tableName,
+		fields: value.fields,
+		order: value.order || Number.POSITIVE_INFINITY,
+	};
+
+	const insertIndex = toBeCreated.findIndex(
+		(t) => (t.order || Number.POSITIVE_INFINITY) > tableData.order
+	);
+
+	if (insertIndex === -1) {
+		if (tIndex === -1) {
+			toBeCreated.push(tableData);
+		} else {
+			const existingTable = toBeCreated[tIndex];
+			if (existingTable) {
+				existingTable.fields = {
+					...existingTable.fields,
+					...value.fields,
+				};
+			}
+		}
+	} else {
+		toBeCreated.splice(insertIndex, 0, tableData);
+	}
+}
+
+/**
+ * Handles logic for an existing table that might need columns added
+ *
+ * This function compares the expected table fields with the actual
+ * table columns to determine which columns need to be added.
+ * It also logs warnings for type mismatches.
+ *
+ * @param tableName - The name of the table being checked
+ * @param value - Table definition containing expected fields and order
+ * @param table - Actual table metadata from database introspection
+ * @param toBeAdded - Array of table columns to be added, modified in-place
+ * @param dbType - Database type for type matching
+ * @param logger - Logger instance for warnings and errors
+ *
+ * @remarks
+ * Fields are compared by name and type. If a field exists in the expected schema
+ * but not in the actual table, it will be added to the list of columns to add.
+ *
+ * If a field exists in both but has a different type, a warning is logged.
+ * Type matching takes into account differences in type names between database systems.
+ *
+ * @example
+ * ```typescript
+ * // This might produce logs like:
+ * // "Field subjectId in table subjects has a different type in the database. Expected string but got varchar."
+ * handleExistingTable(
+ *   'subjects',
+ *   { fields: { subjectId: { type: 'string', required: true } }, order: 1 },
+ *   dbTable,
+ *   columnsToAdd,
+ *   'postgres',
+ *   logger
+ * );
+ * ```
+ */
+function handleExistingTable(
+	tableName: string,
+	value: TableSchemaDefinition,
+	table: TableMetadata,
+	toBeAdded: ColumnsToAdd[],
+	dbType: KyselyDatabaseType,
+	logger: ReturnType<typeof createLogger>
+): void {
+	// Collection of fields that need to be added to the existing table
+	const toBeAddedFields: Record<string, Field> = {};
+
+	// Iterate through each field in the expected schema for this table
+	for (const [fieldName, field] of Object.entries(value.fields)) {
+		// Check if the field exists in the actual database table
+		const column = table.columns.find((c) => c.name === fieldName);
+
+		// If the field doesn't exist in the database, mark it to be added
+		if (!column) {
+			toBeAddedFields[fieldName] = field;
+			continue; // Skip the rest of this iteration
+		}
+
+		// Field exists, so check if its type matches the expected type
+		// If types match, no action needed so continue to next field
+		if (matchType(column.dataType, field.type, dbType)) {
+			continue;
+		}
+
+		// If we reach here, the field exists but has a different type
+		// We don't alter column types to avoid data loss, just log a warning
+		logger.warn(
+			`Field ${fieldName} in table ${tableName} has a different type in the database. Expected ${field.type} but got ${column.dataType}.`
+		);
+	}
+
+	// After checking all fields, if we found fields that need to be added,
+	// add an entry to the toBeAdded array with all fields for this table
+	if (Object.keys(toBeAddedFields).length > 0) {
+		toBeAdded.push({
+			table: tableName,
+			fields: toBeAddedFields,
+			order: value.order || Number.POSITIVE_INFINITY, // Use specified order or lowest priority
+		});
+	}
+}