@metaobjectsdev/migrate-ts 0.5.0 → 0.6.0

package/src/emit/d1-safety-pass.ts

@@ -0,0 +1,94 @@
+const MAX_STATEMENT_BYTES = 1 * 1024 * 1024; // 1 MB — D1 batch API per-statement limit (path used by `wrangler d1 migrations apply --file`).
+
+export class D1UnsupportedStatementError extends Error {
+  constructor(public readonly statement: string, public readonly reason: string) {
+    super(`D1 does not support: ${reason} — offending statement: ${statement.slice(0, 80)}`);
+    this.name = "D1UnsupportedStatementError";
+  }
+}
+
+interface PassResult {
+  sql: string;
+  warnings: string[];
+}
+
+export function applyD1SafetyPass(sql: string): string;
+export function applyD1SafetyPass(sql: string, opts: { collectWarnings: true }): PassResult;
+export function applyD1SafetyPass(sql: string, opts?: { collectWarnings?: boolean }): string | PassResult {
+  const collect = opts?.collectWarnings === true;
+  const warnings: string[] = [];
+
+  if (sql.length === 0) {
+    return collect ? { sql: "", warnings } : "";
+  }
+
+  const statements = splitStatements(sql);
+  const kept: string[] = [];
+
+  for (const stmt of statements) {
+    const trimmed = stmt.trim();
+    if (trimmed.length === 0) continue;
+
+    // Reject hard failures up front.
+    if (/^\s*(ATTACH|DETACH)\b/i.test(trimmed)) {
+      throw new D1UnsupportedStatementError(trimmed, "ATTACH/DETACH DATABASE");
+    }
+    if (/^\s*VACUUM\b/i.test(trimmed)) {
+      throw new D1UnsupportedStatementError(trimmed, "VACUUM");
+    }
+
+    // Strip explicit transaction control + savepoints.
+    if (/^\s*(BEGIN|COMMIT|ROLLBACK|SAVEPOINT|RELEASE)\b/i.test(trimmed)) {
+      continue;
+    }
+
+    const byteLen = byteLength(trimmed);
+    if (byteLen > MAX_STATEMENT_BYTES) {
+      warnings.push(
+        `statement exceeds D1's 1 MB per-statement limit (${byteLen} bytes); ` +
+        `may be rejected by D1 at apply time: ${trimmed.slice(0, 80)}...`,
+      );
+    }
+
+    kept.push(trimmed);
+  }
+
+  // Re-join: each statement on its own line, blank line between top-level
+  // DDL statements (matches sqlite emit's output style).
+  const out = kept.join("\n\n");
+  return collect ? { sql: out, warnings } : out;
+}
+
+/**
+ * Split SQL on `;` boundaries, respecting single-quoted strings (SQL uses
+ * '' to escape a single quote inside a literal — two consecutive quotes toggle
+ * inString twice, net zero, which is exactly what we want).
+ * Sufficient for our DDL output; we don't generate dollar-quoted blocks or
+ * other exotic SQLite literals.
+ */
+function splitStatements(sql: string): string[] {
+  const out: string[] = [];
+  let buf = "";
+  let inString = false;
+  for (let i = 0; i < sql.length; i++) {
+    const c = sql[i]!;
+    if (c === "'") {
+      buf += c;
+      inString = !inString;
+      continue;
+    }
+    if (c === ";" && !inString) {
+      buf += ";";
+      out.push(buf);
+      buf = "";
+      continue;
+    }
+    buf += c;
+  }
+  if (buf.trim().length > 0) out.push(buf);
+  return out;
+}
+
+function byteLength(s: string): number {
+  return new TextEncoder().encode(s).length;
+}

package/src/emit/d1.ts

@@ -0,0 +1,16 @@
+import type { Change, EmitResult, SchemaSnapshot, SnapshotMeta } from "../types.js";
+import { renderSqlite } from "./sqlite.js";
+import { applyD1SafetyPass } from "./d1-safety-pass.js";
+
+export function renderD1(
+  changes: readonly Change[],
+  expectedSchema?: SchemaSnapshot,
+  actualMeta?: SnapshotMeta,
+): EmitResult {
+  const sqliteResult = renderSqlite(changes, expectedSchema, actualMeta);
+  return {
+    up: applyD1SafetyPass(sqliteResult.up),
+    down: applyD1SafetyPass(sqliteResult.down),
+    recreatedTables: sqliteResult.recreatedTables,
+  };
+}

package/src/emit/index.ts

@@ -2,6 +2,7 @@ import type { Change, EmitResult, Dialect, SchemaSnapshot, SnapshotMeta } from "
 import { BlockedChangesError } from "../errors.js";
 import { renderPostgres } from "./postgres.js";
 import { renderSqlite } from "./sqlite.js";
+import { renderD1 } from "./d1.js";
 
 export interface EmitOptions {
   dialect: Dialect;
@@ -34,5 +35,6 @@ export function emit(changes: Change[], opts: EmitOptions): EmitResult {
   switch (opts.dialect) {
     case "postgres": return renderPostgres(changes);
     case "sqlite":   return renderSqlite(changes, opts.expectedSchema, opts.actualMeta);
+    case "d1":       return renderD1(changes, opts.expectedSchema, opts.actualMeta);
   }
 }

package/src/emit/postgres.ts

@@ -38,7 +38,11 @@ function renderUp(c: Change): string {
     case "create-table":           return renderCreateTable(c.table);
     case "drop-table":             return `DROP TABLE ${quoteQualified(c.table, c.schema)};`;
     case "rename-table":           return `ALTER TABLE ${quoteQualified(c.from, c.schema)} RENAME TO ${quote(c.to)};`;
-    case "add-column":             return `ALTER TABLE ${quoteQualified(c.table, c.schema)} ADD COLUMN ${renderColumn(c.column)};`;
+    case "add-column": {
+      const base = `ALTER TABLE ${quoteQualified(c.table, c.schema)} ADD COLUMN ${renderColumn(c.column)};`;
+      if (!c.column.description) return base;
+      return `${base}\n${columnCommentSql(c.table, c.schema, c.column.name, c.column.description)}`;
+    }
     case "drop-column":            return `ALTER TABLE ${quoteQualified(c.table, c.schema)} DROP COLUMN ${quote(c.column)};`;
     case "rename-column":          return `ALTER TABLE ${quoteQualified(c.table, c.schema)} RENAME COLUMN ${quote(c.from)} TO ${quote(c.to)};`;
     case "change-column-type":     return `ALTER TABLE ${quoteQualified(c.table, c.schema)} ALTER COLUMN ${quote(c.column)} TYPE ${pgType(c.to)};`;
@@ -95,7 +99,35 @@ function renderCreateTable(t: TableDescriptor): string {
   if (t.primaryKey.length > 0) {
     colDefs.push(`  CONSTRAINT ${quote(t.name + "_pkey")} PRIMARY KEY (${t.primaryKey.map(quote).join(", ")})`);
   }
-  return `CREATE TABLE ${quoteQualified(t.name, t.schema)} (\n${colDefs.join(",\n")}\n);`;
+  const create = `CREATE TABLE ${quoteQualified(t.name, t.schema)} (\n${colDefs.join(",\n")}\n);`;
+  const comments = renderTableComments(t);
+  return comments.length === 0 ? create : `${create}\n${comments.join("\n")}`;
+}
+
+function renderTableComments(t: TableDescriptor): string[] {
+  const out: string[] = [];
+  if (t.description) {
+    out.push(`COMMENT ON TABLE ${quoteQualified(t.name, t.schema)} IS '${pgEscape(t.description)}';`);
+  }
+  for (const col of t.columns) {
+    if (col.description) {
+      out.push(columnCommentSql(t.name, t.schema, col.name, col.description));
+    }
+  }
+  return out;
+}
+
+function columnCommentSql(
+  table: string,
+  schema: string | undefined,
+  column: string,
+  description: string,
+): string {
+  return `COMMENT ON COLUMN ${quoteQualified(table, schema)}.${quote(column)} IS '${pgEscape(description)}';`;
+}
+
+function pgEscape(s: string): string {
+  return s.replace(/'/g, "''");
 }
 
 function renderColumn(c: ColumnDescriptor): string {
@@ -132,7 +164,7 @@ function pgType(t: SqlType): string {
 function renderDefault(d: ColumnDefault): string {
   if (d.kind === "expr") return d.value;
   // Literal: quote string-form values.
-  return `'${d.value.replace(/'/g, "''")}'`;
+  return `'${pgEscape(d.value)}'`;
 }
 
 function renderCreateIndex(table: string, schema: string | undefined, ix: IndexDescriptor): string {

package/src/emit/sqlite.ts

@@ -23,7 +23,7 @@ const RECREATE_TRIGGERING_KINDS = new Set<Change["kind"]>([
 ]);
 
 export function renderSqlite(
-  changes: Change[],
+  changes: readonly Change[],
   expectedSchema?: SchemaSnapshot,
   actualMeta?: SnapshotMeta,
 ): EmitResult {

package/src/errors.ts

@@ -1,5 +1,38 @@
 import type { Change, ChangeKind } from "./types.js";
 
+// ---------------------------------------------------------------------------
+// SetNullNotNullableError — surfaced by buildExpectedSchema
+// ---------------------------------------------------------------------------
+
+/**
+ * Thrown when a foreign key's resolved ON DELETE action is "set-null" but one
+ * or more of its FK columns map to a NOT NULL field (@required: true).
+ *
+ * ON DELETE SET NULL requires the FK column(s) to be nullable — Postgres and
+ * SQLite both reject the combination at DDL execution time.
+ *
+ * Fix: either remove @required from the FK field(s), or override the
+ * relationship with @onDelete: "restrict" / "no-action" to avoid set-null.
+ */
+export class SetNullNotNullableError extends Error {
+  override readonly name = "SetNullNotNullableError";
+  readonly entityName: string;
+  readonly constraintName: string;
+  readonly offendingFields: string[];
+
+  constructor(entityName: string, constraintName: string, offendingFields: string[]) {
+    const fieldList = offendingFields.join(", ");
+    super(
+      `Entity "${entityName}": FK constraint "${constraintName}" uses ON DELETE SET NULL ` +
+      `but field(s) [${fieldList}] are NOT NULL (@required: true). ` +
+      `Fix: remove @required from the FK field(s), or override with @onDelete: "restrict" / "no-action" on the relationship.`,
+    );
+    this.entityName = entityName;
+    this.constraintName = constraintName;
+    this.offendingFields = offendingFields;
+  }
+}
+
 const ENABLE_FLAG_BY_KIND: Partial<Record<ChangeKind, string>> = {
   "drop-column": "allow.dropColumn",
   "drop-table": "allow.dropTable",

package/src/expected-schema.ts

@@ -1,14 +1,9 @@
-import type { MetaData, MetaObject, MetaReferenceIdentity, MetaRoot } from "@metaobjectsdev/metadata";
+import type { MetaData, MetaObject, MetaRoot } from "@metaobjectsdev/metadata";
 import {
   TYPE_OBJECT,
-  TYPE_SOURCE,
-  TYPE_VALIDATOR,
-  SOURCE_SUBTYPE_DB_VIEW,
-  VALIDATOR_SUBTYPE_REQUIRED,
-  IDENTITY_ATTR_FIELDS,
+  MetaSource,
   IDENTITY_ATTR_GENERATION,
   IDENTITY_ATTR_UNIQUE,
-  FIELD_ATTR_REQUIRED,
   FIELD_ATTR_DEFAULT,
   FIELD_ATTR_UNIQUE,
   FIELD_SUBTYPE_STRING,
@@ -26,43 +21,63 @@ import {
   FIELD_SUBTYPE_TIMESTAMP,
   FIELD_SUBTYPE_OBJECT,
   FIELD_SUBTYPE_CLASS,
+  FIELD_ATTR_OBJECT_REF,
+  FIELD_ATTR_STORAGE,
+  STORAGE_FLATTENED,
+  DOC_ATTR_DESCRIPTION,
   resolveTableName, resolveColumnName, resolveTableSchema,
 } from "@metaobjectsdev/metadata";
 import type { SqlType } from "./sql-type.js";
 import type {
-  SchemaSnapshot, TableDescriptor, ColumnDescriptor, IndexDescriptor, FkDescriptor,
+  Dialect, SchemaSnapshot, TableDescriptor, ColumnDescriptor, IndexDescriptor, FkDescriptor,
 } from "./types.js";
+import {
+  resolveReferentialActions,
+  validateSetNullNullability,
+  readIdentityFields,
+  findField,
+  isRequired,
+} from "./referential-actions.js";
 
 export interface BuildExpectedSchemaOptions {
   /**
    * If set, normalize column SqlTypes for the target dialect so the diff
-   * matches what introspection will see. For sqlite this collapses
-   * boolean → integer{64} and timestamp/date/time → text, since sqlite
-   * has no native boolean/timestamp affinity and Drizzle's
-   * `integer(..., {mode:"boolean"})` / `text("ts")` patterns produce
-   * INTEGER / TEXT in the actual DB.
+   * matches what introspection will see. For sqlite (and d1, which is SQLite
+   * at the SQL level) this collapses boolean → integer{64} and
+   * timestamp/date/time → text, since sqlite has no native boolean/timestamp
+   * affinity and Drizzle's `integer(..., {mode:"boolean"})` / `text("ts")`
+   * patterns produce INTEGER / TEXT in the actual DB.
    */
-  dialect?: "sqlite" | "postgres";
+  dialect?: Dialect;
 }
 
 export function buildExpectedSchema(
   root: MetaData,
   opts?: BuildExpectedSchemaOptions,
 ): SchemaSnapshot {
+  // D1 is SQLite at the SQL level; normalize it so downstream dialect checks
+  // don't need to handle "d1" separately.
+  const dialect = opts?.dialect === "d1" ? "sqlite" : opts?.dialect;
+
   // Pass 1: collect entities + their resolved table names.
   // Skip:
   //   - abstract objects (e.g., BaseEntity)
   //   - value objects (no table backing)
-  //   - projections (source.dbView — handled by the view-diff pipeline, not table diff)
+  //   - projections (read-only @kind source with no writable peer — handled by
+  //     the view-diff pipeline, not the table diff)
   const entities: { entity: MetaObject; tableName: string }[] = [];
   for (const child of root.ownChildren()) {
     if (child.type !== TYPE_OBJECT) continue;
     if (child.isAbstract) continue;
     if (child.subType === "value") continue;
-    const hasViewSource = child.ownChildren().some(
-      (c) => c.type === TYPE_SOURCE && c.subType === SOURCE_SUBTYPE_DB_VIEW,
+    const hasReadOnlySource = child.ownChildren().some(
+      (c) => c instanceof MetaSource && c.isReadOnly(),
     );
-    if (hasViewSource) continue;
+    const hasWritableSource = child.ownChildren().some(
+      (c) => c instanceof MetaSource && c.isWritable(),
+    );
+    // Projection: read-only and not write-through.
+    if (hasReadOnlySource && !hasWritableSource) continue;
     entities.push({ entity: child as MetaObject, tableName: resolveTableName(child) });
   }
   const entityToTable = new Map(entities.map((e) => [e.entity.name, e.tableName]));
@@ -79,7 +94,7 @@ export function buildExpectedSchema(
   });
 
   // Pass 3: dialect-specific SqlType normalization.
-  if (opts?.dialect === "sqlite") {
+  if (dialect === "sqlite") {
     for (const table of tables) {
       for (const col of table.columns) {
         col.sqlType = normalizeForSqlite(col.sqlType);
@@ -88,7 +103,7 @@ export function buildExpectedSchema(
   }
 
   // Dialect validation: SQLite has no schema concept; reject any non-default @schema.
-  if (opts?.dialect === "sqlite") {
+  if (dialect === "sqlite") {
     for (const table of tables) {
       if (table.schema !== undefined) {
         throw new Error(
@@ -146,16 +161,39 @@ function buildTable(
   const columns: ColumnDescriptor[] = [];
   for (const field of entity.fields()) {
     const isPk = pkJsNames.includes(field.name);
-    columns.push(buildColumn(field, isPk, isPk ? pkGeneration : undefined));
+    if (
+      field.subType === FIELD_SUBTYPE_OBJECT &&
+      field.ownAttr(FIELD_ATTR_STORAGE) === STORAGE_FLATTENED
+    ) {
+      // Flattened storage: expand nested value-object fields as prefixed columns.
+      // The parent field.object itself does NOT produce its own column.
+      columns.push(...flattenObjectField(field, root));
+    } else {
+      columns.push(buildColumn(field, isPk, isPk ? pkGeneration : undefined));
+    }
   }
 
-  return {
+  const descriptor: TableDescriptor = {
     name: tableName,
     columns,
     indexes: buildSecondaryIndexes(entity, tableName),
     foreignKeys: buildForeignKeys(entity, tableName, resolveTargetTable, root),
     primaryKey,
   };
+  const entityDesc = readDescription(entity);
+  if (entityDesc !== undefined) descriptor.description = entityDesc;
+  return descriptor;
+}
+
+/**
+ * Read effective `description` attr from a node. Returns the string if present
+ * and non-empty, undefined otherwise. Uses `.attr` (effective, not own) so a
+ * node that extends an abstract base picks up the base's description — required
+ * for both entity- and field-level COMMENT ON parity with the entity-attr contract.
+ */
+function readDescription(node: { attr: (n: string) => unknown }): string | undefined {
+  const v = node.attr(DOC_ATTR_DESCRIPTION);
+  return typeof v === "string" && v.length > 0 ? v : undefined;
 }
 
 function buildSecondaryIndexes(entity: MetaObject, tableName: string): IndexDescriptor[] {
@@ -226,16 +264,47 @@ function buildForeignKeys(
       ? explicitTargetFields.map(toSnake)
       : [toSnake(refChild.resolvedTargetPkField(root) ?? "id")];
 
-    fks.push({
-      name: `${tableName}_${fkCols[0]}_fk`,
+    const { onDelete, onUpdate } = resolveReferentialActions(entity, refChild);
+    const constraintName = `${tableName}_${fkCols[0]}_fk`;
+
+    // Guard: ON DELETE SET NULL requires nullable FK columns.
+    validateSetNullNullability(entity, refChild, onDelete, constraintName);
+
+    const fk: FkDescriptor = {
+      name: constraintName,
       columns: fkCols,
       refTable,
       refColumns,
-    });
+    };
+    if (onDelete !== undefined) fk.onDelete = onDelete;
+    if (onUpdate !== undefined) fk.onUpdate = onUpdate;
+    fks.push(fk);
   }
   return fks;
 }
 
+/**
+ * Expand a `field.object @storage "flattened"` into one ColumnDescriptor per
+ * nested field of the referenced value-object, prefixed by the parent field's
+ * resolved column name + underscore.
+ *
+ * EF OwnsOne pattern: no JSON column for the parent itself; each nested field
+ * becomes `<parent_col>_<nested_col>` in the owning entity's table.
+ */
+function flattenObjectField(field: MetaData, root: MetaRoot): ColumnDescriptor[] {
+  const ref = field.ownAttr(FIELD_ATTR_OBJECT_REF);
+  if (typeof ref !== "string" || ref.length === 0) return [];
+  const targetObject = root.findObject(ref);
+  if (targetObject === undefined) return [];
+  const prefix = resolveColumnName(field) + "_";
+  const cols: ColumnDescriptor[] = [];
+  for (const nested of targetObject.fields()) {
+    const inner = buildColumn(nested, /* isPk */ false, /* pkGeneration */ undefined);
+    cols.push({ ...inner, name: prefix + inner.name });
+  }
+  return cols;
+}
+
 const EXPR_DEFAULT_PATTERNS = [
   /^current_timestamp$/i,
   /^now\(\)$/i,
@@ -249,19 +318,14 @@ function buildColumn(
   isPk: boolean,
   pkGeneration: string | undefined,
 ): ColumnDescriptor {
-  const requiredAttr = field.ownAttr(FIELD_ATTR_REQUIRED);
-  // BaseEntity-style metadata expresses required via a validator.required child;
-  // direct attr form is the alternative. Either signals NOT NULL.
-  const hasRequiredValidator = field.ownChildren().some(
-    (c) => c.type === TYPE_VALIDATOR && c.subType === VALIDATOR_SUBTYPE_REQUIRED,
-  );
-  const isRequired = requiredAttr === true || requiredAttr === "true" || hasRequiredValidator;
+  // Both the @required attr and the validator.required child signal NOT NULL.
+  const fieldIsRequired = isRequired(field);
   const defaultRaw = field.ownAttr(FIELD_ATTR_DEFAULT);
 
   const col: ColumnDescriptor = {
     name: resolveColumnName(field),
     sqlType: subtypeToSqlType(field.subType),
-    nullable: !isPk && !isRequired,
+    nullable: !isPk && !fieldIsRequired,
   };
 
   if (typeof defaultRaw === "string" && defaultRaw.length > 0) {
@@ -275,6 +339,9 @@ function buildColumn(
     col.identity = pkGeneration;
   }
 
+  const fieldDesc = readDescription(field);
+  if (fieldDesc !== undefined) col.description = fieldDesc;
+
   return col;
 }
 
@@ -299,25 +366,6 @@ function subtypeToSqlType(subType: string): SqlType {
   }
 }
 
-function readIdentityFields(identity: MetaData): string[] {
-  const raw = identity.ownAttr(IDENTITY_ATTR_FIELDS);
-  if (Array.isArray(raw)) {
-    return raw.map(String).filter((s) => s.length > 0);
-  }
-  if (typeof raw === "string") {
-    // Fallback: comma-separated string form (defensive; canonical form is array)
-    return raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
-  }
-  return [];
-}
-
-function findField(entity: MetaObject, name: string): MetaData | undefined {
-  for (const field of entity.fields()) {
-    if (field.name === name) return field;
-  }
-  return undefined;
-}
-
 function toSnake(s: string): string {
   return s
     .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")

package/src/index.ts

@@ -13,9 +13,10 @@ export { introspect, introspectPostgres, introspectSqlite } from "./introspect/i
 export { diff } from "./diff/index.js";
 export { emit } from "./emit/index.js";
 export { writeMigration } from "./write-migration.js";
+export { writeMigrationD1 } from "./write-migration-d1.js";
 
 // Errors
-export { BlockedChangesError } from "./errors.js";
+export { BlockedChangesError, SetNullNotNullableError } from "./errors.js";
 
 // SqlType helpers (rarely needed but useful for advanced consumers)
 export { isWidening, sqlTypeEquals } from "./sql-type.js";
@@ -33,6 +34,7 @@ export type {
 export type { DiffArgs } from "./diff/index.js";
 export type { EmitOptions } from "./emit/index.js";
 export type { WriteMigrationOptions, WriteMigrationResult } from "./write-migration.js";
+export type { WriteMigrationD1Options, WriteMigrationD1Result } from "./write-migration-d1.js";
 
 // View diff + dialect emitters
 export { classifyViewDiff } from "./view-diff.js";
@@ -40,6 +42,13 @@ export type { ViewShape, ViewDiffClass, ViewMigrationOpts } from "./view-diff.js
 export { emitPostgresViewMigration } from "./view-ddl-postgres.js";
 export { emitSqliteViewMigration } from "./view-ddl-sqlite.js";
 
+// D1 dialect emitter + safety pass.
+// renderD1 is exported directly (unlike renderSqlite/renderPostgres) so
+// consumers writing raw wrangler batch scripts can apply the safety pass
+// independently without going through emit().
+export { renderD1 } from "./emit/d1.js";
+export { applyD1SafetyPass, D1UnsupportedStatementError } from "./emit/d1-safety-pass.js";
+
 // View migrations orchestrator
 export {
   computeViewMigrations,
@@ -47,3 +56,15 @@ export {
   type ViewMigrationsOpts,
   type ViewMigrationsResult,
 } from "./source-aware-diff.js";
+
+// D1 introspection
+export { introspectD1, type D1Runner, type IntrospectD1Options } from "./introspect/d1.js";
+
+// Wrangler config helpers
+export {
+  findWranglerConfig,
+  parseWranglerConfig,
+  resolveD1Binding,
+  type D1Binding,
+  type WranglerConfig,
+} from "./wrangler-config.js";