sovrium 0.0.2

package/src/infrastructure/database/schema-migration/index-sync.ts

@@ -0,0 +1,108 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { Effect } from 'effect'
+import { generateIndexStatements } from '../generators/index-generators'
+import {
+  executeSQLStatements,
+  type TransactionLike,
+  type SQLExecutionError,
+} from '../sql/sql-execution'
+import type { Table } from '@/domain/models/app/table'
+
+/**
+ * Helper to generate DROP INDEX statements for indexes that need to be removed
+ */
+const generateDropIndexStatements = (
+  table: Table,
+  previousTable:
+    | {
+        readonly name: string
+        readonly fields?: readonly { name?: string; indexed?: boolean }[]
+        readonly indexes?: readonly { name: string }[]
+      }
+    | undefined
+): readonly string[] => {
+  if (!previousTable) return []
+
+  // Drop indexes for fields that no longer have indexed: true
+  const previousIndexedFields =
+    previousTable.fields
+      ?.filter((f) => f.name && 'indexed' in f && f.indexed)
+      .map((f) => f.name!) ?? []
+
+  const currentIndexedFields = new Set(
+    table.fields.filter((f) => 'indexed' in f && f.indexed).map((f) => f.name)
+  )
+
+  const removedIndexedFields = previousIndexedFields.filter(
+    (fieldName) => !currentIndexedFields.has(fieldName)
+  )
+
+  const fieldIndexDrops = removedIndexedFields.map((fieldName) => {
+    const indexName = `idx_${table.name}_${fieldName}`
+    return `DROP INDEX IF EXISTS ${indexName}`
+  })
+
+  // Drop indexes for fields that changed from indexed to unique
+  const currentUniqueFields = new Set(
+    table.fields.filter((f) => 'unique' in f && f.unique).map((f) => f.name)
+  )
+
+  const indexToUniqueFields = previousIndexedFields.filter((fieldName) =>
+    currentUniqueFields.has(fieldName)
+  )
+
+  const indexToUniqueDrops = indexToUniqueFields.map((fieldName) => {
+    const indexName = `idx_${table.name}_${fieldName}`
+    return `DROP INDEX IF EXISTS ${indexName}`
+  })
+
+  // Drop custom indexes that were removed
+  const previousCustomIndexes = previousTable.indexes?.map((idx) => idx.name) ?? []
+  const currentCustomIndexes = table.indexes?.map((idx) => idx.name) ?? []
+
+  const removedCustomIndexes = previousCustomIndexes.filter(
+    (name) => !currentCustomIndexes.includes(name)
+  )
+
+  const customIndexDrops = removedCustomIndexes.map((name) => `DROP INDEX IF EXISTS ${name}`)
+
+  return [...fieldIndexDrops, ...indexToUniqueDrops, ...customIndexDrops]
+}
+
+/**
+ * Sync indexes for existing table
+ * Drops indexes that are no longer needed and creates new indexes
+ * This is needed when field indexed property changes or custom indexes are added/removed
+ */
+export const syncIndexes = (
+  tx: TransactionLike,
+  table: Table,
+  previousSchema?: { readonly tables: readonly object[] }
+): Effect.Effect<void, SQLExecutionError> =>
+  Effect.gen(function* () {
+    // Get previous table definition
+    const previousTable = previousSchema?.tables.find(
+      (t: object) => 'name' in t && t.name === table.name
+    ) as
+      | {
+          name: string
+          fields?: readonly { name?: string; indexed?: boolean }[]
+          indexes?: readonly { name: string }[]
+        }
+      | undefined
+
+    // Determine which indexes should be dropped
+    const dropStatements = generateDropIndexStatements(table, previousTable)
+
+    // Generate CREATE INDEX statements for all current indexes
+    const createStatements = generateIndexStatements(table)
+
+    // Execute drop statements first, then create statements
+    yield* executeSQLStatements(tx, [...dropStatements, ...createStatements])
+  })

package/src/infrastructure/database/schema-migration/index.ts

@@ -0,0 +1,66 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+/**
+ * Schema Migration Helpers
+ *
+ * This module provides utilities for database schema migrations:
+ * - Table operations (rename, drop obsolete)
+ * - Column detection (add, drop, modify)
+ * - Type conversions and nullability changes
+ * - Constraint synchronization (unique, foreign key, check)
+ * - Index synchronization
+ *
+ * All functions use Effect for type-safe error handling.
+ */
+
+// Type exports
+export type { ExistingColumnInfo } from './column-detection'
+export { type TransactionLike as BunSQLTransaction } from '../sql/sql-execution'
+
+// Constants
+export { PROTECTED_SYSTEM_TABLES } from './constants'
+
+// Rename detection
+export { detectFieldRenames, detectTableRenames } from './rename-detection'
+
+// Table operations
+export { renameTablesIfNeeded, dropObsoleteTables } from './table-operations'
+
+// Type utilities
+export {
+  normalizeDataType,
+  doesColumnTypeMatch,
+  generateAlterColumnTypeStatement,
+} from './type-utils'
+
+// Column detection
+export {
+  needsIdColumnRecreation,
+  findColumnsToAdd,
+  findColumnsToDrop,
+  filterModifiableFields,
+  findTypeChanges,
+  generateNotNullValidationQuery,
+  generateBackfillQuery,
+  findNullabilityChanges,
+  findDefaultValueChanges,
+  buildColumnStatements,
+} from './column-detection'
+
+// Migration statement generation
+export { generateAlterTableStatements } from './migration-statements'
+
+// Constraint synchronization
+export {
+  syncUniqueConstraints,
+  syncForeignKeyConstraints,
+  syncCheckConstraints,
+} from './constraint-sync'
+
+// Index synchronization
+export { syncIndexes } from './index-sync'

package/src/infrastructure/database/schema-migration/migration-statements.ts

@@ -0,0 +1,106 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import {
+  needsIdColumnRecreation,
+  findColumnsToAdd,
+  findColumnsToDrop,
+  findTypeChanges,
+  findNullabilityChanges,
+  findDefaultValueChanges,
+  buildColumnStatements,
+  type ExistingColumnInfo,
+} from './column-detection'
+import { detectFieldRenames } from './rename-detection'
+import type { Table } from '@/domain/models/app/table'
+import type { Fields } from '@/domain/models/app/table/fields'
+
+/** Generate statements for automatic timestamp fields (created_at, updated_at, deleted_at) */
+const generateSpecialFieldStatements = (
+  table: Table,
+  existingColumns: ReadonlyMap<string, ExistingColumnInfo>
+): readonly string[] => {
+  const fieldNames = new Set(table.fields.map((f) => f.name))
+  const needsCreatedAt = !fieldNames.has('created_at') && !existingColumns.has('created_at')
+  const needsUpdatedAt = !fieldNames.has('updated_at') && !existingColumns.has('updated_at')
+  const needsDeletedAt = !fieldNames.has('deleted_at') && !existingColumns.has('deleted_at')
+
+  return [
+    ...(needsCreatedAt
+      ? [`ALTER TABLE ${table.name} ADD COLUMN created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()`]
+      : []),
+    ...(needsUpdatedAt
+      ? [`ALTER TABLE ${table.name} ADD COLUMN updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()`]
+      : []),
+    ...(needsDeletedAt ? [`ALTER TABLE ${table.name} ADD COLUMN deleted_at TIMESTAMPTZ`] : []),
+  ]
+}
+
+/** Validate destructive operations require explicit confirmation */
+const validateDestructiveOps = (table: Table, columnsToDrop: readonly string[]): void => {
+  if (columnsToDrop.length > 0 && !table.allowDestructive) {
+    const droppedColumns = columnsToDrop.join(', ')
+    /* eslint-disable-next-line functional/no-throw-statements */
+    throw new Error(
+      `Destructive operation detected: Dropping column(s) [${droppedColumns}] from table '${table.name}' requires confirmation. Set allowDestructive: true to proceed with data loss, or keep the field(s) in the schema to preserve data.`
+    )
+  }
+}
+
+/** Generate ALTER TABLE statements for schema migrations */
+export const generateAlterTableStatements = (
+  table: Table,
+  existingColumns: ReadonlyMap<string, ExistingColumnInfo>,
+  previousSchema?: { readonly tables: readonly object[] }
+): readonly string[] => {
+  const primaryKeyFields =
+    table.primaryKey?.type === 'composite' ? (table.primaryKey.fields ?? []) : []
+  const hasIdField = table.fields.some((field) => field.name === 'id')
+  const shouldProtectIdColumn = !hasIdField && !(table.primaryKey && primaryKeyFields.length > 0)
+
+  if (needsIdColumnRecreation(existingColumns, shouldProtectIdColumn)) return []
+
+  const fieldRenames = detectFieldRenames(table.name, table.fields, previousSchema)
+  const renameStatements = Array.from(fieldRenames.entries()).map(
+    ([oldName, newName]) => `ALTER TABLE ${table.name} RENAME COLUMN ${oldName} TO ${newName}`
+  )
+
+  const renamedOldNames = new Set(fieldRenames.keys())
+  const renamedNewNames = new Set(fieldRenames.values())
+  const schemaFieldsByName = new Map<string, Fields[number]>(
+    table.fields.map((field) => [field.name, field])
+  )
+
+  const columnsToAdd = findColumnsToAdd(table, existingColumns, renamedNewNames)
+  const columnsToDrop = findColumnsToDrop(
+    existingColumns,
+    schemaFieldsByName,
+    shouldProtectIdColumn,
+    renamedOldNames
+  )
+
+  validateDestructiveOps(table, columnsToDrop)
+
+  const { dropStatements, addStatements } = buildColumnStatements({
+    tableName: table.name,
+    columnsToDrop,
+    columnsToAdd,
+    primaryKeyFields,
+    allFields: table.fields,
+  })
+
+  // ORDER: rename → drop → add → special fields → type changes → defaults → nullability
+  return [
+    ...renameStatements,
+    ...dropStatements,
+    ...addStatements,
+    ...generateSpecialFieldStatements(table, existingColumns),
+    ...findTypeChanges(table, existingColumns, renamedNewNames),
+    ...findDefaultValueChanges(table, existingColumns, renamedNewNames, previousSchema),
+    ...findNullabilityChanges(table, existingColumns, renamedNewNames, primaryKeyFields),
+  ]
+}

package/src/infrastructure/database/schema-migration/rename-detection.ts

@@ -0,0 +1,87 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import type { Table } from '@/domain/models/app/table'
+import type { Fields } from '@/domain/models/app/table/fields'
+
+/**
+ * Detect field renames by comparing field IDs between previous and current schema
+ * Returns a map of old field name to new field name for renamed fields
+ */
+export const detectFieldRenames = (
+  tableName: string,
+  currentFields: readonly Fields[number][],
+  previousSchema?: { readonly tables: readonly object[] }
+): ReadonlyMap<string, string> => {
+  if (!previousSchema) return new Map()
+
+  // Find previous table definition
+  const previousTable = previousSchema.tables.find(
+    (t: object) => 'name' in t && t.name === tableName
+  ) as { name: string; fields?: readonly { id?: number; name?: string }[] } | undefined
+
+  if (!previousTable || !previousTable.fields) return new Map()
+
+  // Build map of field ID to field name for both schemas
+  const previousFieldsById = new Map(
+    previousTable.fields
+      .filter((f) => f.id !== undefined && f.name !== undefined)
+      .map((f) => [f.id!, f.name!])
+  )
+
+  const currentFieldsById = new Map(
+    currentFields.filter((f) => f.id !== undefined).map((f) => [f.id, f.name])
+  )
+
+  // Detect renames: same ID, different name (functional construction)
+  const renames = new Map<string, string>(
+    Array.from(currentFieldsById.entries())
+      .map(([fieldId, newName]) => {
+        const oldName = previousFieldsById.get(fieldId)
+        return oldName && oldName !== newName ? [oldName, newName] : undefined
+      })
+      .filter((entry): entry is [string, string] => entry !== undefined)
+  )
+
+  return renames
+}
+
+/**
+ * Detect table renames by comparing table IDs between previous and current schema
+ * Returns a map of old table name to new table name for renamed tables
+ */
+export const detectTableRenames = (
+  currentTables: readonly Table[],
+  previousSchema?: { readonly tables: readonly object[] }
+): ReadonlyMap<string, string> => {
+  if (!previousSchema) return new Map()
+
+  // Build map of table ID to table name for both schemas
+  const previousTablesById = new Map(
+    previousSchema.tables
+      .filter((t: object) => 'id' in t && 'name' in t && t.id !== undefined && t.name !== undefined)
+      .map((t: object) => [(t as { id: number }).id, (t as { name: string }).name])
+  )
+
+  const currentTablesById = new Map(
+    currentTables
+      .filter((t): t is Table & { id: number } => t.id !== undefined)
+      .map((t) => [t.id, t.name])
+  )
+
+  // Detect renames: same ID, different name (functional construction)
+  const renames = new Map<string, string>(
+    Array.from(currentTablesById.entries())
+      .map(([tableId, newName]) => {
+        const oldName = previousTablesById.get(tableId)
+        return oldName && oldName !== newName ? [oldName, newName] : undefined
+      })
+      .filter((entry): entry is [string, string] => entry !== undefined)
+  )
+
+  return renames
+}

package/src/infrastructure/database/schema-migration/table-operations.ts

@@ -0,0 +1,65 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { Effect } from 'effect'
+import {
+  getExistingTableNames,
+  executeSQLStatements,
+  type TransactionLike,
+  type SQLExecutionError,
+} from '../sql/sql-execution'
+import { PROTECTED_SYSTEM_TABLES } from './constants'
+import { detectTableRenames } from './rename-detection'
+import type { Table } from '@/domain/models/app/table'
+
+/**
+ * Rename tables that have changed names (same table ID, different name)
+ * Uses ALTER TABLE RENAME TO to preserve data, indexes, and constraints
+ */
+export const renameTablesIfNeeded = (
+  tx: TransactionLike,
+  tables: readonly Table[],
+  previousSchema?: { readonly tables: readonly object[] }
+): Effect.Effect<void, SQLExecutionError> =>
+  Effect.gen(function* () {
+    const tableRenames = detectTableRenames(tables, previousSchema)
+
+    if (tableRenames.size === 0) return
+
+    // Generate ALTER TABLE RENAME TO statements
+    const renameStatements = Array.from(tableRenames.entries()).map(
+      ([oldName, newName]) => `ALTER TABLE ${oldName} RENAME TO ${newName}`
+    )
+
+    yield* executeSQLStatements(tx, renameStatements)
+  })
+
+/**
+ * Drop tables that exist in database but are not defined in schema
+ *
+ * SECURITY NOTE: Table names are validated before reaching this function.
+ * This is SAFE because:
+ * 1. existingTableNames comes from pg_tables system catalog (trusted source)
+ * 2. schemaTableNames comes from validated Effect Schema objects
+ * 3. Only tables not in schema are dropped (explicit comparison)
+ * 4. Better Auth system tables are protected and never dropped
+ */
+export const dropObsoleteTables = (
+  tx: TransactionLike,
+  tables: readonly Table[]
+): Effect.Effect<void, SQLExecutionError> =>
+  Effect.gen(function* () {
+    const existingTableNames = yield* getExistingTableNames(tx)
+    const schemaTableNames = new Set(tables.map((table) => table.name))
+    const tablesToDrop = existingTableNames.filter(
+      (tableName) => !schemaTableNames.has(tableName) && !PROTECTED_SYSTEM_TABLES.has(tableName)
+    )
+
+    // Drop all obsolete tables sequentially
+    const dropStatements = tablesToDrop.map((tableName) => `DROP TABLE ${tableName} CASCADE`)
+    yield* executeSQLStatements(tx, dropStatements)
+  })

package/src/infrastructure/database/schema-migration/type-utils.ts

@@ -0,0 +1,98 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { mapFieldTypeToPostgres } from '../sql/sql-generators'
+import type { Fields } from '@/domain/models/app/table/fields'
+
+/**
+ * Normalize PostgreSQL data type for comparison
+ * Maps similar types to a canonical form (e.g., 'varchar' and 'character varying' both map to 'varchar')
+ * Strips length specifiers and precision for type matching
+ */
+export const normalizeDataType = (dataType: string): string => {
+  const normalized = dataType.toLowerCase().trim()
+
+  // Map 'character varying' to 'varchar' for easier comparison
+  if (normalized.startsWith('character varying')) return 'varchar'
+  if (normalized.startsWith('timestamp')) return 'timestamp'
+  if (normalized.startsWith('numeric') || normalized.startsWith('decimal')) return 'numeric'
+
+  // Map PostgreSQL ARRAY type to text[] for comparison with field type mappings
+  // information_schema.columns returns 'ARRAY' for all array columns
+  if (normalized === 'array') return 'text[]'
+
+  // Strip length specifiers for varchar, char, etc.
+  // varchar(255) → varchar, char(10) → char, numeric(10,2) → numeric
+  const withoutLength = normalized.replace(/\([^)]*\)/, '')
+
+  return withoutLength
+}
+
+/**
+ * Check if column data type matches the expected type from schema
+ */
+export const doesColumnTypeMatch = (field: Fields[number], existingDataType: string): boolean => {
+  const expectedType = mapFieldTypeToPostgres(field)
+  const normalizedExpected = normalizeDataType(expectedType)
+  const normalizedExisting = normalizeDataType(existingDataType)
+
+  // For varchar/text types, check if both are string types
+  if (
+    (normalizedExpected === 'varchar' || normalizedExpected === 'text') &&
+    (normalizedExisting === 'varchar' || normalizedExisting === 'text')
+  ) {
+    // Match if both are string types (varchar/text are interchangeable for our purposes)
+    return normalizedExpected === normalizedExisting
+  }
+
+  // For other types, exact match required
+  return normalizedExpected === normalizedExisting
+}
+
+/**
+ * Generate ALTER COLUMN TYPE statement with USING clause if needed
+ * Handles type conversions that require explicit casting or transformation
+ */
+export const generateAlterColumnTypeStatement = (
+  tableName: string,
+  field: Fields[number],
+  existingDataType: string
+): string => {
+  const targetType = mapFieldTypeToPostgres(field)
+  const normalizedTarget = normalizeDataType(targetType)
+  const normalizedExisting = normalizeDataType(existingDataType)
+
+  // Determine if USING clause is needed for type conversion
+  const usingClause = (() => {
+    // TEXT → VARCHAR requires LEFT() to truncate
+    if (normalizedExisting === 'text' && normalizedTarget === 'varchar') {
+      const lengthMatch = targetType.match(/VARCHAR\((\d+)\)/)
+      const length = lengthMatch ? lengthMatch[1] : '255'
+      return ` USING LEFT(${field.name}, ${length})`
+    }
+
+    // TEXT → INTEGER requires explicit cast
+    if (normalizedExisting === 'text' && normalizedTarget === 'integer') {
+      return ` USING ${field.name}::INTEGER`
+    }
+
+    // TEXT → TIMESTAMP requires explicit cast
+    if (normalizedExisting === 'text' && normalizedTarget === 'timestamp') {
+      return ` USING ${field.name}::TIMESTAMPTZ`
+    }
+
+    // INTEGER → NUMERIC conversion (automatic, no USING clause needed)
+    // PostgreSQL can implicitly convert INTEGER to NUMERIC
+    if (normalizedExisting === 'integer' && normalizedTarget === 'numeric') {
+      return ''
+    }
+
+    return ''
+  })()
+
+  return `ALTER TABLE ${tableName} ALTER COLUMN ${field.name} TYPE ${targetType}${usingClause}`
+}

package/src/infrastructure/database/schema-migration/types.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import type { TransactionLike } from '../sql/sql-execution'
+
+/**
+ * Type definition for Bun SQL transaction
+ * Re-exported from sql-execution.ts for backward compatibility
+ */
+export type BunSQLTransaction = TransactionLike

package/src/infrastructure/database/schema-migration-helpers.ts

@@ -0,0 +1,53 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+/**
+ * Schema Migration Helpers - Re-export Module
+ *
+ * This file re-exports all schema migration utilities from the split module structure.
+ * Maintained for backwards compatibility with existing imports.
+ *
+ * @see ./schema-migration/ for the actual implementations
+ */
+
+// Type exports
+export type { BunSQLTransaction, ExistingColumnInfo } from './schema-migration'
+
+// All function exports
+export {
+  // Constants
+  PROTECTED_SYSTEM_TABLES,
+  // Rename detection
+  detectFieldRenames,
+  detectTableRenames,
+  // Table operations
+  renameTablesIfNeeded,
+  dropObsoleteTables,
+  // Type utilities
+  normalizeDataType,
+  doesColumnTypeMatch,
+  generateAlterColumnTypeStatement,
+  // Column detection
+  needsIdColumnRecreation,
+  findColumnsToAdd,
+  findColumnsToDrop,
+  filterModifiableFields,
+  findTypeChanges,
+  generateNotNullValidationQuery,
+  generateBackfillQuery,
+  findNullabilityChanges,
+  findDefaultValueChanges,
+  buildColumnStatements,
+  // Migration statement generation
+  generateAlterTableStatements,
+  // Constraint synchronization
+  syncUniqueConstraints,
+  syncForeignKeyConstraints,
+  syncCheckConstraints,
+  // Index synchronization
+  syncIndexes,
+} from './schema-migration'

package/src/infrastructure/database/session-context.ts

@@ -0,0 +1,20 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+/**
+ * Re-export domain error types for backward compatibility
+ *
+ * Error classes are now defined in @/domain/errors (the domain layer)
+ * where they belong. This file re-exports them so existing infrastructure
+ * imports continue to work without changes.
+ */
+export {
+  SessionContextError,
+  ForbiddenError,
+  UniqueConstraintViolationError,
+  ValidationError,
+} from '@/domain/errors'