@fragno-dev/db 0.2.2 → 0.4.1

package/src/schema/create.ts

@@ -1,6 +1,12 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+
 import { createId } from "../id";
+import type { DbNow } from "../query/db-now";
+import type { Prettify } from "../util/types";
+import { createTableStandardSchemaProps, createTableValidator } from "./validator";
 
 export { generateId } from "./generate-id";
+export { FragnoDbValidationError } from "./validator";
 
 export type AnySchema = Schema<Record<string, AnyTable>>;
 
@@ -20,6 +26,16 @@ export type AnyColumn =
 export type TableSubOperation =
   | { type: "add-column"; columnName: string; column: AnyColumn }
   | { type: "add-index"; name: string; columns: string[]; unique: boolean }
+  | { type: "rename-column"; from: string; to: string }
+  | { type: "drop-column"; name: string }
+  | {
+      type: "update-column";
+      columnName: string;
+      column: AnyColumn;
+      updateNullable: boolean;
+      updateDefault: boolean;
+      updateDataType: boolean;
+    }
   | {
       type: "add-foreign-key";
       name: string;
@@ -51,6 +67,7 @@ export type SchemaOperation =
         type: "one" | "many";
         from: { table: string; column: string };
         to: { table: string; column: string };
+        foreignKey?: boolean;
       };
     };
 
@@ -72,11 +89,18 @@ class RelationInit<
   referencedTable: TTables[TTableName];
   referencer: AnyTable;
   on: [string, string][] = [];
+  foreignKey: boolean;
 
-  constructor(type: TRelationType, referencedTable: TTables[TTableName], referencer: AnyTable) {
+  constructor(
+    type: TRelationType,
+    referencedTable: TTables[TTableName],
+    referencer: AnyTable,
+    options?: { foreignKey?: boolean },
+  ) {
     this.type = type;
     this.referencedTable = referencedTable;
     this.referencer = referencer;
+    this.foreignKey = options?.foreignKey ?? true;
   }
 }
 
@@ -95,16 +119,17 @@ export class ExplicitRelationInit<
   TTables extends Record<string, AnyTable>,
   TTableName extends keyof TTables,
 > extends RelationInit<TRelationType, TTables, TTableName> {
-  init(ormName: string): Relation<TRelationType, TTables[TTableName]> {
-    const id = `${this.referencer.ormName}_${this.referencedTable.ormName}`;
+  init(name: string): Relation<TRelationType, TTables[TTableName]> {
+    const id = `${this.referencer.name}_${this.referencedTable.name}`;
 
     return {
       id,
       on: this.on,
-      name: ormName,
+      name,
       referencer: this.referencer,
       table: this.referencedTable,
       type: this.type,
+      foreignKey: this.foreignKey,
     };
   }
 }
@@ -116,6 +141,7 @@ export interface Relation<
   id: string;
   name: string;
   type: TRelationType;
+  foreignKey?: boolean;
 
   table: TTable;
   referencer: AnyTable;
@@ -123,18 +149,57 @@ export interface Relation<
   on: [string, string][];
 }
 
+type PickNullable<T> = {
+  [P in keyof T as null extends T[P] ? P : never]: T[P];
+};
+
+type PickNotNullable<T> = {
+  [P in keyof T as null extends T[P] ? never : P]: T[P];
+};
+
+type RawInsertValuesFromColumns<TColumns extends Record<string, AnyColumn>> = {
+  [K in keyof TColumns as string extends K ? never : K]: TColumns[K]["$in"];
+};
+
+type TableInsertValuesFromColumns<TColumns extends Record<string, AnyColumn>> = Prettify<
+  Partial<PickNullable<RawInsertValuesFromColumns<TColumns>>> &
+    PickNotNullable<RawInsertValuesFromColumns<TColumns>>
+>;
+
+export type TableInsertValues<T extends AnyTable> = TableInsertValuesFromColumns<T["columns"]>;
+
+export type TableUnknownKeysMode = "strip" | "strict";
+
+export type TableValidationOptions = {
+  unknownKeys?: TableUnknownKeysMode;
+};
+
 export interface Table<
   TColumns extends Record<string, AnyColumn> = Record<string, AnyColumn>,
   TRelations extends Record<string, AnyRelation> = Record<string, AnyRelation>,
   TIndexes extends Record<string, Index> = Record<string, Index>,
 > {
+  /**
+   * Standard Schema-compatible validator for insert values.
+   */
+  "~standard": StandardSchemaV1.Props<
+    TableInsertValuesFromColumns<TColumns>,
+    TableInsertValuesFromColumns<TColumns>
+  >;
   name: string;
-  ormName: string;
 
   columns: TColumns;
   relations: TRelations;
   indexes: TIndexes;
 
+  /**
+   * Validate insert values at runtime.
+   */
+  validate: (
+    value: unknown,
+    options?: TableValidationOptions,
+  ) => TableInsertValuesFromColumns<TColumns>;
+
   /**
    * Get column by name
    */
@@ -203,7 +268,6 @@ export type TypeMap = {
 export class Column<TType extends keyof TypeMap, TIn = unknown, TOut = unknown> {
   type: TType;
   name: string = "";
-  ormName: string = "";
   isNullable: boolean = false;
   role: "external-id" | "internal-id" | "version" | "reference" | "regular" = "regular";
   isHidden: boolean = false;
@@ -421,9 +485,36 @@ export class VersionColumn<TIn = unknown, TOut = unknown> extends Column<"intege
   }
 }
 
+function cloneColumn<TColumn extends AnyColumn>(col: TColumn): TColumn {
+  let clonedCol: AnyColumn;
+
+  if (col instanceof InternalIdColumn) {
+    clonedCol = new InternalIdColumn();
+  } else if (col instanceof VersionColumn) {
+    clonedCol = new VersionColumn();
+  } else if (col instanceof IdColumn) {
+    clonedCol = new IdColumn(col.type);
+  } else {
+    clonedCol = new Column(col.type);
+  }
+
+  clonedCol.name = col.name;
+  clonedCol.isNullable = col.isNullable;
+  clonedCol.role = col.role;
+  clonedCol.isHidden = col.isHidden;
+  clonedCol.default = col.default;
+  clonedCol.tableName = col.tableName;
+
+  return clonedCol as TColumn;
+}
+
+type ColumnInput<TType extends keyof TypeMap> =
+  | TypeMap[TType]
+  | (TType extends "timestamp" | "date" ? DbNow : never);
+
 export function column<TType extends keyof TypeMap>(
   type: TType,
-): Column<TType, TypeMap[TType], TypeMap[TType]> {
+): Column<TType, ColumnInput<TType>, TypeMap[TType]> {
   return new Column(type);
 }
 
@@ -449,8 +540,8 @@ export function referenceColumn(): Column<
  * This is a CUID string that can be auto-generated or user-provided.
  * Input accepts string | FragnoId | null, output returns FragnoId.
  */
-export function idColumn(): IdColumn<"varchar(30)", string | FragnoId | null, FragnoId> {
-  const col = new IdColumn<"varchar(30)", string | FragnoId | null, FragnoId>("varchar(30)");
+export function idColumn(): IdColumn<"varchar(128)", string | FragnoId | null, FragnoId> {
+  const col = new IdColumn<"varchar(128)", string | FragnoId | null, FragnoId>("varchar(128)");
   col.role = "external-id";
   col.defaultTo$((b) => b.cuid());
   return col;
@@ -579,6 +670,8 @@ export class FragnoReference {
   }
 }
 
+const validationClasses = { FragnoId, FragnoReference };
+
 type RelationType = "one" | "many";
 
 export class TableBuilder<
@@ -590,7 +683,6 @@ export class TableBuilder<
   #columns: TColumns;
   #relations: TRelations;
   #indexes: TIndexes;
-  #ormName: string = "";
   #columnOrder: string[] = [];
 
   constructor(name: string) {
@@ -626,7 +718,7 @@ export class TableBuilder<
    * Add a column to the table.
    */
   addColumn<TColumnName extends string, TColumn extends AnyColumn>(
-    ormName: TColumnName,
+    name: TColumnName,
     col: TColumn,
   ): TableBuilder<TColumns & Record<TColumnName, TColumn>, TRelations, TIndexes>;
 
@@ -634,28 +726,27 @@ export class TableBuilder<
    * Add a column to the table with simplified syntax.
    */
   addColumn<TColumnName extends string, TType extends keyof TypeMap>(
-    ormName: TColumnName,
+    name: TColumnName,
     type: TType,
   ): TableBuilder<
-    TColumns & Record<TColumnName, Column<TType, TypeMap[TType], TypeMap[TType]>>,
+    TColumns & Record<TColumnName, Column<TType, ColumnInput<TType>, TypeMap[TType]>>,
     TRelations,
     TIndexes
   >;
 
   addColumn<TColumnName extends string, TColumn extends AnyColumn, TType extends keyof TypeMap>(
-    ormName: TColumnName,
+    name: TColumnName,
     colOrType: TColumn | TType,
   ): TableBuilder<TColumns & Record<TColumnName, TColumn>, TRelations, TIndexes> {
     // Create the column if a type string was provided
     const col = typeof colOrType === "string" ? column(colOrType) : colOrType;
 
     // Set column metadata
-    col.ormName = ormName;
-    col.name = ormName;
+    col.name = name;
 
     // Add column directly to this builder
-    this.#columns[ormName] = col as unknown as TColumns[TColumnName];
-    this.#columnOrder.push(ormName);
+    this.#columns[name] = col as unknown as TColumns[TColumnName];
+    this.#columnOrder.push(name);
 
     return this as unknown as TableBuilder<
       TColumns & Record<TColumnName, TColumn>,
@@ -664,6 +755,32 @@ export class TableBuilder<
     >;
   }
 
+  /**
+   * Alter an existing column.
+   */
+  alterColumn<TColumnName extends NonIdColumnName<TColumns>>(
+    name: TColumnName,
+  ): ColumnAlterer<TColumns, TRelations, TIndexes, TColumnName> {
+    return {
+      nullable: <TNullable extends boolean = true>(nullable?: TNullable) => {
+        const column = this.#columns[name];
+        if (!column) {
+          throw new Error(`Unknown column name ${String(name)}`);
+        }
+
+        const cloned = cloneColumn(column) as Column<keyof TypeMap>;
+        const updated = cloned.nullable(nullable ?? true);
+        this.#columns[name] = updated as unknown as TColumns[TColumnName];
+
+        return this as unknown as TableBuilder<
+          UpdateColumn<TColumns, TColumnName, NullableColumn<TColumns[TColumnName], TNullable>>,
+          TRelations,
+          TIndexes
+        >;
+      },
+    };
+  }
+
   /**
    * Create an index on the specified columns.
    */
@@ -716,7 +833,6 @@ export class TableBuilder<
     // Auto-add _internalId and _version columns if not already present
     if (!this.#columns["_internalId"]) {
       const col = internalIdColumn();
-      col.ormName = "_internalId";
       col.name = "_internalId";
       // Safe: we're adding system columns to the internal columns object
       (this.#columns as Record<string, AnyColumn>)["_internalId"] = col;
@@ -724,18 +840,13 @@ export class TableBuilder<
 
     if (!this.#columns["_version"]) {
       const col = versionColumn();
-      col.ormName = "_version";
       col.name = "_version";
       // Safe: we're adding system columns to the internal columns object
       (this.#columns as Record<string, AnyColumn>)["_version"] = col;
     }
 
-    // Use name as ormName if ormName is not set
-    const ormName = this.#ormName || this.#name;
-
-    const table: Table<TColumns, TRelations, TIndexes> = {
+    const table = {
       name: this.#name,
-      ormName,
       columns: this.#columns,
       relations: this.#relations,
       indexes: this.#indexes,
@@ -751,7 +862,10 @@ export class TableBuilder<
       getVersionColumn: () => {
         return versionCol!;
       },
-    };
+    } as Table<TColumns, TRelations, TIndexes>;
+
+    table["~standard"] = createTableStandardSchemaProps(table, validationClasses);
+    table.validate = createTableValidator(table, validationClasses);
 
     // Set table reference and find special columns
     for (const k in this.#columns) {
@@ -787,6 +901,10 @@ export class TableBuilder<
 }
 
 export interface Schema<TTables extends Record<string, AnyTable> = Record<string, AnyTable>> {
+  /**
+   * @description The name of the schema (required).
+   */
+  name: string;
   /**
    * @description The version of the schema, automatically incremented on each change.
    */
@@ -850,12 +968,55 @@ type ColumnsToTuple<
     : never;
 } & AnyColumn[];
 
+type UpdateColumn<
+  TColumns extends Record<string, AnyColumn>,
+  TColumnName extends keyof TColumns,
+  TUpdatedColumn extends AnyColumn,
+> = Prettify<Omit<TColumns, TColumnName> & Record<TColumnName, TUpdatedColumn>>;
+
+type NonIdColumnName<TColumns extends Record<string, AnyColumn>> = {
+  [K in keyof TColumns]: TColumns[K] extends
+    | IdColumn<IdColumnType, unknown, unknown>
+    | InternalIdColumn<unknown, unknown>
+    | VersionColumn<unknown, unknown>
+    ? never
+    : K;
+}[keyof TColumns];
+
+type NullableColumn<TColumn extends AnyColumn, TNullable extends boolean> =
+  TColumn extends Column<infer TType, infer TIn, infer TOut>
+    ? Column<
+        TType,
+        TNullable extends true ? TIn | null : Exclude<TIn, null>,
+        TNullable extends true ? TOut | null : Exclude<TOut, null>
+      >
+    : TColumn;
+
+type ColumnAlterer<
+  TColumns extends Record<string, AnyColumn>,
+  TRelations extends Record<string, AnyRelation>,
+  TIndexes extends Record<string, Index>,
+  TColumnName extends keyof TColumns,
+> = {
+  nullable<TNullable extends boolean = true>(
+    nullable?: TNullable,
+  ): TableBuilder<
+    UpdateColumn<TColumns, TColumnName, NullableColumn<TColumns[TColumnName], TNullable>>,
+    TRelations,
+    TIndexes
+  >;
+};
+
 export class SchemaBuilder<TTables extends Record<string, AnyTable> = {}> {
+  #name: string;
   #tables: TTables;
   #version: number = 0;
   #operations: SchemaOperation[] = [];
+  #tableNames: Set<string> = new Set();
+  #indexNames: Set<string> = new Set();
 
-  constructor(existingSchema?: Schema<TTables>) {
+  constructor(name: string, existingSchema?: Schema<TTables>) {
+    this.#name = name;
     if (existingSchema) {
       this.#tables = existingSchema.tables;
       this.#version = existingSchema.version;
@@ -863,6 +1024,54 @@ export class SchemaBuilder<TTables extends Record<string, AnyTable> = {}> {
     } else {
       this.#tables = {} as TTables;
     }
+
+    for (const table of Object.values(this.#tables)) {
+      this.#registerTableName(table.name);
+      for (const index of Object.values(table.indexes)) {
+        this.#registerIndexName(index.name, table.name);
+      }
+    }
+  }
+
+  #registerTableName(name: string): void {
+    if (this.#tableNames.has(name)) {
+      throw new Error(`Duplicate table name "${name}" in schema "${this.#name}".`);
+    }
+    this.#tableNames.add(name);
+  }
+
+  #registerIndexName(name: string, tableName: string): void {
+    if (this.#indexNames.has(name)) {
+      throw new Error(
+        `Duplicate index name "${name}" in schema "${this.#name}". Index names must be unique across tables (conflict on "${tableName}").`,
+      );
+    }
+    this.#indexNames.add(name);
+  }
+
+  #rebindRelations(tableName: string, newTable: AnyTable): void {
+    for (const table of Object.values(this.#tables)) {
+      for (const relation of Object.values(table.relations)) {
+        if (relation.table.name === tableName) {
+          relation.table = newTable;
+        }
+        if (relation.referencer.name === tableName) {
+          relation.referencer = newTable;
+        }
+      }
+    }
+  }
+
+  #isJoinColumnIndexed(table: AnyTable, columnName: string): boolean {
+    const idColumnName = table.getIdColumn().name;
+    const internalIdColumnName = table.getInternalIdColumn().name;
+    if (columnName === idColumnName || columnName === internalIdColumnName) {
+      return true;
+    }
+
+    return Object.values(table.indexes).some((index) =>
+      index.columnNames.some((name) => name === columnName),
+    );
   }
 
   /**
@@ -871,7 +1080,7 @@ export class SchemaBuilder<TTables extends Record<string, AnyTable> = {}> {
    *
    * @example
    * ```ts
-   * const builder = new SchemaBuilder()
+   * const builder = new SchemaBuilder("combined")
    *   .add(userSchema)
    *   .add(postSchema)
    *   .addTable("comments", ...);
@@ -880,10 +1089,32 @@ export class SchemaBuilder<TTables extends Record<string, AnyTable> = {}> {
   mergeWithExistingSchema<TNewTables extends Record<string, AnyTable>>(
     schema: Schema<TNewTables>,
   ): SchemaBuilder<TTables & TNewTables> {
+    for (const table of Object.values(schema.tables)) {
+      if (this.#tableNames.has(table.name)) {
+        throw new Error(
+          `Duplicate table name "${table.name}" in schema "${this.#name}" when merging.`,
+        );
+      }
+      for (const index of Object.values(table.indexes)) {
+        if (this.#indexNames.has(index.name)) {
+          throw new Error(
+            `Duplicate index name "${index.name}" in schema "${this.#name}" when merging (conflict on "${table.name}").`,
+          );
+        }
+      }
+    }
+
     this.#tables = { ...this.#tables, ...schema.tables } as TTables & TNewTables;
     this.#operations = [...this.#operations, ...schema.operations];
     this.#version += schema.version;
 
+    for (const table of Object.values(schema.tables)) {
+      this.#tableNames.add(table.name);
+      for (const index of Object.values(table.indexes)) {
+        this.#indexNames.add(index.name);
+      }
+    }
+
     return this as unknown as SchemaBuilder<TTables & TNewTables>;
   }
 
@@ -896,21 +1127,31 @@ export class SchemaBuilder<TTables extends Record<string, AnyTable> = {}> {
     TRelations extends Record<string, AnyRelation>,
     TIndexes extends Record<string, Index> = Record<string, Index>,
   >(
-    ormName: TTableName,
+    name: TTableName,
     callback: (
-      builder: TableBuilder<
-        Record<string, AnyColumn>,
-        Record<string, AnyRelation>,
-        Record<string, Index>
-      >,
+      builder: TableBuilder<{}, Record<string, AnyRelation>, Record<string, Index>>,
     ) => TableBuilder<TColumns, TRelations, TIndexes>,
   ): SchemaBuilder<TTables & Record<TTableName, Table<TColumns, TRelations, TIndexes>>> {
     this.#version++;
 
-    const tableBuilder = new TableBuilder(ormName);
+    if (this.#tableNames.has(name)) {
+      throw new Error(`Duplicate table name "${name}" in schema "${this.#name}".`);
+    }
+
+    const tableBuilder = new TableBuilder<{}, Record<string, AnyRelation>, Record<string, Index>>(
+      name,
+    );
     const result = callback(tableBuilder);
     const builtTable = result.build();
-    builtTable.ormName = ormName;
+    const indexNames = result.getIndexes().map((idx) => idx.name);
+
+    for (const indexName of indexNames) {
+      if (this.#indexNames.has(indexName)) {
+        throw new Error(
+          `Duplicate index name "${indexName}" in schema "${this.#name}". Index names must be unique across tables (conflict on "${name}").`,
+        );
+      }
+    }
 
     // Collect sub-operations in order
     const subOperations: TableSubOperation[] = [];
@@ -922,7 +1163,7 @@ export class SchemaBuilder<TTables extends Record<string, AnyTable> = {}> {
       subOperations.push({
         type: "add-column",
         columnName: colName,
-        column: col,
+        column: cloneColumn(col),
       });
     }
 
@@ -931,14 +1172,14 @@ export class SchemaBuilder<TTables extends Record<string, AnyTable> = {}> {
       subOperations.push({
         type: "add-column",
         columnName: "_internalId",
-        column: builtTable.columns["_internalId"],
+        column: cloneColumn(builtTable.columns["_internalId"]),
       });
     }
     if (builtTable.columns["_version"]) {
       subOperations.push({
         type: "add-column",
         columnName: "_version",
-        column: builtTable.columns["_version"],
+        column: cloneColumn(builtTable.columns["_version"]),
       });
     }
 
@@ -947,7 +1188,7 @@ export class SchemaBuilder<TTables extends Record<string, AnyTable> = {}> {
       subOperations.push({
         type: "add-index",
         name: idx.name,
-        columns: idx.columns.map((c) => c.ormName),
+        columns: idx.columns.map((c) => c.name),
         unique: idx.unique,
       });
     }
@@ -955,13 +1196,17 @@ export class SchemaBuilder<TTables extends Record<string, AnyTable> = {}> {
     // Add the add-table operation
     this.#operations.push({
       type: "add-table",
-      tableName: ormName,
+      tableName: name,
       operations: subOperations,
     });
 
     // Update tables map
-    this.#tables = { ...this.#tables, [ormName]: builtTable } as TTables &
+    this.#tables = { ...this.#tables, [name]: builtTable } as TTables &
       Record<TTableName, Table<TColumns, TRelations, TIndexes>>;
+    this.#tableNames.add(name);
+    for (const indexName of indexNames) {
+      this.#indexNames.add(indexName);
+    }
 
     return this as unknown as SchemaBuilder<
       TTables & Record<TTableName, Table<TColumns, TRelations, TIndexes>>
@@ -977,7 +1222,7 @@ export class SchemaBuilder<TTables extends Record<string, AnyTable> = {}> {
    * @example
    * ```ts
    * // One-to-one or many-to-one: post -> user
-   * schema(s => s
+   * schema("blog", s => s
    *   .addTable("users", t => t.addColumn("id", idColumn()))
    *   .addTable("posts", t => t
    *     .addColumn("id", idColumn())
@@ -1002,6 +1247,14 @@ export class SchemaBuilder<TTables extends Record<string, AnyTable> = {}> {
    *   from: { table: "users", column: "invitedBy" },
    *   to: { table: "users", column: "id" },
    * })
+   *
+   * // Join-only relation (no foreign key)
+   * .addReference("invitedUser", {
+   *   type: "one",
+   *   from: { table: "invitations", column: "email" },
+   *   to: { table: "users", column: "email" },
+   *   foreignKey: false,
+   * })
    * ```
    */
   addReference<
@@ -1021,6 +1274,12 @@ export class SchemaBuilder<TTables extends Record<string, AnyTable> = {}> {
         table: TToTableName;
         column: keyof TTables[TToTableName]["columns"];
       };
+      /**
+       * When false, defines a join-only relation without foreign key migrations.
+       * References to external-id columns still coerce to `_internalId`
+       * (including left-side external IDs for join-only).
+       */
+      foreignKey?: boolean;
     },
   ): SchemaBuilder<
     UpdateTableRelations<TTables, TFromTableName, TReferenceName, TToTableName, TRelationType>
@@ -1030,6 +1289,10 @@ export class SchemaBuilder<TTables extends Record<string, AnyTable> = {}> {
     const table = this.#tables[config.from.table];
     const referencedTable = this.#tables[config.to.table];
 
+    if (!referenceName || referenceName.trim().length === 0) {
+      throw new Error(`referenceName is required for addReference on ${config.from.table}`);
+    }
+
     if (!table) {
       throw new Error(`Table ${config.from.table} not found in schema`);
     }
@@ -1039,21 +1302,33 @@ export class SchemaBuilder<TTables extends Record<string, AnyTable> = {}> {
 
     const columnName = config.from.column as string;
     const targetColumnName = config.to.column as string;
-
-    // Foreign keys always reference internal IDs, not external IDs
-    // If user specifies "id", translate to "_internalId" for the actual FK
-    const actualTargetColumnName = targetColumnName === "id" ? "_internalId" : targetColumnName;
+    const foreignKey = config.foreignKey !== false;
 
     const column = table.columns[columnName];
-    const referencedColumn = referencedTable.columns[actualTargetColumnName];
+    const targetColumn = referencedTable.columns[targetColumnName];
 
     if (!column) {
       throw new Error(`Column ${columnName} not found in table ${config.from.table}`);
     }
+    if (!targetColumn) {
+      throw new Error(`Column ${targetColumnName} not found in table ${config.to.table}`);
+    }
+
+    // External-id columns always target the internal ID column.
+    const actualTargetColumnName =
+      targetColumn.role === "external-id"
+        ? referencedTable.getInternalIdColumn().name
+        : targetColumnName;
+
+    const referencedColumn = referencedTable.columns[actualTargetColumnName];
     if (!referencedColumn) {
       throw new Error(`Column ${actualTargetColumnName} not found in table ${config.to.table}`);
     }
 
+    if (table.relations[referenceName]) {
+      throw new Error(`Reference ${referenceName} already exists on table ${config.from.table}`);
+    }
+
     // Verify that reference columns are bigint (matching internal ID type)
     if (column.role === "reference" && column.type !== "bigint") {
       throw new Error(
@@ -1061,9 +1336,28 @@ export class SchemaBuilder<TTables extends Record<string, AnyTable> = {}> {
       );
     }
 
-    // Create the relation (use the user-facing column name for the relation)
-    const init = new ExplicitRelationInit(config.type, referencedTable, table);
-    init.on.push([columnName, targetColumnName]);
+    if (!foreignKey) {
+      const missingIndexes: string[] = [];
+      if (!this.#isJoinColumnIndexed(table, columnName)) {
+        missingIndexes.push(`${table.name}.${columnName}`);
+      }
+      if (!this.#isJoinColumnIndexed(referencedTable, actualTargetColumnName)) {
+        missingIndexes.push(`${referencedTable.name}.${actualTargetColumnName}`);
+      }
+      if (missingIndexes.length > 0) {
+        throw new Error(
+          `Join-only relation "${referenceName}" requires indexed join columns: ${missingIndexes.join(", ")}.`,
+        );
+      }
+    }
+
+    // Join-only relations treat external IDs as internal IDs on the left side.
+    const actualFromColumnName =
+      !foreignKey && column.role === "external-id" ? table.getInternalIdColumn().name : columnName;
+
+    // Create the relation (use user-facing right-side column name)
+    const init = new ExplicitRelationInit(config.type, referencedTable, table, { foreignKey });
+    init.on.push([actualFromColumnName, targetColumnName]);
     const relation = init.init(referenceName);
 
     // Add relation to the table
@@ -1076,8 +1370,9 @@ export class SchemaBuilder<TTables extends Record<string, AnyTable> = {}> {
       referenceName,
       config: {
         type: config.type,
-        from: { table: config.from.table, column: columnName },
+        from: { table: config.from.table, column: actualFromColumnName },
         to: { table: config.to.table, column: actualTargetColumnName },
+        foreignKey,
       },
     });
 
@@ -1089,8 +1384,8 @@ export class SchemaBuilder<TTables extends Record<string, AnyTable> = {}> {
   }
 
   /**
-   * Alter an existing table by adding columns or indexes.
-   * This is used for append-only schema modifications.
+   * Alter an existing table by adding columns, altering columns, or adding indexes.
+   * This is used for forward-only schema modifications.
    *
    * @param tableName - The name of the table to modify
    * @param callback - A callback that receives a table builder for adding columns/indexes
@@ -1098,11 +1393,12 @@ export class SchemaBuilder<TTables extends Record<string, AnyTable> = {}> {
    * @example
    * ```ts
    * // Add a new column to an existing table
-   * schema(s => s
+   * schema("blog", s => s
    *   .addTable("users", t => t
    *     .addColumn("id", idColumn())
    *     .addColumn("name", column("string")))
    *   .alterTable("users", t => t
+   *     .alterColumn("name").nullable()
    *     .addColumn("email", column("string"))
    *     .addColumn("age", column("integer").nullable())
    *     .createIndex("idx_email", ["email"]))
@@ -1139,6 +1435,10 @@ export class SchemaBuilder<TTables extends Record<string, AnyTable> = {}> {
     // Track existing columns and indexes
     const existingColumns = new Set(Object.keys(table.columns));
     const existingIndexes = new Set(Object.keys(table.indexes));
+    const existingColumnState = new Map<string, { isNullable: boolean }>();
+    for (const [colName, col] of Object.entries(table.columns)) {
+      existingColumnState.set(colName, { isNullable: col.isNullable });
+    }
 
     // Apply modifications
     const resultBuilder = callback(
@@ -1160,7 +1460,25 @@ export class SchemaBuilder<TTables extends Record<string, AnyTable> = {}> {
         subOperations.push({
           type: "add-column",
           columnName: colName,
-          column: newTable.columns[colName],
+          column: cloneColumn(newTable.columns[colName]),
+        });
+      }
+    }
+
+    // Track updates to existing columns
+    for (const [colName, previousState] of existingColumnState.entries()) {
+      const updatedColumn = newTable.columns[colName];
+      if (!updatedColumn) {
+        continue;
+      }
+      if (previousState.isNullable !== updatedColumn.isNullable) {
+        subOperations.push({
+          type: "update-column",
+          columnName: colName,
+          column: cloneColumn(updatedColumn),
+          updateNullable: true,
+          updateDefault: false,
+          updateDataType: false,
         });
       }
     }
@@ -1168,10 +1486,15 @@ export class SchemaBuilder<TTables extends Record<string, AnyTable> = {}> {
     // Add only new indexes
     for (const idx of resultBuilder.getIndexes()) {
       if (!existingIndexes.has(idx.name)) {
+        if (this.#indexNames.has(idx.name)) {
+          throw new Error(
+            `Duplicate index name "${idx.name}" in schema "${this.#name}". Index names must be unique across tables (conflict on "${tableName}").`,
+          );
+        }
         subOperations.push({
           type: "add-index",
           name: idx.name,
-          columns: idx.columns.map((c) => c.ormName),
+          columns: idx.columns.map((c) => c.name),
           unique: idx.unique,
         });
       }
@@ -1188,6 +1511,12 @@ export class SchemaBuilder<TTables extends Record<string, AnyTable> = {}> {
 
     // Update table reference in schema
     this.#tables[tableName] = newTable as unknown as TTables[TTableName];
+    this.#rebindRelations(tableName, newTable as unknown as AnyTable);
+    for (const idx of resultBuilder.getIndexes()) {
+      if (!existingIndexes.has(idx.name)) {
+        this.#indexNames.add(idx.name);
+      }
+    }
 
     // Set table name for all columns
     for (const col of Object.values(newTable.columns)) {
@@ -1208,6 +1537,7 @@ export class SchemaBuilder<TTables extends Record<string, AnyTable> = {}> {
     const tables = this.#tables;
 
     const schema: Schema<TTables> = {
+      name: this.#name,
       version,
       tables,
       operations,
@@ -1231,7 +1561,6 @@ export class SchemaBuilder<TTables extends Record<string, AnyTable> = {}> {
             }
 
             clonedCol.name = col.name;
-            clonedCol.ormName = col.ormName;
             clonedCol.isNullable = col.isNullable;
             clonedCol.role = col.role;
             clonedCol.isHidden = col.isHidden;
@@ -1240,20 +1569,28 @@ export class SchemaBuilder<TTables extends Record<string, AnyTable> = {}> {
             clonedColumns[colName] = clonedCol;
           }
 
-          cloneTables[k] = {
+          const clonedTable = {
             ...v,
             columns: clonedColumns,
-          };
+          } as AnyTable;
+
+          clonedTable["~standard"] = createTableStandardSchemaProps(clonedTable, validationClasses);
+          clonedTable.validate = createTableValidator(clonedTable, validationClasses);
+
+          cloneTables[k] = clonedTable;
         }
 
-        return new SchemaBuilder<TTables>({
+        const clonedSchema: Schema<TTables> = {
+          name: this.#name,
           version,
           tables: cloneTables as TTables,
           operations: [...operations],
           clone: () => {
             throw new Error("Cannot clone during clone");
           },
-        }).build();
+        };
+
+        return new SchemaBuilder<TTables>(this.#name, clonedSchema).build();
       },
     };
 
@@ -1272,19 +1609,18 @@ export class SchemaBuilder<TTables extends Record<string, AnyTable> = {}> {
  * Create a new schema with callback pattern.
  */
 export function schema<const TTables extends Record<string, AnyTable> = {}>(
+  name: string,
   callback: (builder: SchemaBuilder<{}>) => SchemaBuilder<TTables>,
 ): Schema<TTables> {
-  return callback(new SchemaBuilder()).build();
+  return callback(new SchemaBuilder(name)).build();
 }
 
-export function compileForeignKey(key: ForeignKey, nameType: "sql" | "orm" = "orm") {
+export function compileForeignKey(key: ForeignKey) {
   return {
     name: key.name,
-    table: nameType === "sql" ? key.table.name : key.table.ormName,
-    referencedTable: nameType === "sql" ? key.referencedTable.name : key.referencedTable.ormName,
-    referencedColumns: key.referencedColumns.map((col) =>
-      nameType === "sql" ? col.name : col.ormName,
-    ),
-    columns: key.columns.map((col) => (nameType === "sql" ? col.name : col.ormName)),
+    table: key.table.name,
+    referencedTable: key.referencedTable.name,
+    referencedColumns: key.referencedColumns.map((col) => col.name),
+    columns: key.columns.map((col) => col.name),
   };
 }