@fragno-dev/db 0.0.1

package/src/migration-engine/auto-from-schema.test.ts

@@ -0,0 +1,238 @@
+import { describe, expect, it } from "vitest";
+import { column, idColumn, referenceColumn, schema } from "../schema/create";
+import { generateMigrationFromSchema } from "./auto-from-schema";
+
+describe("generateMigrationFromSchema", () => {
+  it("should generate create-table operation for new tables", () => {
+    const mySchema = schema((s) => {
+      return s
+        .addTable("users", (t) => {
+          return t.addColumn("id", idColumn()).addColumn("name", column("string"));
+        })
+        .addTable("posts", (t) => {
+          return t
+            .addColumn("id", idColumn())
+            .addColumn("title", column("string"))
+            .addColumn("content", column("string"));
+        });
+    });
+
+    // Version 0 -> 1: users table created
+    // Version 1 -> 2: posts table created
+    // We want to generate the migration for version 1 -> 2
+    const operations = generateMigrationFromSchema(mySchema, 1, 2, {
+      provider: "postgresql",
+    });
+
+    expect(operations).toHaveLength(1);
+    expect(operations[0]).toMatchObject({
+      type: "create-table",
+      value: mySchema.tables.posts,
+    });
+  });
+
+  it("should generate multiple table operations in sequence", () => {
+    const mySchema = schema((s) => {
+      return s
+        .addTable("users", (t) => {
+          return t.addColumn("id", idColumn()).addColumn("name", column("string"));
+        })
+        .addTable("posts", (t) => {
+          return t.addColumn("id", idColumn()).addColumn("title", column("string"));
+        })
+        .addTable("comments", (t) => {
+          return t.addColumn("id", idColumn()).addColumn("text", column("string"));
+        });
+    });
+
+    // Generate migrations from version 0 to 3 (all three tables)
+    const operations = generateMigrationFromSchema(mySchema, 0, 3, {
+      provider: "postgresql",
+    });
+
+    expect(operations).toHaveLength(3);
+    expect(operations[0]).toMatchObject({
+      type: "create-table",
+      value: mySchema.tables.users,
+    });
+    expect(operations[1]).toMatchObject({
+      type: "create-table",
+      value: mySchema.tables.posts,
+    });
+    expect(operations[2]).toMatchObject({
+      type: "create-table",
+      value: mySchema.tables.comments,
+    });
+  });
+
+  it("should generate add-foreign-key operation for new foreign keys", () => {
+    const mySchema = schema((s) => {
+      return s
+        .addTable("users", (t) => {
+          return t.addColumn("id", idColumn());
+        })
+        .addTable("posts", (t) => {
+          return t.addColumn("id", idColumn()).addColumn("authorId", referenceColumn());
+        })
+        .addReference("posts", "author", {
+          columns: ["authorId"],
+          targetTable: "users",
+          targetColumns: ["id"],
+        });
+    });
+
+    // Version 0 -> 1: users table
+    // Version 1 -> 2: posts table
+    // Version 2 -> 3: author foreign key
+    const operations = generateMigrationFromSchema(mySchema, 2, 3, {
+      provider: "postgresql",
+    });
+
+    expect(operations).toHaveLength(1);
+    expect(operations[0]).toMatchObject({
+      type: "add-foreign-key",
+      table: "posts",
+    });
+
+    const fkOp = operations[0];
+    if (fkOp.type === "add-foreign-key") {
+      expect(fkOp.value).toMatchObject({
+        name: "posts_users_author_fk",
+        table: "posts",
+        referencedTable: "users",
+        columns: ["authorId"],
+        referencedColumns: ["id"],
+      });
+    }
+  });
+
+  it("should generate add-index operation for indexes defined in createIndex", () => {
+    const mySchema = schema((s) => {
+      return s.addTable("users", (t) => {
+        return t
+          .addColumn("id", idColumn())
+          .addColumn("email", column("string"))
+          .createIndex("idx_email", ["email"], { unique: true });
+      });
+    });
+
+    // Version 0 -> 1: users table
+    // Version 1 -> 2: email index
+    const operations = generateMigrationFromSchema(mySchema, 1, 2, {
+      provider: "postgresql",
+    });
+
+    expect(operations).toHaveLength(1);
+    expect(operations[0]).toMatchObject({
+      type: "add-index",
+      table: "users",
+      name: "idx_email",
+      columns: ["email"],
+      unique: true,
+    });
+  });
+
+  it("should generate mixed operations for tables and foreign keys", () => {
+    const mySchema = schema((s) => {
+      return s
+        .addTable("users", (t) => {
+          return t.addColumn("id", idColumn()).addColumn("name", column("string"));
+        })
+        .addTable("posts", (t) => {
+          return t.addColumn("id", idColumn()).addColumn("authorId", referenceColumn());
+        })
+        .addReference("posts", "author", {
+          columns: ["authorId"],
+          targetTable: "users",
+          targetColumns: ["id"],
+        });
+    });
+
+    // Generate all migrations from scratch
+    const operations = generateMigrationFromSchema(mySchema, 0, 3, {
+      provider: "postgresql",
+    });
+
+    expect(operations).toHaveLength(3);
+    expect(operations[0].type).toBe("create-table");
+    expect(operations[1].type).toBe("create-table");
+    expect(operations[2].type).toBe("add-foreign-key");
+  });
+
+  it("should generate mixed operations for tables, indexes, and foreign keys", () => {
+    const mySchema = schema((s) => {
+      return s
+        .addTable("users", (t) => {
+          return t
+            .addColumn("id", idColumn())
+            .addColumn("email", column("string"))
+            .createIndex("idx_email", ["email"], { unique: true });
+        })
+        .addTable("posts", (t) => {
+          return t.addColumn("id", idColumn()).addColumn("authorId", referenceColumn());
+        })
+        .addReference("posts", "author", {
+          columns: ["authorId"],
+          targetTable: "users",
+          targetColumns: ["id"],
+        });
+    });
+
+    // Generate all migrations from scratch
+    const operations = generateMigrationFromSchema(mySchema, 0, 4, {
+      provider: "postgresql",
+    });
+
+    expect(operations).toHaveLength(4);
+    expect(operations[0].type).toBe("create-table");
+    expect(operations[1].type).toBe("add-index");
+    expect(operations[2].type).toBe("create-table");
+    expect(operations[3].type).toBe("add-foreign-key");
+  });
+
+  it("should generate no operations when version range is empty", () => {
+    const mySchema = schema((s) => {
+      return s.addTable("users", (t) => {
+        return t.addColumn("id", idColumn()).addColumn("name", column("string"));
+      });
+    });
+
+    const operations = generateMigrationFromSchema(mySchema, 1, 1, {
+      provider: "postgresql",
+    });
+
+    expect(operations).toHaveLength(0);
+  });
+
+  it("should throw error when fromVersion exceeds schema version", () => {
+    const mySchema = schema((s) => s.addTable("users", (t) => t.addColumn("id", idColumn())));
+
+    expect(() => {
+      generateMigrationFromSchema(mySchema, 999, 1000, { provider: "postgresql" });
+    }).toThrow("fromVersion (999) exceeds schema version (1)");
+  });
+
+  it("should throw error when toVersion exceeds schema version", () => {
+    const mySchema = schema((s) => s.addTable("users", (t) => t.addColumn("id", idColumn())));
+
+    expect(() => {
+      generateMigrationFromSchema(mySchema, 0, 999, { provider: "postgresql" });
+    }).toThrow("toVersion (999) exceeds schema version (1)");
+  });
+
+  it("should throw error when trying to migrate backwards", () => {
+    const mySchema = schema((s) => s.addTable("users", (t) => t.addColumn("id", idColumn())));
+
+    expect(() => {
+      generateMigrationFromSchema(mySchema, 1, 0, { provider: "postgresql" });
+    }).toThrow("Cannot migrate backwards");
+  });
+
+  it("should throw error for negative fromVersion", () => {
+    const mySchema = schema((s) => s.addTable("users", (t) => t.addColumn("id", idColumn())));
+
+    expect(() => {
+      generateMigrationFromSchema(mySchema, -1, 1, { provider: "postgresql" });
+    }).toThrow("fromVersion cannot be negative");
+  });
+});

package/src/migration-engine/auto-from-schema.ts

@@ -0,0 +1,106 @@
+import { compileForeignKey, type AnySchema } from "../schema/create";
+import type { MigrationOperation } from "./shared";
+import type { Provider } from "../shared/providers";
+
+/**
+ * Generate migration operations from a schema's operation history
+ *
+ * The schema version number represents the cumulative number of operations applied.
+ * This function takes operations from the schema between fromVersion and toVersion,
+ * and converts them into migration operations.
+ *
+ * @param targetSchema - The schema containing the operations history
+ * @param fromVersion - The current database version (e.g., 0)
+ * @param toVersion - The target version to migrate to (e.g., 5)
+ * @param options - Migration generation options
+ * @returns Array of migration operations to apply
+ *
+ * @example
+ * ```ts
+ * const mySchema = schema(s => s
+ *   .addTable("users", t => t.addColumn("id", idColumn()))       // version 1
+ *   .addTable("posts", t => t.addColumn("id", idColumn()))       // version 2
+ * );
+ *
+ * // Generate operations from version 0 to 1 (only creates users table)
+ * const operations = generateMigrationFromSchema(mySchema, 0, 1, {
+ *   provider: "postgresql"
+ * });
+ * ```
+ */
+export function generateMigrationFromSchema(
+  targetSchema: AnySchema,
+  fromVersion: number,
+  toVersion: number,
+  _options: {
+    provider: Provider;
+  },
+): MigrationOperation[] {
+  if (fromVersion < 0) {
+    throw new Error(`fromVersion cannot be negative: ${fromVersion}`);
+  }
+
+  if (fromVersion > targetSchema.version) {
+    throw new Error(
+      `fromVersion (${fromVersion}) exceeds schema version (${targetSchema.version})`,
+    );
+  }
+
+  if (toVersion > targetSchema.version) {
+    throw new Error(`toVersion (${toVersion}) exceeds schema version (${targetSchema.version})`);
+  }
+
+  if (toVersion < fromVersion) {
+    throw new Error(
+      `Cannot migrate backwards: toVersion (${toVersion}) < fromVersion (${fromVersion})`,
+    );
+  }
+
+  // Get operations between fromVersion and toVersion
+  // Operations are 1-indexed (operation 0 is version 0→1)
+  const relevantOperations = targetSchema.operations.slice(fromVersion, toVersion);
+
+  // Convert schema operations to migration operations
+  const migrationOperations: MigrationOperation[] = [];
+
+  for (const op of relevantOperations) {
+    if (op.type === "add-table") {
+      migrationOperations.push({
+        type: "create-table",
+        value: op.table,
+      });
+    } else if (op.type === "add-reference") {
+      const table = targetSchema.tables[op.tableName];
+      if (!table) {
+        throw new Error(`Table ${op.tableName} not found in schema`);
+      }
+
+      // Find the foreign key that matches this reference
+      const foreignKey = table.foreignKeys.find(
+        (fk) => fk.name === `${op.tableName}_${op.config.targetTable}_${op.referenceName}_fk`,
+      );
+
+      if (!foreignKey) {
+        throw new Error(
+          `Foreign key for reference ${op.referenceName} not found in table ${op.tableName}`,
+        );
+      }
+
+      migrationOperations.push({
+        type: "add-foreign-key",
+        table: op.tableName,
+        value: compileForeignKey(foreignKey),
+      });
+    } else if (op.type === "add-index") {
+      migrationOperations.push({
+        type: "add-index",
+        table: op.tableName,
+        name: op.name,
+        columns: op.columns,
+        unique: op.unique,
+      });
+    }
+  }
+
+  return migrationOperations;
+}

package/src/migration-engine/create.test.ts

@@ -0,0 +1,349 @@
+import { describe, expect, it, vi } from "vitest";
+import { createMigrator, type MigrationEngineOptions } from "./create";
+import { schema, idColumn, column, referenceColumn } from "../schema/create";
+import type { MigrationOperation } from "./shared";
+
+describe("createMigrator", () => {
+  const testSchema = schema((s) => {
+    return s
+      .addTable("users", (t) => {
+        return t.addColumn("id", idColumn()).addColumn("name", column("string"));
+      })
+      .addTable("posts", (t) => {
+        return t.addColumn("id", idColumn()).addColumn("title", column("string"));
+      })
+      .addTable("comments", (t) => {
+        return t.addColumn("id", idColumn()).addColumn("text", column("string"));
+      });
+  });
+
+  function createTestMigrator(currentVersion = 0) {
+    const executedOperations: MigrationOperation[][] = [];
+    let version = currentVersion;
+
+    const options: MigrationEngineOptions = {
+      schema: testSchema,
+      userConfig: {
+        provider: "postgresql",
+      },
+      executor: async (operations) => {
+        executedOperations.push(operations);
+      },
+      settings: {
+        getVersion: async () => version,
+        updateSettingsInMigration: async (newVersion) => {
+          version = newVersion;
+          return [
+            {
+              type: "custom",
+              sql: `UPDATE _settings SET version = ${newVersion}`,
+            },
+          ];
+        },
+      },
+    };
+
+    const migrator = createMigrator(options);
+
+    return { migrator, executedOperations, getVersion: () => version };
+  }
+
+  describe("migrate()", () => {
+    it("should migrate from version 0 to latest schema version", async () => {
+      const { migrator, getVersion } = createTestMigrator(0);
+
+      const result = await migrator.migrate();
+
+      expect(result.operations.length).toBeGreaterThan(0);
+      expect(getVersion()).toBe(testSchema.version);
+    });
+
+    it("should migrate from intermediate version to latest", async () => {
+      const { migrator, getVersion } = createTestMigrator(1);
+
+      const result = await migrator.migrate();
+
+      expect(result.operations.length).toBeGreaterThan(0);
+      expect(getVersion()).toBe(testSchema.version);
+    });
+
+    it("should return empty operations when already at latest version", async () => {
+      const { migrator, getVersion } = createTestMigrator(testSchema.version);
+
+      const result = await migrator.migrate();
+
+      expect(result.operations).toEqual([]);
+      expect(getVersion()).toBe(testSchema.version);
+    });
+
+    it("should generate correct operations when jumping multiple versions", async () => {
+      const { migrator } = createTestMigrator(0);
+
+      const result = await migrator.migrate();
+
+      // Should create all 3 tables plus settings update
+      const createTableOps = result.operations.filter((op) => op.type === "create-table");
+      expect(createTableOps).toHaveLength(3);
+    });
+  });
+
+  describe("migrateTo()", () => {
+    it("should migrate forward from version 0 to version 2", async () => {
+      const { migrator, getVersion } = createTestMigrator(0);
+
+      const result = await migrator.migrateTo(2);
+
+      expect(result.operations.length).toBeGreaterThan(0);
+      expect(getVersion()).toBe(2);
+    });
+
+    it("should migrate forward by jumping multiple versions", async () => {
+      const { migrator, getVersion } = createTestMigrator(0);
+
+      const result = await migrator.migrateTo(testSchema.version);
+
+      expect(getVersion()).toBe(testSchema.version);
+      const createTableOps = result.operations.filter((op) => op.type === "create-table");
+      expect(createTableOps).toHaveLength(3);
+    });
+
+    it("should migrate forward one version at a time", async () => {
+      const { migrator, getVersion } = createTestMigrator(0);
+
+      await migrator.migrateTo(1);
+      expect(getVersion()).toBe(1);
+
+      await migrator.migrateTo(2);
+      expect(getVersion()).toBe(2);
+
+      await migrator.migrateTo(3);
+      expect(getVersion()).toBe(3);
+    });
+
+    it("should return empty operations when already at target version", async () => {
+      const { migrator, getVersion } = createTestMigrator(2);
+
+      const result = await migrator.migrateTo(2);
+
+      expect(result.operations).toEqual([]);
+      expect(getVersion()).toBe(2);
+    });
+
+    it("should throw error when trying to migrate backwards", async () => {
+      const { migrator } = createTestMigrator(3);
+
+      await expect(migrator.migrateTo(1)).rejects.toThrow(
+        "Cannot migrate backwards: current version is 3, target is 1. Only forward migrations are supported.",
+      );
+    });
+
+    it("should throw error when migrating to negative version", async () => {
+      const { migrator } = createTestMigrator(0);
+
+      await expect(migrator.migrateTo(-1)).rejects.toThrow(
+        "Cannot migrate to negative version: -1",
+      );
+    });
+
+    it("should throw error when migrating beyond schema version", async () => {
+      const { migrator } = createTestMigrator(0);
+
+      await expect(migrator.migrateTo(999)).rejects.toThrow(
+        `Cannot migrate to version 999: schema only has version ${testSchema.version}`,
+      );
+    });
+  });
+
+  describe("getVersion()", () => {
+    it("should return current version", async () => {
+      const { migrator } = createTestMigrator(0);
+
+      const version = await migrator.getVersion();
+
+      expect(version).toBe(0);
+    });
+
+    it("should return updated version after migration", async () => {
+      const { migrator } = createTestMigrator(0);
+
+      await migrator.migrateTo(2);
+      const version = await migrator.getVersion();
+
+      expect(version).toBe(2);
+    });
+  });
+
+  describe("execute()", () => {
+    it("should execute migration operations", async () => {
+      const { migrator, executedOperations } = createTestMigrator(0);
+
+      const result = await migrator.migrateTo(1);
+      await result.execute();
+
+      expect(executedOperations).toHaveLength(1);
+      expect(executedOperations[0].length).toBeGreaterThan(0);
+    });
+
+    it("should not execute operations until execute() is called", async () => {
+      const { migrator, executedOperations } = createTestMigrator(0);
+
+      await migrator.migrateTo(1);
+
+      expect(executedOperations).toHaveLength(0);
+    });
+  });
+
+  describe("transformers", () => {
+    it("should apply afterAuto transformer", async () => {
+      const executedOperations: MigrationOperation[][] = [];
+      let version = 0;
+
+      const afterAutoSpy = vi.fn((operations) => {
+        return [
+          ...operations,
+          {
+            type: "custom",
+            sql: "-- Added by afterAuto",
+          },
+        ];
+      });
+
+      const options: MigrationEngineOptions = {
+        schema: testSchema,
+        userConfig: {
+          provider: "postgresql",
+        },
+        executor: async (operations) => {
+          executedOperations.push(operations);
+        },
+        settings: {
+          getVersion: async () => version,
+          updateSettingsInMigration: async (newVersion) => {
+            version = newVersion;
+            return [];
+          },
+        },
+        transformers: [
+          {
+            afterAuto: afterAutoSpy,
+          },
+        ],
+      };
+
+      const migrator = createMigrator(options);
+      const result = await migrator.migrateTo(1);
+
+      expect(afterAutoSpy).toHaveBeenCalledOnce();
+      expect(result.operations.some((op) => op.type === "custom")).toBe(true);
+    });
+
+    it("should apply afterAll transformer", async () => {
+      const executedOperations: MigrationOperation[][] = [];
+      let version = 0;
+
+      const afterAllSpy = vi.fn((operations) => {
+        return [
+          ...operations,
+          {
+            type: "custom",
+            sql: "-- Added by afterAll",
+          },
+        ];
+      });
+
+      const options: MigrationEngineOptions = {
+        schema: testSchema,
+        userConfig: {
+          provider: "postgresql",
+        },
+        executor: async (operations) => {
+          executedOperations.push(operations);
+        },
+        settings: {
+          getVersion: async () => version,
+          updateSettingsInMigration: async (newVersion) => {
+            version = newVersion;
+            return [];
+          },
+        },
+        transformers: [
+          {
+            afterAll: afterAllSpy,
+          },
+        ],
+      };
+
+      const migrator = createMigrator(options);
+      const result = await migrator.migrateTo(1);
+
+      expect(afterAllSpy).toHaveBeenCalledOnce();
+      expect(result.operations.some((op) => op.type === "custom")).toBe(true);
+    });
+  });
+
+  describe("updateSettings option", () => {
+    it("should update settings by default", async () => {
+      const { migrator } = createTestMigrator(0);
+
+      const result = await migrator.migrateTo(1);
+
+      const settingsOp = result.operations.find((op) => op.type === "custom");
+      expect(settingsOp).toBeDefined();
+    });
+
+    it("should skip settings update when updateSettings is false", async () => {
+      const { migrator } = createTestMigrator(0);
+
+      const result = await migrator.migrateTo(1, { updateSettings: false });
+
+      // When updateSettings is false, we shouldn't have the settings update operation
+      // Check that we only have create-table operations
+      const nonTableOps = result.operations.filter((op) => op.type !== "create-table");
+      expect(nonTableOps).toHaveLength(0);
+    });
+  });
+
+  describe("with foreign keys", () => {
+    it("should handle schema with foreign keys", async () => {
+      const fkSchema = schema((s) => {
+        return s
+          .addTable("users", (t) => {
+            return t.addColumn("id", idColumn());
+          })
+          .addTable("posts", (t) => {
+            return t.addColumn("id", idColumn()).addColumn("authorId", referenceColumn());
+          })
+          .addReference("posts", "author", {
+            columns: ["authorId"],
+            targetTable: "users",
+            targetColumns: ["id"],
+          });
+      });
+
+      let version = 0;
+      const options: MigrationEngineOptions = {
+        schema: fkSchema,
+        userConfig: {
+          provider: "postgresql",
+        },
+        executor: async () => {},
+        settings: {
+          getVersion: async () => version,
+          updateSettingsInMigration: async (newVersion) => {
+            version = newVersion;
+            return [];
+          },
+        },
+      };
+
+      const migrator = createMigrator(options);
+      const result = await migrator.migrate();
+
+      const createTableOps = result.operations.filter((op) => op.type === "create-table");
+      const fkOps = result.operations.filter((op) => op.type === "add-foreign-key");
+
+      expect(createTableOps).toHaveLength(2);
+      expect(fkOps).toHaveLength(1);
+    });
+  });
+});