@fragno-dev/db 0.0.1 → 0.1.0

package/src/schema/create.ts

@@ -1,4 +1,4 @@
-import { createId } from "../cuid";
+import { createId } from "../id";
 
 export type AnySchema = Schema<Record<string, AnyTable>>;
 
@@ -8,17 +8,23 @@ export type AnyTable = Table;
 
 export type AnyColumn =
   | Column<keyof TypeMap, unknown, unknown>
-  | IdColumn<IdColumnType, unknown, unknown>;
-
+  | IdColumn<IdColumnType, unknown, unknown>
+  | InternalIdColumn<unknown, unknown>
+  | VersionColumn<unknown, unknown>;
 /**
- * Operations that can be performed on a table during its definition.
+ * Sub-operations that can be performed within table operations.
+ * These are stored in order within add-table and alter-table operations.
  */
-export type TableOperation = {
-  type: "add-index";
-  name: string;
-  columns: string[];
-  unique: boolean;
-};
+export type TableSubOperation =
+  | { type: "add-column"; columnName: string; column: AnyColumn }
+  | { type: "add-index"; name: string; columns: string[]; unique: boolean }
+  | {
+      type: "add-foreign-key";
+      name: string;
+      columns: string[];
+      referencedTable: string;
+      referencedColumns: string[];
+    };
 
 /**
  * Operations that can be performed on a schema during its definition.
@@ -28,24 +34,22 @@ export type SchemaOperation =
   | {
       type: "add-table";
       tableName: string;
-      table: AnyTable;
+      operations: TableSubOperation[]; // Ordered list of sub-operations
     }
   | {
-      type: "add-reference";
+      type: "alter-table";
       tableName: string;
+      operations: TableSubOperation[]; // Ordered list of sub-operations
+    }
+  | {
+      type: "add-reference";
+      tableName: string; // The table that has the foreign key
       referenceName: string;
       config: {
-        columns: string[];
-        targetTable: string;
-        targetColumns: string[];
+        type: "one" | "many";
+        from: { table: string; column: string };
+        to: { table: string; column: string };
       };
-    }
-  | {
-      type: "add-index";
-      tableName: string;
-      name: string;
-      columns: string[];
-      unique: boolean;
     };
 
 export interface ForeignKey {
@@ -74,61 +78,26 @@ class RelationInit<
   }
 }
 
-export interface Index {
+export interface Index<
+  TColumns extends AnyColumn[] = AnyColumn[],
+  TColumnNames extends readonly string[] = readonly string[],
+> {
   name: string;
-  columns: AnyColumn[];
+  columns: TColumns;
+  columnNames: TColumnNames;
   unique: boolean;
 }
 
-/**
- * Helper function to add an index to a table's index array
- */
-function addIndexToTable(
-  indexes: Index[],
-  name: string,
-  columns: AnyColumn[],
-  unique: boolean,
-): void {
-  indexes.push({
-    name,
-    columns,
-    unique,
-  });
-}
-
 export class ExplicitRelationInit<
   TRelationType extends RelationType,
   TTables extends Record<string, AnyTable>,
   TTableName extends keyof TTables,
 > extends RelationInit<TRelationType, TTables, TTableName> {
-  private foreignKeyName?: string;
-
-  private initForeignKey(ormName: string): ForeignKey {
-    const columns: AnyColumn[] = [];
-    const referencedColumns: AnyColumn[] = [];
-
-    for (const [left, right] of this.on) {
-      columns.push(this.referencer.columns[left]);
-      referencedColumns.push(this.referencedTable.columns[right]);
-    }
-
-    return {
-      columns,
-      referencedColumns,
-      referencedTable: this.referencedTable,
-      table: this.referencer,
-      name:
-        this.foreignKeyName ??
-        `${this.referencer.ormName}_${this.referencedTable.ormName}_${ormName}_fk`,
-    };
-  }
-
   init(ormName: string): Relation<TRelationType, TTables[TTableName]> {
     const id = `${this.referencer.ormName}_${this.referencedTable.ormName}`;
 
     return {
       id,
-      foreignKey: this.initForeignKey(ormName),
       on: this.on,
       name: ormName,
       referencer: this.referencer,
@@ -136,14 +105,6 @@ export class ExplicitRelationInit<
       type: this.type,
     };
   }
-
-  /**
-   * Define custom foreign key name.
-   */
-  foreignKey(name: string) {
-    this.foreignKeyName = name;
-    return this;
-  }
 }
 
 export interface Relation<
@@ -158,28 +119,36 @@ export interface Relation<
   referencer: AnyTable;
 
   on: [string, string][];
-  foreignKey: ForeignKey;
 }
 
 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>,
 > {
   name: string;
   ormName: string;
 
   columns: TColumns;
   relations: TRelations;
-  foreignKeys: ForeignKey[];
-  indexes: Index[];
+  indexes: TIndexes;
 
   /**
    * Get column by name
    */
   getColumnByName: (name: string) => AnyColumn | undefined;
+  /**
+   * Get the external ID column (user-facing)
+   */
   getIdColumn: () => AnyColumn;
-
-  clone: () => Table<TColumns, TRelations>;
+  /**
+   * Get the internal ID column (database-native, used for joins)
+   */
+  getInternalIdColumn: () => AnyColumn;
+  /**
+   * Get the version column (for optimistic concurrency control)
+   */
+  getVersionColumn: () => AnyColumn;
 }
 
 type DefaultFunctionMap = {
@@ -214,15 +183,16 @@ export class Column<TType extends keyof TypeMap, TIn = unknown, TOut = unknown>
   name: string = "";
   ormName: string = "";
   isNullable: boolean = false;
-  isUnique: boolean = false;
-  isReference: boolean = false;
+  role: "external-id" | "internal-id" | "version" | "reference" | "regular" = "regular";
+  isHidden: boolean = false;
+
   default?:
     | { value: TypeMap[TType] }
     | {
         runtime: DefaultFunction<TType>;
       };
 
-  table: AnyTable = undefined as unknown as AnyTable;
+  tableName: string = "";
 
   constructor(type: TType) {
     this.type = type;
@@ -238,6 +208,11 @@ export class Column<TType extends keyof TypeMap, TIn = unknown, TOut = unknown>
     >;
   }
 
+  hidden<THidden extends boolean = true>(hidden?: THidden) {
+    this.isHidden = hidden ?? true;
+    return this as Column<TType, null, null>;
+  }
+
   /**
    * Generate default value on runtime
    */
@@ -256,22 +231,6 @@ export class Column<TType extends keyof TypeMap, TIn = unknown, TOut = unknown>
     return this;
   }
 
-  clone() {
-    const clone = new Column(this.type);
-    clone.name = this.name;
-    clone.ormName = this.ormName;
-    clone.isNullable = this.isNullable;
-    clone.isUnique = this.isUnique;
-    clone.isReference = this.isReference;
-    clone.default = this.default;
-    clone.table = this.table;
-    return clone;
-  }
-
-  getUniqueConstraintName(): string {
-    return `unique_c_${this.table.ormName}_${this.ormName}`;
-  }
-
   /**
    * Generate default value for the column on runtime.
    */
@@ -293,11 +252,20 @@ export class Column<TType extends keyof TypeMap, TIn = unknown, TOut = unknown>
     return this.default.runtime();
   }
 
+  /**
+   * @description This is used for type inference only. Runtime value will be undefined.
+   * @internal
+   */
   get $in(): TIn {
-    throw new Error("Type inference only");
+    return undefined as unknown as TIn;
   }
+
+  /**
+   * @description This is used for type inference only. Runtime value will be undefined.
+   * @internal
+   */
   get $out(): TOut {
-    throw new Error("Type inference only");
+    return undefined as unknown as TOut;
   }
 }
 
@@ -308,18 +276,6 @@ export class IdColumn<
 > extends Column<TType, TIn, TOut> {
   id = true;
 
-  clone() {
-    const clone = new IdColumn(this.type);
-    clone.name = this.name;
-    clone.ormName = this.ormName;
-    clone.isNullable = this.isNullable;
-    clone.isUnique = this.isUnique;
-    clone.isReference = this.isReference;
-    clone.default = this.default;
-    clone.table = this.table;
-    return clone;
-  }
-
   override defaultTo$(fn: DefaultFunction<TType>) {
     return super.defaultTo$(fn) as IdColumn<TType, TIn | null, TOut>;
   }
@@ -329,6 +285,32 @@ export class IdColumn<
   }
 }
 
+/**
+ * Internal ID column - used for database-native joins and foreign keys.
+ * Hidden from user API by default.
+ */
+export class InternalIdColumn<TIn = unknown, TOut = unknown> extends Column<"bigint", TIn, TOut> {
+  override role = "internal-id" as const;
+
+  constructor() {
+    super("bigint");
+    this.hidden();
+  }
+}
+
+/**
+ * Version column - used for optimistic concurrency control.
+ * Automatically incremented on each update.
+ */
+export class VersionColumn<TIn = unknown, TOut = unknown> extends Column<"integer", TIn, TOut> {
+  override role = "version" as const;
+
+  constructor() {
+    super("integer");
+    this.defaultTo(0).hidden();
+  }
+}
+
 export function column<TType extends keyof TypeMap>(
   type: TType,
 ): Column<TType, TypeMap[TType], TypeMap[TType]> {
@@ -336,140 +318,316 @@ export function column<TType extends keyof TypeMap>(
 }
 
 /**
- * Create a reference column that points to another table.
+ * Create a reference column that points to another table's internal ID.
  * This is used for foreign key relationships.
+ * Always uses bigint to match the internal ID type.
  */
-export function referenceColumn<TType extends keyof TypeMap = "varchar(30)">(
-  type?: TType,
-): Column<TType, TypeMap[TType], TypeMap[TType]> {
-  const actualType = (type ?? "varchar(30)") as TType;
-  const col = new Column<TType, TypeMap[TType], TypeMap[TType]>(actualType);
-  col.isReference = true;
-  return col as Column<TType, TypeMap[TType], TypeMap[TType]>;
+export function referenceColumn(): Column<
+  "bigint",
+  string | bigint | FragnoId | FragnoReference,
+  FragnoReference
+> {
+  const col = new Column<"bigint", string | bigint | FragnoId | FragnoReference, FragnoReference>(
+    "bigint",
+  );
+  col.role = "reference";
+  return col;
 }
 
-export function idColumn(): IdColumn<"varchar(30)", string, string> {
-  const col = new IdColumn<"varchar(30)", string, string>("varchar(30)");
+/**
+ * Create an external ID column (user-facing).
+ * 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)");
+  col.role = "external-id";
   col.defaultTo$("auto");
-  return col as IdColumn<"varchar(30)", string, string>;
+  return col;
+}
+
+/**
+ * Create an internal ID column (database-native, hidden from user API).
+ * Used for joins and foreign keys.
+ * @internal
+ */
+export function internalIdColumn(): InternalIdColumn<null, bigint> {
+  const col = new InternalIdColumn<null, bigint>();
+  col.role = "internal-id";
+  col.hidden();
+  return col;
+}
+
+/**
+ * Create a version column for optimistic concurrency control.
+ * @internal
+ */
+export function versionColumn(): VersionColumn<null, number> {
+  const col = new VersionColumn<null, number>();
+  col.role = "version";
+  col.hidden();
+  return col;
 }
 
-type RelationType = "one";
+/**
+ * FragnoId represents a unified ID object that can contain external ID, internal ID, or both.
+ * @internal
+ *
+ * For query inputs: externalId is sufficient (internalId is optional)
+ * For query results: both externalId and internalId are provided
+ */
+export class FragnoId {
+  readonly #externalId: string;
+  readonly #internalId?: bigint;
+  readonly #version: number;
+
+  constructor({
+    externalId,
+    internalId,
+    version,
+  }: {
+    externalId: string;
+    internalId?: bigint;
+    version: number;
+  }) {
+    this.#externalId = externalId;
+    this.#internalId = internalId;
+    this.#version = version;
+  }
+
+  /**
+   * Create a FragnoId from just an external ID (for inputs)
+   */
+  static fromExternal(externalId: string, version: number): FragnoId {
+    return new FragnoId({ externalId, version });
+  }
+
+  get version(): number {
+    return this.#version;
+  }
+
+  get externalId(): string {
+    return this.#externalId;
+  }
+
+  get internalId(): bigint | undefined {
+    return this.#internalId;
+  }
+
+  /**
+   * Get the appropriate ID for database operations
+   * Prefers internal ID if available, falls back to external ID
+   */
+  get databaseId(): string | bigint {
+    return this.#internalId ?? this.#externalId;
+  }
+
+  /**
+   * Convert to a plain object for serialization
+   */
+  toJSON(): { externalId: string; internalId?: string } {
+    return {
+      externalId: this.#externalId,
+      internalId: this.#internalId?.toString(),
+    };
+  }
+
+  toString(): string {
+    return this.#externalId;
+  }
+
+  valueOf(): string {
+    return this.#externalId;
+  }
+}
+
+/**
+ * FragnoReference represents a foreign key reference to another table's internal ID.
+ * Unlike FragnoId, it only contains the internal ID (bigint) of the referenced record.
+ * This is used for reference columns in query results.
+ * @internal
+ */
+export class FragnoReference {
+  readonly #internalId: bigint;
+
+  constructor(internalId: bigint) {
+    this.#internalId = internalId;
+  }
+
+  /**
+   * Create a FragnoReference from an internal ID
+   */
+  static fromInternal(internalId: bigint): FragnoReference {
+    return new FragnoReference(internalId);
+  }
+
+  /**
+   * Get the internal ID for database operations
+   */
+  get internalId(): bigint {
+    return this.#internalId;
+  }
+}
+
+type RelationType = "one" | "many";
 
 export class TableBuilder<
   TColumns extends Record<string, AnyColumn> = Record<string, AnyColumn>,
   TRelations extends Record<string, AnyRelation> = Record<string, AnyRelation>,
+  TIndexes extends Record<string, Index> = Record<string, Index>,
 > {
   #name: string;
   #columns: TColumns;
   #relations: TRelations;
-  #foreignKeys: ForeignKey[] = [];
-  #indexes: Index[] = [];
-  #version: number = 0;
+  #indexes: TIndexes;
   #ormName: string = "";
-  #operations: TableOperation[] = [];
+  #columnOrder: string[] = [];
 
   constructor(name: string) {
     this.#name = name;
     this.#columns = {} as TColumns;
     this.#relations = {} as TRelations;
+    this.#indexes = {} as TIndexes;
+  }
+
+  // For alterTable to set existing state
+  setColumns(columns: TColumns): void {
+    this.#columns = { ...columns };
+  }
+
+  setRelations(relations: TRelations): void {
+    this.#relations = { ...relations };
+  }
+
+  setIndexes(indexes: TIndexes): void {
+    this.#indexes = { ...indexes };
+  }
+
+  // For SchemaBuilder to read collected indexes
+  getIndexes(): Index[] {
+    return Object.values(this.#indexes) as Index[];
+  }
+
+  getColumnOrder(): string[] {
+    return this.#columnOrder;
   }
 
   /**
-   * Add a column to the table. Increments the version counter.
+   * Add a column to the table.
    */
   addColumn<TColumnName extends string, TColumn extends AnyColumn>(
     ormName: TColumnName,
     col: TColumn,
-  ): TableBuilder<TColumns & Record<TColumnName, TColumn>, TRelations>;
+  ): TableBuilder<TColumns & Record<TColumnName, TColumn>, TRelations, TIndexes>;
 
   /**
-   * Add a column to the table with simplified syntax. Increments the version counter.
+   * Add a column to the table with simplified syntax.
    */
   addColumn<TColumnName extends string, TType extends keyof TypeMap>(
     ormName: TColumnName,
     type: TType,
   ): TableBuilder<
     TColumns & Record<TColumnName, Column<TType, TypeMap[TType], TypeMap[TType]>>,
-    TRelations
+    TRelations,
+    TIndexes
   >;
 
   addColumn<TColumnName extends string, TColumn extends AnyColumn, TType extends keyof TypeMap>(
     ormName: TColumnName,
     colOrType: TColumn | TType,
-  ): TableBuilder<TColumns & Record<TColumnName, TColumn>, TRelations> {
-    this.#version++;
-
+  ): TableBuilder<TColumns & Record<TColumnName, TColumn>, TRelations, TIndexes> {
     // Create the column if a type string was provided
     const col = typeof colOrType === "string" ? column(colOrType) : colOrType;
 
-    // Create a new instance to ensure immutability semantics
-    const builder = new TableBuilder<TColumns & Record<TColumnName, TColumn>, TRelations>(
-      this.#name,
-    );
-    builder.#columns = { ...this.#columns, [ormName]: col } as TColumns &
-      Record<TColumnName, TColumn>;
-    builder.#relations = this.#relations;
-    builder.#foreignKeys = this.#foreignKeys;
-    builder.#indexes = this.#indexes;
-    builder.#version = this.#version;
-    builder.#ormName = this.#ormName;
-    builder.#operations = this.#operations;
-
     // Set column metadata
     col.ormName = ormName;
     col.name = ormName;
 
-    return builder;
+    // Add column directly to this builder
+    this.#columns[ormName] = col as unknown as TColumns[TColumnName];
+    this.#columnOrder.push(ormName);
+
+    return this as unknown as TableBuilder<
+      TColumns & Record<TColumnName, TColumn>,
+      TRelations,
+      TIndexes
+    >;
   }
 
   /**
-   * Create an index on the specified columns. Increments the version counter.
+   * Create an index on the specified columns.
    */
-  createIndex<TColumnName extends string & keyof TColumns>(
-    name: string,
-    columns: TColumnName[],
+  createIndex<
+    TIndexName extends string,
+    const TColumnNames extends readonly (string & keyof TColumns)[],
+  >(
+    name: TIndexName,
+    columns: TColumnNames,
     options?: { unique?: boolean },
-  ): TableBuilder<TColumns, TRelations> {
-    this.#version++;
-
-    const cols = columns.map((name) => {
-      const column = this.#columns[name];
+  ): TableBuilder<
+    TColumns,
+    TRelations,
+    TIndexes & Record<TIndexName, Index<ColumnsToTuple<TColumns, TColumnNames>, TColumnNames>>
+  > {
+    const cols = columns.map((colName) => {
+      const column = this.#columns[colName];
       if (!column) {
-        throw new Error(`Unknown column name ${name}`);
+        throw new Error(`Unknown column name ${colName}`);
       }
       return column;
     });
 
     const unique = options?.unique ?? false;
-    addIndexToTable(this.#indexes, name, cols, unique);
-
-    // Record the operation
-    this.#operations.push({
-      type: "add-index",
+    // Safe: we're adding the index to the internal indexes object
+    this.#indexes[name] = {
       name,
-      columns: columns as string[],
+      columns: cols,
+      columnNames: columns,
       unique,
-    });
+    } as unknown as TIndexes[TIndexName];
 
-    return this;
+    return this as unknown as TableBuilder<
+      TColumns,
+      TRelations,
+      TIndexes & Record<TIndexName, Index<ColumnsToTuple<TColumns, TColumnNames>, TColumnNames>>
+    >;
   }
 
   /**
    * Build the final table. This should be called after all columns are added.
    */
-  build(): Table<TColumns, TRelations> {
+  build(): Table<TColumns, TRelations, TIndexes> {
     let idCol: AnyColumn | undefined;
+    let internalIdCol: AnyColumn | undefined;
+    let versionCol: AnyColumn | undefined;
+
+    // TODO: Throw if user manually added version/internalId columns
+
+    // 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;
+    }
+
+    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> = {
+    const table: Table<TColumns, TRelations, TIndexes> = {
       name: this.#name,
       ormName,
       columns: this.#columns,
       relations: this.#relations,
-      foreignKeys: this.#foreignKeys,
       indexes: this.#indexes,
       getColumnByName: (name) => {
         return Object.values(this.#columns).find((c) => c.name === name);
@@ -477,78 +635,45 @@ export class TableBuilder<
       getIdColumn: () => {
         return idCol!;
       },
-      clone: () => {
-        const cloneColumns: Record<string, AnyColumn> = {};
-
-        for (const [k, v] of Object.entries(this.#columns)) {
-          cloneColumns[k] = v.clone();
-        }
-
-        const builder = new TableBuilder<TColumns, TRelations>(this.#name);
-        builder.#columns = cloneColumns as TColumns;
-        builder.#relations = this.#relations;
-        builder.#foreignKeys = [...this.#foreignKeys];
-        builder.#indexes = [...this.#indexes];
-        builder.#version = this.#version;
-        builder.#ormName = this.#ormName;
-        builder.#operations = [...this.#operations];
-
-        const cloned = builder.build();
-
-        return cloned;
+      getInternalIdColumn: () => {
+        return internalIdCol!;
+      },
+      getVersionColumn: () => {
+        return versionCol!;
       },
     };
 
-    // Set table reference and find id column
+    // Set table reference and find special columns
     for (const k in this.#columns) {
       const column = this.#columns[k];
       if (!column) {
         continue;
       }
 
-      column.table = table;
-      if (column instanceof IdColumn) {
+      column.tableName = table.name;
+      if (column instanceof IdColumn || column.role === "external-id") {
         idCol = column;
       }
+      if (column instanceof InternalIdColumn || column.role === "internal-id") {
+        internalIdCol = column;
+      }
+      if (column instanceof VersionColumn || column.role === "version") {
+        versionCol = column;
+      }
     }
 
     if (idCol === undefined) {
       throw new Error(`there's no id column in your table ${this.#name}`);
     }
+    if (internalIdCol === undefined) {
+      throw new Error(`there's no internal id column in your table ${this.#name}`);
+    }
+    if (versionCol === undefined) {
+      throw new Error(`there's no version column in your table ${this.#name}`);
+    }
 
     return table;
   }
-
-  /**
-   * Get the current version of the table builder.
-   */
-  getVersion(): number {
-    return this.#version;
-  }
-
-  /**
-   * Get the operations performed on this table.
-   */
-  getOperations(): TableOperation[] {
-    return this.#operations;
-  }
-}
-
-/**
- * Create a new table with callback pattern.
- */
-export function table<
-  TColumns extends Record<string, AnyColumn> = Record<string, AnyColumn>,
-  TRelations extends Record<string, AnyRelation> = Record<string, AnyRelation>,
->(
-  name: string,
-  callback: (
-    builder: TableBuilder<Record<string, AnyColumn>, Record<string, AnyRelation>>,
-  ) => TableBuilder<TColumns, TRelations>,
-): Table<TColumns, TRelations> {
-  const builder = new TableBuilder(name);
-  const result = callback(builder);
-  return result.build();
 }
 
 export interface Schema<TTables extends Record<string, AnyTable> = Record<string, AnyTable>> {
@@ -566,13 +691,90 @@ export interface Schema<TTables extends Record<string, AnyTable> = Record<string
   clone: () => Schema<TTables>;
 }
 
-export class SchemaBuilder<TTables extends Record<string, AnyTable> = Record<string, never>> {
+/**
+ * Utility type for updating a single table's relations in a schema.
+ * Used to properly type the return value of addReference.
+ */
+type UpdateTableRelations<
+  TTables extends Record<string, AnyTable>,
+  TTableName extends keyof TTables,
+  TReferenceName extends string,
+  TReferencedTableName extends keyof TTables,
+  TRelationType extends RelationType = RelationType,
+> = {
+  [K in keyof TTables]: K extends TTableName
+    ? Table<
+        TTables[TTableName]["columns"],
+        TTables[TTableName]["relations"] &
+          Record<TReferenceName, Relation<TRelationType, TTables[TReferencedTableName]>>,
+        TTables[TTableName]["indexes"]
+      >
+    : TTables[K];
+};
+
+/**
+ * Utility type for updating a single table in a schema.
+ * Used to properly type the return value of alterTable.
+ */
+type UpdateTable<
+  TTables extends Record<string, AnyTable>,
+  TTableName extends keyof TTables,
+  TNewColumns extends Record<string, AnyColumn>,
+  TNewRelations extends Record<string, AnyRelation>,
+  TNewIndexes extends Record<string, Index>,
+> = {
+  [K in keyof TTables]: K extends TTableName
+    ? Table<TNewColumns, TNewRelations, TNewIndexes>
+    : TTables[K];
+};
+
+/**
+ * Map an array of column names to a tuple of their actual column types
+ */
+type ColumnsToTuple<
+  TColumns extends Record<string, AnyColumn>,
+  TColumnNames extends readonly (keyof TColumns)[],
+> = {
+  [K in keyof TColumnNames]: TColumnNames[K] extends keyof TColumns
+    ? TColumns[TColumnNames[K]]
+    : never;
+} & AnyColumn[];
+
+export class SchemaBuilder<TTables extends Record<string, AnyTable> = {}> {
   #tables: TTables;
   #version: number = 0;
   #operations: SchemaOperation[] = [];
 
-  constructor() {
-    this.#tables = {} as TTables;
+  constructor(existingSchema?: Schema<TTables>) {
+    if (existingSchema) {
+      this.#tables = existingSchema.tables;
+      this.#version = existingSchema.version;
+      this.#operations = [...existingSchema.operations];
+    } else {
+      this.#tables = {} as TTables;
+    }
+  }
+
+  /**
+   * Add an existing schema to this builder.
+   * Merges tables and operations from the provided schema.
+   *
+   * @example
+   * ```ts
+   * const builder = new SchemaBuilder()
+   *   .add(userSchema)
+   *   .add(postSchema)
+   *   .addTable("comments", ...);
+   * ```
+   */
+  mergeWithExistingSchema<TNewTables extends Record<string, AnyTable>>(
+    schema: Schema<TNewTables>,
+  ): SchemaBuilder<TTables & TNewTables> {
+    this.#tables = { ...this.#tables, ...schema.tables } as TTables & TNewTables;
+    this.#operations = [...this.#operations, ...schema.operations];
+    this.#version += schema.version;
+
+    return this as unknown as SchemaBuilder<TTables & TNewTables>;
   }
 
   /**
@@ -582,172 +784,309 @@ export class SchemaBuilder<TTables extends Record<string, AnyTable> = Record<str
     TTableName extends string,
     TColumns extends Record<string, AnyColumn>,
     TRelations extends Record<string, AnyRelation>,
+    TIndexes extends Record<string, Index> = Record<string, Index>,
   >(
     ormName: TTableName,
     callback: (
-      builder: TableBuilder<Record<string, AnyColumn>, Record<string, AnyRelation>>,
-    ) => TableBuilder<TColumns, TRelations>,
-  ): SchemaBuilder<TTables & Record<TTableName, Table<TColumns, TRelations>>> {
+      builder: TableBuilder<
+        Record<string, AnyColumn>,
+        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);
     const result = callback(tableBuilder);
     const builtTable = result.build();
-
-    // Set table metadata
     builtTable.ormName = ormName;
 
-    const builder = new SchemaBuilder<TTables & Record<TTableName, Table<TColumns, TRelations>>>();
-    builder.#tables = { ...this.#tables, [ormName]: builtTable } as TTables &
-      Record<TTableName, Table<TColumns, TRelations>>;
-
-    // Start with existing operations plus the add-table operation
-    const newOperations: SchemaOperation[] = [
-      ...this.#operations,
-      {
-        type: "add-table",
-        tableName: ormName,
-        table: builtTable,
-      },
-    ];
-
-    // Promote table operations to schema operations and increment version for each
-    const tableOps = result.getOperations();
-    for (const tableOp of tableOps) {
-      if (tableOp.type === "add-index") {
-        this.#version++;
-        newOperations.push({
-          type: "add-index",
-          tableName: ormName,
-          name: tableOp.name,
-          columns: tableOp.columns,
-          unique: tableOp.unique,
-        });
-      }
+    // Collect sub-operations in order
+    const subOperations: TableSubOperation[] = [];
+
+    // Add user-defined columns first
+    const columnOrder = result.getColumnOrder();
+    for (const colName of columnOrder) {
+      const col = builtTable.columns[colName];
+      subOperations.push({
+        type: "add-column",
+        columnName: colName,
+        column: col,
+      });
     }
 
-    builder.#version = this.#version;
-    builder.#operations = newOperations;
+    // Add system columns (_internalId and _version) that were auto-added
+    if (builtTable.columns["_internalId"]) {
+      subOperations.push({
+        type: "add-column",
+        columnName: "_internalId",
+        column: builtTable.columns["_internalId"],
+      });
+    }
+    if (builtTable.columns["_version"]) {
+      subOperations.push({
+        type: "add-column",
+        columnName: "_version",
+        column: builtTable.columns["_version"],
+      });
+    }
 
-    return builder;
+    // Add indexes from builder
+    for (const idx of result.getIndexes()) {
+      subOperations.push({
+        type: "add-index",
+        name: idx.name,
+        columns: idx.columns.map((c) => c.ormName),
+        unique: idx.unique,
+      });
+    }
+
+    // Add the add-table operation
+    this.#operations.push({
+      type: "add-table",
+      tableName: ormName,
+      operations: subOperations,
+    });
+
+    // Update tables map
+    this.#tables = { ...this.#tables, [ormName]: builtTable } as TTables &
+      Record<TTableName, Table<TColumns, TRelations, TIndexes>>;
+
+    return this as unknown as SchemaBuilder<
+      TTables & Record<TTableName, Table<TColumns, TRelations, TIndexes>>
+    >;
   }
 
   /**
-   * Add a foreign key reference from this table to another table.
+   * Add a relation between two tables.
    *
-   * @param tableName - The table that has the foreign key column
-   * @param referenceName - A name for this reference (e.g., "author", "category")
-   * @param config - Configuration specifying the foreign key mapping
+   * @param referenceName - A name for this relation (e.g., "author", "posts")
+   * @param config - Configuration specifying the relation type and foreign key mapping
    *
    * @example
    * ```ts
-   * // Basic foreign key: post -> user
+   * // One-to-one or many-to-one: post -> user
    * schema(s => s
    *   .addTable("users", t => t.addColumn("id", idColumn()))
    *   .addTable("posts", t => t
    *     .addColumn("id", idColumn())
-   *     .addColumn("authorId", referenceColumn()))
-   *   .addReference("posts", "author", {
-   *     columns: ["authorId"],
-   *     targetTable: "users",
-   *     targetColumns: ["id"],
+   *     .addColumn("userId", referenceColumn()))
+   *   .addReference("author", {
+   *     type: "one",
+   *     from: { table: "posts", column: "userId" },
+   *     to: { table: "users", column: "id" },
    *   })
    * )
    *
-   * // Self-referencing foreign key
-   * .addReference("users", "inviter", {
-   *   columns: ["invitedBy"],
-   *   targetTable: "users",
-   *   targetColumns: ["id"],
+   * // One-to-many (inverse relation): user -> posts
+   * .addReference("posts", {
+   *   type: "many",
+   *   from: { table: "users", column: "id" },
+   *   to: { table: "posts", column: "userId" },
    * })
    *
-   * // Multiple foreign keys - call addReference multiple times
-   * .addReference("posts", "author", {
-   *   columns: ["authorId"],
-   *   targetTable: "users",
-   *   targetColumns: ["id"],
-   * })
-   * .addReference("posts", "category", {
-   *   columns: ["categoryId"],
-   *   targetTable: "categories",
-   *   targetColumns: ["id"],
+   * // Self-referencing foreign key
+   * .addReference("inviter", {
+   *   type: "one",
+   *   from: { table: "users", column: "invitedBy" },
+   *   to: { table: "users", column: "id" },
    * })
    * ```
    */
   addReference<
-    TTableName extends string & keyof TTables,
-    TReferencedTableName extends string & keyof TTables,
+    TFromTableName extends string & keyof TTables,
+    TToTableName extends string & keyof TTables,
+    TReferenceName extends string,
+    TRelationType extends RelationType,
   >(
-    tableName: TTableName,
-    referenceName: string,
+    referenceName: TReferenceName,
     config: {
-      columns: (keyof TTables[TTableName]["columns"])[];
-      targetTable: TReferencedTableName;
-      targetColumns: (keyof TTables[TReferencedTableName]["columns"])[];
+      type: TRelationType;
+      from: {
+        table: TFromTableName;
+        column: keyof TTables[TFromTableName]["columns"];
+      };
+      to: {
+        table: TToTableName;
+        column: keyof TTables[TToTableName]["columns"];
+      };
     },
-  ): SchemaBuilder<TTables> {
+  ): SchemaBuilder<
+    UpdateTableRelations<TTables, TFromTableName, TReferenceName, TToTableName, TRelationType>
+  > {
     this.#version++;
 
-    const table = this.#tables[tableName];
-    const referencedTable = this.#tables[config.targetTable];
+    const table = this.#tables[config.from.table];
+    const referencedTable = this.#tables[config.to.table];
 
     if (!table) {
-      throw new Error(`Table ${tableName} not found in schema`);
+      throw new Error(`Table ${config.from.table} not found in schema`);
     }
     if (!referencedTable) {
-      throw new Error(`Referenced table ${config.targetTable} not found in schema`);
+      throw new Error(`Referenced table ${config.to.table} not found in schema`);
     }
 
-    const { columns, targetColumns } = config;
+    const columnName = config.from.column as string;
+    const targetColumnName = config.to.column as string;
 
-    if (columns.length !== targetColumns.length) {
-      throw new Error(
-        `Reference ${referenceName}: columns and targetColumns must have the same length`,
-      );
-    }
-
-    // For now, only support single column foreign keys
-    if (columns.length !== 1) {
-      throw new Error(
-        `Reference ${referenceName}: currently only single column foreign keys are supported`,
-      );
-    }
-
-    const columnName = columns[0] as string;
-    const targetColumnName = targetColumns[0] 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 column = table.columns[columnName];
-    const referencedColumn = referencedTable.columns[targetColumnName];
+    const referencedColumn = referencedTable.columns[actualTargetColumnName];
 
     if (!column) {
-      throw new Error(`Column ${columnName} not found in table ${tableName}`);
+      throw new Error(`Column ${columnName} not found in table ${config.from.table}`);
     }
     if (!referencedColumn) {
-      throw new Error(`Column ${targetColumnName} not found in table ${config.targetTable}`);
+      throw new Error(`Column ${actualTargetColumnName} not found in table ${config.to.table}`);
+    }
+
+    // Verify that reference columns are bigint (matching internal ID type)
+    if (column.role === "reference" && column.type !== "bigint") {
+      throw new Error(
+        `Reference column ${columnName} must be of type bigint to match internal ID type`,
+      );
     }
 
-    // Create the relation
-    const init = new ExplicitRelationInit("one", referencedTable, table);
+    // 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]);
     const relation = init.init(referenceName);
 
-    // Add relation and foreign key to the table
+    // Add relation to the table
     table.relations[referenceName] = relation;
-    table.foreignKeys.push(relation.foreignKey);
 
     // Record the operation
     this.#operations.push({
       type: "add-reference",
-      tableName: tableName as string,
+      tableName: config.from.table,
       referenceName,
       config: {
-        columns: columns as string[],
-        targetTable: config.targetTable as string,
-        targetColumns: targetColumns as string[],
+        type: config.type,
+        from: { table: config.from.table, column: columnName },
+        to: { table: config.to.table, column: actualTargetColumnName },
       },
     });
 
-    return this;
+    // Return this with updated type
+    // Safe: The relation was added to the table in place and now has the updated relations
+    return this as unknown as SchemaBuilder<
+      UpdateTableRelations<TTables, TFromTableName, TReferenceName, TToTableName, TRelationType>
+    >;
+  }
+
+  /**
+   * Alter an existing table by adding columns or indexes.
+   * This is used for append-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
+   *
+   * @example
+   * ```ts
+   * // Add a new column to an existing table
+   * schema(s => s
+   *   .addTable("users", t => t
+   *     .addColumn("id", idColumn())
+   *     .addColumn("name", column("string")))
+   *   .alterTable("users", t => t
+   *     .addColumn("email", column("string"))
+   *     .addColumn("age", column("integer").nullable())
+   *     .createIndex("idx_email", ["email"]))
+   * )
+   * ```
+   */
+  alterTable<
+    TTableName extends string & keyof TTables,
+    TNewColumns extends Record<string, AnyColumn>,
+    TNewRelations extends Record<string, AnyRelation>,
+    TNewIndexes extends Record<string, Index> = Record<string, Index>,
+  >(
+    tableName: TTableName,
+    callback: (
+      builder: TableBuilder<
+        TTables[TTableName]["columns"],
+        TTables[TTableName]["relations"],
+        Record<string, Index>
+      >,
+    ) => TableBuilder<TNewColumns, TNewRelations, TNewIndexes>,
+  ): SchemaBuilder<UpdateTable<TTables, TTableName, TNewColumns, TNewRelations, TNewIndexes>> {
+    const table = this.#tables[tableName];
+
+    if (!table) {
+      throw new Error(`Table ${tableName} not found in schema`);
+    }
+
+    // Create builder with existing table state
+    const tableBuilder = new TableBuilder(tableName);
+    tableBuilder.setColumns(table.columns);
+    tableBuilder.setRelations(table.relations);
+    tableBuilder.setIndexes(table.indexes);
+
+    // Track existing columns and indexes
+    const existingColumns = new Set(Object.keys(table.columns));
+    const existingIndexes = new Set(Object.keys(table.indexes));
+
+    // Apply modifications
+    const resultBuilder = callback(
+      tableBuilder as TableBuilder<
+        TTables[TTableName]["columns"],
+        TTables[TTableName]["relations"],
+        Record<string, Index>
+      >,
+    );
+    const newTable = resultBuilder.build();
+
+    // Collect sub-operations
+    const subOperations: TableSubOperation[] = [];
+
+    // Find new columns (preserve order from builder)
+    const columnOrder = resultBuilder.getColumnOrder();
+    for (const colName of columnOrder) {
+      if (!existingColumns.has(colName)) {
+        subOperations.push({
+          type: "add-column",
+          columnName: colName,
+          column: newTable.columns[colName],
+        });
+      }
+    }
+
+    // Add only new indexes
+    for (const idx of resultBuilder.getIndexes()) {
+      if (!existingIndexes.has(idx.name)) {
+        subOperations.push({
+          type: "add-index",
+          name: idx.name,
+          columns: idx.columns.map((c) => c.ormName),
+          unique: idx.unique,
+        });
+      }
+    }
+
+    if (subOperations.length > 0) {
+      this.#version++;
+      this.#operations.push({
+        type: "alter-table",
+        tableName,
+        operations: subOperations,
+      });
+    }
+
+    // Update table reference in schema
+    this.#tables[tableName] = newTable as unknown as TTables[TTableName];
+
+    // Set table name for all columns
+    for (const col of Object.values(newTable.columns)) {
+      col.tableName = newTable.name;
+    }
+
+    return this as unknown as SchemaBuilder<
+      UpdateTable<TTables, TTableName, TNewColumns, TNewRelations, TNewIndexes>
+    >;
   }
 
   /**
@@ -766,15 +1105,45 @@ export class SchemaBuilder<TTables extends Record<string, AnyTable> = Record<str
         const cloneTables: Record<string, AnyTable> = {};
 
         for (const [k, v] of Object.entries(tables)) {
-          cloneTables[k] = v.clone();
+          // Create a new table with cloned columns
+          const clonedColumns: Record<string, AnyColumn> = {};
+          for (const [colName, col] of Object.entries(v.columns)) {
+            // Create a new column with the same properties, preserving the column type
+            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.ormName = col.ormName;
+            clonedCol.isNullable = col.isNullable;
+            clonedCol.role = col.role;
+            clonedCol.isHidden = col.isHidden;
+            clonedCol.default = col.default;
+            clonedCol.tableName = col.tableName;
+            clonedColumns[colName] = clonedCol;
+          }
+
+          cloneTables[k] = {
+            ...v,
+            columns: clonedColumns,
+          };
         }
 
-        const builder = new SchemaBuilder<TTables>();
-        builder.#tables = cloneTables as TTables;
-        builder.#version = version;
-        builder.#operations = [...operations];
-
-        return builder.build();
+        return new SchemaBuilder<TTables>({
+          version,
+          tables: cloneTables as TTables,
+          operations: [...operations],
+          clone: () => {
+            throw new Error("Cannot clone during clone");
+          },
+        }).build();
       },
     };
 
@@ -792,18 +1161,20 @@ export class SchemaBuilder<TTables extends Record<string, AnyTable> = Record<str
 /**
  * Create a new schema with callback pattern.
  */
-export function schema<TTables extends Record<string, AnyTable> = Record<string, never>>(
-  callback: (builder: SchemaBuilder<Record<string, never>>) => SchemaBuilder<TTables>,
+export function schema<const TTables extends Record<string, AnyTable> = {}>(
+  callback: (builder: SchemaBuilder<{}>) => SchemaBuilder<TTables>,
 ): Schema<TTables> {
   return callback(new SchemaBuilder()).build();
 }
 
-export function compileForeignKey(key: ForeignKey) {
+export function compileForeignKey(key: ForeignKey, nameType: "sql" | "orm" = "orm") {
   return {
     name: key.name,
-    table: key.table.name,
-    referencedTable: key.referencedTable.name,
-    referencedColumns: key.referencedColumns.map((col) => col.name),
-    columns: key.columns.map((col) => col.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)),
   };
 }