@vibeorm/migrate 1.0.0

package/README.md

@@ -0,0 +1,95 @@
+# @vibeorm/migrate
+
+Migration, introspection, and schema diff toolkit for VibeORM. Handles DDL generation, database introspection, schema comparison, migration tracking, and `.prisma` schema printing.
+
+## Installation
+
+```bash
+bun add @vibeorm/migrate
+```
+
+## Features
+
+- **DDL generation** — schema IR to PostgreSQL DDL (enums, tables, constraints, indexes, foreign keys, M:N join tables)
+- **Introspection** — reverse-engineer a live PostgreSQL database into schema IR
+- **Schema diffing** — compute migration operations between two schema versions
+- **Migration runner** — track and apply migrations via a `_vibeorm_migrations` table
+- **Snapshot management** — serialize/deserialize schema IR as JSON for diffing
+- **Schema printing** — convert schema IR back to `.prisma` format
+
+## API
+
+### DDL
+
+```ts
+import { buildDDL } from "@vibeorm/migrate";
+
+const { sql, statements } = buildDDL({ schema });
+// sql: full DDL wrapped in BEGIN/COMMIT
+// statements: individual DDL statements
+```
+
+### Introspection
+
+```ts
+import { introspect } from "@vibeorm/migrate";
+
+const schema = await introspect({ executor });
+// Returns a Schema IR from a live database
+```
+
+### Schema Diffing
+
+```ts
+import { diffSchemas } from "@vibeorm/migrate";
+
+const operations = diffSchemas({ previous: oldSchema, current: newSchema });
+// Returns DiffOperation[] with isDestructive flags
+```
+
+### Migration Runner
+
+```ts
+import {
+  ensureMigrationTable,
+  getAppliedMigrations,
+  applyMigration,
+  removeMigrationRecord,
+  markMigrationApplied,
+} from "@vibeorm/migrate";
+
+await ensureMigrationTable({ executor });
+const applied = await getAppliedMigrations({ executor });
+await applyMigration({ executor, migrationName: "20260101_init", sql, checksum });
+```
+
+### Snapshots
+
+```ts
+import {
+  saveSnapshot,
+  loadLatestSnapshot,
+  loadSnapshot,
+  saveJournal,
+  loadJournal,
+  generateTimestamp,
+  computeChecksum,
+} from "@vibeorm/migrate";
+```
+
+### Schema Printing
+
+```ts
+import { printSchema } from "@vibeorm/migrate";
+
+const prismaText = printSchema({ schema });
+// Returns .prisma formatted schema text
+```
+
+### Diff Operation Types
+
+18 operation types: `createEnum`, `addEnumValue`, `removeEnumValue`, `dropEnum`, `createTable`, `dropTable`, `addColumn`, `dropColumn`, `alterColumnType`, `alterColumnNullability`, `alterColumnDefault`, `addUnique`, `dropUnique`, `addIndex`, `dropIndex`, `addForeignKey`, `dropForeignKey`, `createJoinTable`, `dropJoinTable`.
+
+## License
+
+[MIT](../../LICENSE)

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@vibeorm/migrate",
+  "version": "1.0.0",
+  "description": "Migration, introspection, and schema diff toolkit for VibeORM",
+  "license": "MIT",
+  "keywords": [
+    "orm",
+    "migrations",
+    "postgresql",
+    "bun",
+    "typescript",
+    "introspection"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "default": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vibeorm/vibeorm.git",
+    "directory": "packages/migrate"
+  },
+  "homepage": "https://github.com/vibeorm/vibeorm/tree/master/packages/migrate",
+  "bugs": {
+    "url": "https://github.com/vibeorm/vibeorm/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "dependencies": {
+    "@vibeorm/parser": "workspace:*"
+  }
+}

package/src/ddl-builder.ts

@@ -0,0 +1,442 @@
+/**
+ * DDL Builder — Schema IR → DDL SQL
+ *
+ * Takes a parsed Schema IR and produces the complete set of DDL statements
+ * to create the database from scratch (enums, tables, constraints, indexes, FKs).
+ */
+
+import type { Schema, Model, Field, ScalarField, EnumField, RelationField, DefaultValue, Enum, EnumValue } from "@vibeorm/parser";
+import { PRISMA_TO_PG } from "@vibeorm/parser";
+
+export type DDLResult = {
+  /** The full DDL SQL wrapped in BEGIN/COMMIT */
+  sql: string;
+  /** Individual DDL statements (without BEGIN/COMMIT wrapper) */
+  statements: string[];
+};
+
+// ─── Helpers ──────────────────────────────────────────────────────
+
+function q(params: { name: string }): string {
+  return `"${params.name}"`;
+}
+
+function getDbName(params: { model: Model }): string {
+  return params.model.dbName;
+}
+
+function getFieldDbName(params: { field: ScalarField | EnumField }): string {
+  return params.field.dbName;
+}
+
+function resolveColumnType(params: { field: ScalarField }): string {
+  const { field } = params;
+
+  // Autoincrement uses SERIAL
+  if (field.default?.kind === "autoincrement") {
+    return field.prismaType === "BigInt" ? "BIGSERIAL" : "SERIAL";
+  }
+
+  // Native type override (e.g., @db.VarChar(255))
+  if (field.nativeType) {
+    return field.nativeType;
+  }
+
+  // List fields use PostgreSQL arrays
+  if (field.isList) {
+    return `${PRISMA_TO_PG[field.prismaType]}[]`;
+  }
+
+  return PRISMA_TO_PG[field.prismaType];
+}
+
+/** Resolve to the base column type (no SERIAL — used for FK reference columns) */
+function resolveBaseColumnType(params: { field: ScalarField }): string {
+  const { field } = params;
+  if (field.nativeType) return field.nativeType;
+  if (field.isList) return `${PRISMA_TO_PG[field.prismaType]}[]`;
+  return PRISMA_TO_PG[field.prismaType];
+}
+
+function resolveDefault(params: { field: ScalarField | EnumField }): string | undefined {
+  const { field } = params;
+  const def = field.default;
+  if (!def) return undefined;
+
+  switch (def.kind) {
+    case "autoincrement":
+      // Handled by SERIAL type, no explicit DEFAULT needed
+      return undefined;
+    case "now":
+      return "CURRENT_TIMESTAMP";
+    case "uuid":
+      return "gen_random_uuid()::TEXT";
+    case "cuid":
+      // No native PG equivalent, handled at application level
+      return undefined;
+    case "nanoid":
+      // No native PG equivalent, handled at application level
+      return undefined;
+    case "ulid":
+      // No native PG equivalent, handled at application level
+      return undefined;
+    case "dbgenerated":
+      return def.value;
+    case "literal": {
+      const val = def.value;
+      if (typeof val === "string") return `'${val.replace(/'/g, "''")}'`;
+      if (typeof val === "boolean") return val ? "true" : "false";
+      return String(val);
+    }
+    default:
+      return undefined;
+  }
+}
+
+// ─── Enum DDL ─────────────────────────────────────────────────────
+
+function buildEnumStatements(params: { enums: Enum[] }): string[] {
+  const statements: string[] = [];
+
+  for (const enumDef of params.enums) {
+    const typeName = enumDef.dbName ?? enumDef.name;
+    const values = enumDef.values
+      .map((v) => `'${(v.dbName ?? v.name).replace(/'/g, "''")}'`)
+      .join(", ");
+
+    // Use DO block for safe creation (no IF NOT EXISTS for CREATE TYPE)
+    statements.push(
+      `DO $$ BEGIN\n` +
+      `  CREATE TYPE ${q({ name: typeName })} AS ENUM (${values});\n` +
+      `EXCEPTION WHEN duplicate_object THEN NULL;\n` +
+      `END $$;`
+    );
+  }
+
+  return statements;
+}
+
+// ─── Table DDL ────────────────────────────────────────────────────
+
+function buildTableStatement(params: { model: Model; enums: Enum[] }): string {
+  const { model, enums } = params;
+  const tableName = getDbName({ model });
+  const columns: string[] = [];
+  const enumNames = new Set(enums.map((e) => e.name));
+
+  // Collect scalar + enum fields (not relations)
+  for (const field of model.fields) {
+    if (field.kind === "relation") continue;
+
+    const colName = getFieldDbName({ field });
+    let colType: string;
+
+    if (field.kind === "enum") {
+      const enumDef = enums.find((e) => e.name === field.enumName);
+      const enumDbName = enumDef?.dbName ?? field.enumName;
+      colType = q({ name: enumDbName });
+      if (field.isList) colType += "[]";
+    } else {
+      colType = resolveColumnType({ field });
+    }
+
+    let colDef = `  ${q({ name: colName })} ${colType}`;
+
+    // NOT NULL (unless optional or autoincrement serial which is implicitly NOT NULL)
+    if (field.kind === "scalar" && field.isRequired && field.default?.kind !== "autoincrement") {
+      colDef += " NOT NULL";
+    } else if (field.kind === "enum" && field.isRequired) {
+      colDef += " NOT NULL";
+    }
+
+    // DEFAULT
+    const defaultExpr = resolveDefault({ field });
+    if (defaultExpr) {
+      colDef += ` DEFAULT ${defaultExpr}`;
+    }
+
+    // Inline UNIQUE for single-field unique
+    if (field.isUnique) {
+      colDef += " UNIQUE";
+    }
+
+    columns.push(colDef);
+  }
+
+  // Primary key constraint
+  const pkFields = model.primaryKey.fields
+    .map((f) => {
+      const field = model.fields.find((fld) => fld.name === f);
+      if (field && field.kind !== "relation") {
+        return q({ name: getFieldDbName({ field }) });
+      }
+      return q({ name: f });
+    })
+    .join(", ");
+
+  const pkName = `${tableName}_pkey`;
+  columns.push(`  CONSTRAINT ${q({ name: pkName })} PRIMARY KEY (${pkFields})`);
+
+  return `CREATE TABLE ${q({ name: tableName })} (\n${columns.join(",\n")}\n);`;
+}
+
+// ─── Unique Index DDL ─────────────────────────────────────────────
+
+function buildUniqueIndexStatements(params: { model: Model }): string[] {
+  const { model } = params;
+  const statements: string[] = [];
+  const tableName = getDbName({ model });
+
+  for (const unique of model.uniqueConstraints) {
+    // Skip single-field uniques (handled inline on column)
+    if (unique.fields.length === 1) continue;
+
+    const cols = unique.fields
+      .map((f) => {
+        const field = model.fields.find((fld) => fld.name === f);
+        if (field && field.kind !== "relation") {
+          return q({ name: getFieldDbName({ field }) });
+        }
+        return q({ name: f });
+      })
+      .join(", ");
+
+    const idxName = unique.name ?? `${tableName}_${unique.fields.join("_")}_key`;
+    statements.push(
+      `CREATE UNIQUE INDEX ${q({ name: idxName })} ON ${q({ name: tableName })} (${cols});`
+    );
+  }
+
+  return statements;
+}
+
+// ─── Regular Index DDL ────────────────────────────────────────────
+
+function buildIndexStatements(params: { model: Model }): string[] {
+  const { model } = params;
+  const statements: string[] = [];
+  const tableName = getDbName({ model });
+
+  for (const idx of model.indexes) {
+    const cols = idx.fields
+      .map((f) => {
+        const field = model.fields.find((fld) => fld.name === f);
+        if (field && field.kind !== "relation") {
+          return q({ name: getFieldDbName({ field }) });
+        }
+        return q({ name: f });
+      })
+      .join(", ");
+
+    const idxName = idx.name ?? `${tableName}_${idx.fields.join("_")}_idx`;
+    statements.push(
+      `CREATE INDEX ${q({ name: idxName })} ON ${q({ name: tableName })} (${cols});`
+    );
+  }
+
+  return statements;
+}
+
+// ─── Foreign Key DDL ──────────────────────────────────────────────
+
+function buildForeignKeyStatements(params: { model: Model; allModels: Model[] }): string[] {
+  const { model, allModels } = params;
+  const statements: string[] = [];
+  const tableName = getDbName({ model });
+
+  for (const field of model.fields) {
+    if (field.kind !== "relation") continue;
+    if (!field.relation.isForeignKey) continue;
+    if (field.relation.fields.length === 0) continue;
+
+    const relatedModel = allModels.find((m) => m.name === field.relatedModel);
+    if (!relatedModel) continue;
+
+    const relatedTableName = getDbName({ model: relatedModel });
+
+    const fkCols = field.relation.fields
+      .map((f) => {
+        const fld = model.fields.find((mf) => mf.name === f);
+        if (fld && fld.kind !== "relation") return q({ name: getFieldDbName({ field: fld }) });
+        return q({ name: f });
+      })
+      .join(", ");
+
+    const refCols = field.relation.references
+      .map((f) => {
+        const fld = relatedModel.fields.find((mf) => mf.name === f);
+        if (fld && fld.kind !== "relation") return q({ name: getFieldDbName({ field: fld }) });
+        return q({ name: f });
+      })
+      .join(", ");
+
+    const constraintName = `${tableName}_${field.relation.fields.join("_")}_fkey`;
+    statements.push(
+      `ALTER TABLE ${q({ name: tableName })} ADD CONSTRAINT ${q({ name: constraintName })} ` +
+      `FOREIGN KEY (${fkCols}) REFERENCES ${q({ name: relatedTableName })} (${refCols}) ` +
+      `ON DELETE RESTRICT ON UPDATE CASCADE;`
+    );
+  }
+
+  return statements;
+}
+
+// ─── Implicit M:N Join Table ──────────────────────────────────────
+
+type ImplicitManyToMany = {
+  modelA: string;
+  modelB: string;
+  tableA: string;
+  tableB: string;
+  pkFieldA: string;
+  pkFieldB: string;
+  pkTypeA: string;
+  pkTypeB: string;
+};
+
+function detectImplicitManyToMany(params: { schema: Schema }): ImplicitManyToMany[] {
+  const { schema } = params;
+  const result: ImplicitManyToMany[] = [];
+  const seen = new Set<string>();
+
+  for (const model of schema.models) {
+    for (const field of model.fields) {
+      if (field.kind !== "relation") continue;
+      if (!field.isList) continue;
+      if (field.relation.isForeignKey) continue;
+      if (field.relation.fields.length > 0) continue;
+
+      // Check if the other side is also a list with no FK fields
+      const relatedModel = schema.models.find((m) => m.name === field.relatedModel);
+      if (!relatedModel) continue;
+
+      const backRef = relatedModel.fields.find(
+        (f) =>
+          f.kind === "relation" &&
+          f.relatedModel === model.name &&
+          f.isList &&
+          !f.relation.isForeignKey &&
+          f.relation.fields.length === 0
+      );
+      if (!backRef) continue;
+
+      // Sort alphabetically for consistent naming
+      const sorted = [model.name, relatedModel.name].sort();
+      const nameA = sorted[0]!;
+      const nameB = sorted[1]!;
+      const key = `${nameA}_${nameB}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+
+      const modelADef = schema.models.find((m) => m.name === nameA)!;
+      const modelBDef = schema.models.find((m) => m.name === nameB)!;
+
+      const pkFieldA = modelADef.primaryKey.fields[0]!;
+      const pkFieldB = modelBDef.primaryKey.fields[0]!;
+
+      const pkFieldDefA = modelADef.fields.find((f) => f.name === pkFieldA);
+      const pkFieldDefB = modelBDef.fields.find((f) => f.name === pkFieldB);
+
+      const pkTypeA = pkFieldDefA && pkFieldDefA.kind === "scalar"
+        ? resolveBaseColumnType({ field: pkFieldDefA })
+        : "INTEGER";
+      const pkTypeB = pkFieldDefB && pkFieldDefB.kind === "scalar"
+        ? resolveBaseColumnType({ field: pkFieldDefB })
+        : "INTEGER";
+
+      result.push({
+        modelA: nameA,
+        modelB: nameB,
+        tableA: getDbName({ model: modelADef }),
+        tableB: getDbName({ model: modelBDef }),
+        pkFieldA,
+        pkFieldB,
+        pkTypeA,
+        pkTypeB,
+      });
+    }
+  }
+
+  return result;
+}
+
+function buildJoinTableStatements(params: { joinTable: ImplicitManyToMany }): string[] {
+  const { joinTable } = params;
+  const tableName = `_${joinTable.modelA}To${joinTable.modelB}`;
+  const statements: string[] = [];
+
+  // Create join table
+  statements.push(
+    `CREATE TABLE ${q({ name: tableName })} (\n` +
+    `  "A" ${joinTable.pkTypeA} NOT NULL,\n` +
+    `  "B" ${joinTable.pkTypeB} NOT NULL\n` +
+    `);`
+  );
+
+  // Composite unique index on (A, B)
+  statements.push(
+    `CREATE UNIQUE INDEX ${q({ name: `${tableName}_AB_unique` })} ON ${q({ name: tableName })} ("A", "B");`
+  );
+
+  // Index on B for reverse lookups
+  statements.push(
+    `CREATE INDEX ${q({ name: `${tableName}_B_index` })} ON ${q({ name: tableName })} ("B");`
+  );
+
+  // Foreign key A → modelA
+  statements.push(
+    `ALTER TABLE ${q({ name: tableName })} ADD CONSTRAINT ${q({ name: `${tableName}_A_fkey` })} ` +
+    `FOREIGN KEY ("A") REFERENCES ${q({ name: joinTable.tableA })} ("${joinTable.pkFieldA}") ` +
+    `ON DELETE CASCADE ON UPDATE CASCADE;`
+  );
+
+  // Foreign key B → modelB
+  statements.push(
+    `ALTER TABLE ${q({ name: tableName })} ADD CONSTRAINT ${q({ name: `${tableName}_B_fkey` })} ` +
+    `FOREIGN KEY ("B") REFERENCES ${q({ name: joinTable.tableB })} ("${joinTable.pkFieldB}") ` +
+    `ON DELETE CASCADE ON UPDATE CASCADE;`
+  );
+
+  return statements;
+}
+
+// ─── Main Entry Point ─────────────────────────────────────────────
+
+export function buildDDL(params: { schema: Schema }): DDLResult {
+  const { schema } = params;
+  const statements: string[] = [];
+
+  // 1. Enums
+  statements.push(...buildEnumStatements({ enums: schema.enums }));
+
+  // 2. Tables
+  for (const model of schema.models) {
+    statements.push(buildTableStatement({ model, enums: schema.enums }));
+  }
+
+  // 3. Unique indexes (multi-column only; single-column handled inline)
+  for (const model of schema.models) {
+    statements.push(...buildUniqueIndexStatements({ model }));
+  }
+
+  // 4. Regular indexes
+  for (const model of schema.models) {
+    statements.push(...buildIndexStatements({ model }));
+  }
+
+  // 5. Foreign keys (after all tables exist)
+  for (const model of schema.models) {
+    statements.push(...buildForeignKeyStatements({ model, allModels: schema.models }));
+  }
+
+  // 6. Implicit M:N join tables
+  const joinTables = detectImplicitManyToMany({ schema });
+  for (const jt of joinTables) {
+    statements.push(...buildJoinTableStatements({ joinTable: jt }));
+  }
+
+  // Wrap in transaction
+  const sql = `BEGIN;\n\n${statements.join("\n\n")}\n\nCOMMIT;`;
+
+  return { sql, statements };
+}

package/src/index.ts

@@ -0,0 +1,40 @@
+/**
+ * @vibeorm/migrate
+ *
+ * Core migration modules: DDL generation, database introspection,
+ * schema diffing, snapshot management, migration execution, and schema printing.
+ */
+
+export { buildDDL } from "./ddl-builder.ts";
+export type { DDLResult } from "./ddl-builder.ts";
+
+export { introspect } from "./introspector.ts";
+
+export { diffSchemas } from "./schema-differ.ts";
+export type { DiffOperation, DiffOperationType } from "./schema-differ.ts";
+
+export {
+  saveSnapshot,
+  loadLatestSnapshot,
+  loadSnapshot,
+  saveJournal,
+  loadJournal,
+  generateTimestamp,
+  computeChecksum,
+} from "./snapshot.ts";
+export type { JournalEntry, Journal } from "./snapshot.ts";
+
+export {
+  ensureMigrationTable,
+  getAppliedMigrations,
+  applyMigration,
+  removeMigrationRecord,
+  markMigrationApplied,
+} from "./migration-runner.ts";
+export type { AppliedMigration } from "./migration-runner.ts";
+
+export { printSchema } from "./schema-printer.ts";
+
+export { splitSqlStatements } from "./sql-utils.ts";
+
+export type { SqlExecutor } from "./types.ts";