@zerotal/orm 1.0.3 → 1.1.0

package/CHANGELOG.md

@@ -8,6 +8,30 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.1.0] — 2026-08-08
+
+### Fixed
+
+- **A `json` column returns the type it was given.** Writing skipped `JSON.stringify` for values that were already strings, so a string went into the column as bare characters — `62812345678`, not `"62812345678"` — and the read side's `JSON.parse` turned it back into a number. A `json`-cast setting holding an account number came back as a number, and only for *some* values, since a string that fails to parse fell through unchanged. Encoding is now symmetric in both directions, and `where()` against a `json` column encodes the same way, so a query finds what a write stores. **Upgrade note:** rows written by an older version hold bare scalars, so a string column may still read back as a number, and a `where()` on a string will not match those older rows — they are stored unquoted. Only affects bare scalars in `json`/`array` columns; objects and arrays were always encoded and are untouched.
+- **`bun zt make:model` generates a file that parses.** The stub emitted `@table('posts').withTimestamps()`, which is not valid decorator syntax — the grammar allows a call at the end of the chain, not in the middle — so every generated model failed with `Expected "class" but found "."`. The stub now emits plain `@table('posts')`; timestamps are on by default and the chained form needs outer parentheses, `@(table("x").withoutTimestamps())`. The same broken form is corrected in the `BaseModel` docblocks, and every generated stub is now parsed by a test rather than checked for substrings.
+- **A column `default` is applied on insert.** A declared field that was never assigned was written as an explicit `NULL`, so the INSERT named the column, the database never applied its own default, and a `NOT NULL` column failed outright — on a model and migration that both declared `default: 0`. `undefined` now means "I didn't say": the declared default is used, or the column is omitted so the database decides. An explicit `null` still stores `NULL`.
+- **A `Date` compared against a timestamp column matches again.** Bound values are serialised through the column's cast metadata, but the framework-managed `created_at` / `updated_at` / `deleted_at` carry no `@column` registration — so a `Date` was bound raw and matched nothing. `where("created_at", ">=", monthStart)` is the commonest reporting query there is, and it silently returned zero rows: a dashboard reading "0 this month" looks like a quiet month, not a broken query.
+
+### Added
+
+- `Schema.alter(...)` as an alias of `Schema.table(...)`, and `table.datetime(...)` as an alias of `table.dateTime(...)`. Both are the names other frameworks use, neither was a type error because the blueprint callback is loosely typed, and both therefore failed as a `TypeError` mid-migration — after earlier statements had already run, leaving the schema half-changed.
+- `@column("string", { nullable: true })` — a two-argument form. The shorthand keeps its type and cast; the options cannot contradict them.
+- `@column({ unique: true })` and `@column({ index: true })`, carried through to both `migrate:generate` and `synchronize`. Uniqueness is usually a correctness property, and it was not expressible at all.
+- Generated migrations index any `*_id` column. The reference cannot always be inferred, but the index can, and an unindexed foreign key is a table scan on every join.
+- `"text"` is its own storage type rather than an alias for `"string"`, so a real `TEXT` column is expressible — the distinction matters on Postgres and MySQL.
+
+### Changed
+
+- **`create()` narrows its payload to the mass-assignable columns** when a model declares `fillable` as a literal tuple (`as const`). A required column deliberately kept out of `fillable` was demanded by `InsertPayload` and refused by `fill()` at runtime: the type required exactly what the runtime forbade, and there was no spelling of `create()` that satisfied both. Models without a literal list are unaffected.
+- `static fillable` / `static guarded` accept `readonly string[]`.
+- A migration that fails with "already exists" now says that `database.synchronize` is the usual cause, since the raw driver error names nothing actionable.
+- `make:model` generates `fillable` as a literal tuple and documents that a nullable column is declared `?: T | undefined` — under the scaffold's `exactOptionalPropertyTypes`, `?: T` cannot be assigned `undefined`, so the field could never be cleared.
+
 ## [1.0.3] — 2026-08-07
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/orm",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -30,8 +30,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.0.3",
-    "@zerotal/validator": "1.0.3"
+    "@zerotal/core": "1.1.0",
+    "@zerotal/validator": "1.1.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0"

package/src/commands/MakeModelCommand.ts

@@ -7,13 +7,23 @@ import { createMigrationFile } from "./MakeMigrationCommand.ts";
 export function modelStub(name: string, tableName: string): string {
   return `import { BaseModel, column, table } from '@zerotal/orm';
 
-@table('${tableName}').withTimestamps()
+@table('${tableName}')
 export class ${name} extends BaseModel {
   // Models guard every attribute by default. List the columns that may be
   // mass-assigned from user input via create() / fill().
-  static override fillable: string[] = ['name'];
+  //
+  // \`as const\` is what lets create() narrow its payload to exactly these columns,
+  // so a column kept out of this list is neither required by the type nor accepted
+  // at runtime — instead of being demanded by one and refused by the other.
+  static override fillable = ['name'] as const;
 
   @column() name!: string;
+
+  // A nullable column is declared \`?: T | undefined\`, not \`?: T\`. The scaffold
+  // enables exactOptionalPropertyTypes, under which \`?: T\` means "may be absent,
+  // but never undefined" — so clearing the field, which is the whole point of a
+  // nullable column, would not typecheck.
+  // @column({ nullable: true }) note?: string | undefined;
 }
 `;
 }

package/src/errors/MigrationError.ts

@@ -9,10 +9,31 @@ import { ZerotalError } from "@zerotal/core";
  */
 export class MigrationError extends ZerotalError {
   constructor(migrationName: string, cause: Error) {
-    super(`Migration '${migrationName}' failed: ${cause.message}`, "E_MIGRATION_FAILED", 500, {
-      migration: migrationName,
-    });
+    super(
+      `Migration '${migrationName}' failed: ${cause.message}` + _syncHint(cause),
+      "E_MIGRATION_FAILED",
+      500,
+      { migration: migrationName },
+    );
     // Preserve the original error so its stack and message survive re-throwing.
     this.cause = cause;
   }
 }
+
+/**
+ * "table X already exists" on a migration that is supposed to create it almost always
+ * means boot-time schema sync got there first: `database.synchronize` built the table
+ * from the model before the migration ran. The two cannot both own a table, and the
+ * raw driver error gives no hint that a config flag is responsible — so name it here,
+ * at the only moment anyone is looking.
+ */
+function _syncHint(cause: Error): string {
+  if (!/already exists/i.test(cause.message)) return "";
+  return (
+    `\n\n  This usually means database.synchronize created the table from your model ` +
+    `before the migration ran.\n` +
+    `  A table can have one owner: set synchronize: false in config/database.ts and let ` +
+    `migrations build the schema,\n` +
+    `  or delete the migration and let synchronize own it.`
+  );
+}

package/src/model/BaseModel.ts

@@ -35,7 +35,7 @@ import { type ManyToMany } from "./relations/RelationRegistry.ts";
 import { installReactiveAccessors, type ColumnOptions } from "./decorators/column.ts";
 import { columnsFor, relationsFor } from "./decorators/_metadata.ts";
 import { TransactionContext } from "../db/TransactionContext.ts";
-import type { InsertPayload, UpdatePayload } from "./payload.ts";
+import type { InsertPayload, UpdatePayload, FillablePayload } from "./payload.ts";
 import type { WhereOperator, OrderDirection } from "../db/types.ts";
 
 let _dialect: "sqlite" | "postgres" | "mysql" = "sqlite";
@@ -311,8 +311,13 @@ function applyCastSet(value: unknown, cast: StringCast): unknown {
       return value;
     case "array":
     case "json":
-      if (typeof value !== "string") return JSON.stringify(value);
-      return value;
+      // Encode unconditionally. Skipping strings was meant to avoid double-encoding a
+      // value that was already JSON text, but that is indistinguishable from a string
+      // someone means to store — and guessing wrong changed the value's *type* between
+      // write and read: `"62812345678"` went in as bare characters and came back out of
+      // `JSON.parse` as a number. Encoding both ways symmetrically is the only version
+      // of this that round-trips.
+      return JSON.stringify(value);
     case "date":
       if (value instanceof Carbon) return _serializeDate(value.toDate());
       if (value instanceof Date) return _serializeDate(value);
@@ -366,7 +371,9 @@ function _serializeForWrite(
     serializedVal = applyCastSet(val, castOpt);
   } else if (colType === "boolean" && val !== null && val !== undefined) {
     serializedVal = val ? 1 : 0;
-  } else if (colType === "json" && val !== null && typeof val !== "string") {
+  } else if (colType === "json" && val !== null) {
+    // See applyCastSet: strings are encoded too, so the column always holds valid JSON
+    // and a read returns the type that was written.
     serializedVal = JSON.stringify(val);
   } else {
     serializedVal = val;
@@ -460,7 +467,7 @@ export interface ScopeApplicator {
  * — TypeScript will catch typos and non-existent column references.
  *
  * @example
- * \@table("users").withTimestamps()
+ * \@table("users")
  * export class User extends BaseModel {
  *   static fillable: Columns<User>[] = ["name", "email", "role"];
  *   static hidden:   Columns<User>[] = ["password"];
@@ -516,7 +523,7 @@ export type Columns<T> = {
  * @example
  * Defining a model with `@column`:
  * ```ts
- * @table("users").withTimestamps()
+ * @table("users")
  * export class User extends BaseModel {
  *   static fillable: Columns<User>[] = ["name", "email", "password"];
  *   static hidden: Columns<User>[] = ["password"];
@@ -660,7 +667,7 @@ export class BaseModel {
    *
    * @category Attributes & mass assignment
    */
-  static fillable?: string[];
+  static fillable?: readonly string[];
 
   /**
    * Denylist of camelCase field names blocked from create() / fill().
@@ -669,7 +676,7 @@ export class BaseModel {
    *
    * @category Attributes & mass assignment
    */
-  static guarded?: string[];
+  static guarded?: readonly string[];
 
   /**
    * Disable mass-assignment protection for this model — every attribute passed
@@ -1198,6 +1205,11 @@ export class BaseModel {
    * Mass-assign `data` (respecting {@link fillable} / {@link guarded}) onto a new
    * instance and {@link save} it, returning the persisted model.
    *
+   * When the model declares `static fillable` as a literal tuple (`as const`), the
+   * payload type is narrowed to exactly those columns — so a column deliberately kept
+   * out of `fillable` is neither required nor accepted here, instead of being demanded
+   * by the type and rejected by {@link fill} at runtime.
+   *
    * @throws {MassAssignmentError} when `data` contains a non-fillable key.
    *
    * @example
@@ -1205,7 +1217,10 @@ export class BaseModel {
    *
    * @category Persistence
    */
-  static async create<T extends BaseModel>(this: ModelCtor<T>, data: InsertPayload<T>): Promise<T> {
+  static async create<T extends BaseModel, F extends string = string>(
+    this: ModelCtor<T> & { fillable?: readonly F[] | undefined },
+    data: FillablePayload<T, F>,
+  ): Promise<T> {
     const inst = new this();
     inst.fill(data as UpdatePayload<T>);
     return inst.save() as Promise<T>;
@@ -1604,9 +1619,12 @@ export class BaseModel {
     // On INSERT: hash every hashable field that holds a non-empty string.
     // On UPDATE: only hash hashable fields whose value changed since the last
     //            save (avoids re-hashing an already-stored bcrypt hash).
+    // One keyed view of the instance for the whole method: the hashable pass and the
+    // insert's default-filling both need to read and write columns by name.
+    const self = this as unknown as Record<string, unknown>;
+
     const hashable = ModelClass.hashable;
     if (hashable && hashable.length > 0) {
-      const self = this as unknown as Record<string, unknown>;
       if (!this._exists) {
         for (const key of hashable) {
           const val = self[key];
@@ -1635,7 +1653,24 @@ export class BaseModel {
       const row: Record<string, unknown> = _writeDialect.run(dialect, () => {
         const r: Record<string, unknown> = {};
         for (const [key, val] of ownDataEntries(this, SYSTEM_KEYS, rels, colKeys)) {
-          r[toSnake(key)] = _serializeForWrite(key, val, casts, colReg);
+          // A declared field that was never assigned is `undefined`, and writing that
+          // as an explicit NULL made `@column({ default: … })` inert: the INSERT named
+          // the column, so the database never applied its own default and a NOT NULL
+          // column failed outright. Fall back to the declared default, and if there
+          // isn't one, omit the column entirely so the database decides.
+          //
+          // Only `undefined` is treated this way. An explicit `null` is a deliberate
+          // "store NULL" and still writes one.
+          let effective = val;
+          if (effective === undefined) {
+            const declared = colReg?.get(key)?.default;
+            if (declared === undefined) continue; // omit → database default / NULL
+            effective = typeof declared === "function" ? (declared as () => unknown)() : declared;
+            // Keep the instance consistent with the row we are about to write, so the
+            // value is readable straight after save() without a reload.
+            self[key] = effective;
+          }
+          r[toSnake(key)] = _serializeForWrite(key, effective, casts, colReg);
         }
         if (ModelClass.timestamps) {
           const now = _serializeDate(new Date());

package/src/model/ModelQueryBuilder.ts

@@ -1,6 +1,6 @@
 import type { SQLInstance } from "../db/sql-types.ts";
 import { Carbon } from "@zerotal/core/carbon";
-import { QueryBuilder, OPERATORS, _inlineValue } from "../db/QueryBuilder.ts";
+import { QueryBuilder, OPERATORS, _inlineValue, dialectFor } from "../db/QueryBuilder.ts";
 import {
   toCamelKey as _toCamel,
   toSnakeColumn as _toSnakeColumn,
@@ -1261,11 +1261,26 @@ export class ModelQueryBuilder<M extends BaseModel> extends QueryBuilder {
     if (colType === "boolean") {
       return value ? 1 : 0;
     }
-    if (colType === "json" && typeof value !== "string") {
+    if (colType === "json") {
+      // Match how writes encode: strings are stringified too, so a column holding
+      // `"051001"` is found by `where("value", "051001")` rather than only by a caller
+      // who knows to pre-encode the quotes themselves.
       return JSON.stringify(value);
     }
     // Carbon instances always serialize to ISO string regardless of column metadata.
     if (value instanceof Carbon) return value.toDatabase();
+    // …and so does a plain Date. Without this, a comparison against a column the cast
+    // lookup above can't see — most importantly the framework-managed `created_at` /
+    // `updated_at` / `deleted_at`, which carry no `@column` metadata — bound the Date
+    // object itself and matched nothing. `where("created_at", ">=", monthStart)` is the
+    // commonest reporting query there is, and it silently returned zero rows: a
+    // dashboard reading "0 this month" looks like a quiet month, not a broken query.
+    // A Date in a comparison is unambiguous intent, so serialize it the way writes do.
+    if (value instanceof Date) {
+      return dialectFor(this._sql) === "mysql"
+        ? value.toISOString().replace("T", " ").slice(0, 19)
+        : value.toISOString();
+    }
     return value;
   }
 

package/src/model/decorators/column.ts

@@ -19,8 +19,8 @@ export { columnRegistry };
  *
  * | Shorthand   | Equivalent options                              |
  * |-------------|--------------------------------------------------|
- * | `"string"`  | `{ type: "string" }`                            |
- * | `"text"`    | `{ type: "string" }` (large text, alias)        |
+ * | `"string"`  | `{ type: "string" }` (VARCHAR)                   |
+ * | `"text"`    | `{ type: "text" }` (unbounded TEXT)             |
  * | `"integer"` | `{ type: "number", cast: "integer" }`           |
  * | `"number"`  | `{ type: "number" }`                            |
  * | `"float"`   | `{ type: "number", cast: "float" }`             |
@@ -68,14 +68,32 @@ export type ColumnShorthand =
  * ```
  */
 export interface ColumnOptions {
-  /** Logical storage type; drives schema generation and auto-migration. @default "string" */
-  type?: "string" | "number" | "boolean" | "datetime" | "json";
+  /**
+   * Logical storage type; drives schema generation and auto-migration.
+   *
+   * `"string"` is a bounded VARCHAR; `"text"` is the unbounded TEXT type — a real
+   * distinction on Postgres and MySQL, where a long body in a VARCHAR(255) is an
+   * error rather than a slow column.
+   *
+   * @default "string"
+   */
+  type?: "string" | "text" | "number" | "boolean" | "datetime" | "json";
   /** Mark this column as the table's primary key. */
   primary?: boolean;
   /** Allow SQL `NULL` for this column. */
   nullable?: boolean;
   /** Default value applied when none is provided. */
   default?: unknown;
+  /**
+   * Add a unique index on this column during schema generation / auto-migration.
+   *
+   * Declared here rather than left to a hand-written migration because uniqueness is
+   * usually a correctness property (a webhook idempotency key, an invoice number),
+   * and `migrate:generate` can only emit constraints it can see declared.
+   */
+  unique?: boolean;
+  /** Add a plain (non-unique) index on this column. */
+  index?: boolean;
   /**
    * Shorthand cast types automatically serialize/deserialize the column value.
    * Can also be a custom object with `get`/`set` functions for full control.
@@ -113,7 +131,7 @@ export interface ColumnOptions {
  */
 const SHORTHAND_MAP: Record<ColumnShorthand, ColumnOptions> = {
   string: { type: "string" },
-  text: { type: "string" },
+  text: { type: "text" },
   integer: { type: "number", cast: "integer" },
   number: { type: "number" },
   float: { type: "number", cast: "float" },
@@ -124,7 +142,31 @@ const SHORTHAND_MAP: Record<ColumnShorthand, ColumnOptions> = {
   array: { type: "json", cast: "array" },
 };
 
-function resolveOptions(arg?: ColumnShorthand | ColumnOptions): ColumnOptions {
+/**
+ * Resolve the decorator's arguments to one options object.
+ *
+ * `extra` is the second argument of the `@column("string", { nullable: true })` form —
+ * the shorthand covers the common case and nullability is the most common modifier, so
+ * writing `@column({ type: "number", cast: "integer", nullable: true })` just to say
+ * "nullable int" is noise. The shorthand's own `type`/`cast` win: `extra` is typed as
+ * `Omit<ColumnOptions, "type">`, so it cannot contradict the type it is modifying.
+ */
+function resolveOptions(
+  arg?: ColumnShorthand | ColumnOptions,
+  extra?: Omit<ColumnOptions, "type">,
+): ColumnOptions {
+  const base = _resolveBase(arg);
+  if (!extra) return base;
+  // Spread `base` last for type/cast so the shorthand keeps ownership of them, and never
+  // write an explicit `undefined` — under exactOptionalPropertyTypes that is a distinct,
+  // and invalid, value rather than an absent key.
+  const merged: ColumnOptions = { ...extra };
+  if (base.type !== undefined) merged.type = base.type;
+  if (extra.cast === undefined && base.cast !== undefined) merged.cast = base.cast;
+  return merged;
+}
+
+function _resolveBase(arg?: ColumnShorthand | ColumnOptions): ColumnOptions {
   if (arg === undefined) return { type: "string" };
   if (typeof arg === "string") {
     const a = arg as string;
@@ -243,8 +285,15 @@ type ColumnDecorator = (value: undefined, context: ClassFieldDecoratorContext) =
 export function column(): ColumnDecorator;
 export function column(type: ColumnShorthand): ColumnDecorator;
 export function column(options: ColumnOptions): ColumnDecorator;
-export function column(arg?: ColumnShorthand | ColumnOptions): ColumnDecorator {
-  const options = resolveOptions(arg);
+export function column(
+  type: ColumnShorthand,
+  options: Omit<ColumnOptions, "type">,
+): ColumnDecorator;
+export function column(
+  arg?: ColumnShorthand | ColumnOptions,
+  extra?: Omit<ColumnOptions, "type">,
+): ColumnDecorator {
+  const options = resolveOptions(arg, extra);
   // The decorator BODY runs synchronously at definition time with the correct
   // `context.name` (the only thing Bun 1.3.x compiles reliably for field decorators).
   // We can't defer to a field initializer or addInitializer — Bun cross-wires those

package/src/model/payload.ts

@@ -92,6 +92,36 @@ type ColumnKeys<T> = WritableKeys<T> &
  */
 export type InsertPayload<T> = Omit<Pick<T, ColumnKeys<T>>, AutoManagedKeys>;
 
+/**
+ * The insert payload narrowed to a model's mass-assignable columns.
+ *
+ * `create()` funnels into `fill()`, which throws {@link MassAssignmentError} for any key
+ * outside `fillable`. Without this narrowing the type demands fields the runtime forbids:
+ * a non-optional column deliberately kept out of `fillable` — a compliance flag that must
+ * never come from a request body — is *required* by `InsertPayload`, and supplying it
+ * throws. There was no way to satisfy both.
+ *
+ * `Fillable` is inferred from the model's `static fillable`. Declare it `as const` (or as
+ * a literal tuple) and the payload becomes exactly the assignable columns: the flag is no
+ * longer required, and passing it is a compile error rather than a runtime one. When
+ * `fillable` is absent or widened to `string[]`, `Fillable` is `string` and the payload is
+ * the unnarrowed {@link InsertPayload}, so existing models are unaffected.
+ *
+ * @example
+ * class Customer extends BaseModel {
+ *   static fillable = ['name', 'email'] as const;
+ *   @column() name!: string;
+ *   @column() email!: string;
+ *   @column({ type: 'boolean', cast: 'boolean', default: false }) legalHold!: boolean;
+ * }
+ *
+ * await Customer.create({ name: 'Ada', email: 'ada@example.com' }); // ok — legalHold not required
+ * await Customer.create({ name: 'Ada', email: 'a@b.c', legalHold: true }); // compile error
+ */
+export type FillablePayload<T, Fillable extends string> = string extends Fillable
+  ? InsertPayload<T>
+  : Pick<InsertPayload<T>, Extract<keyof InsertPayload<T>, Fillable>>;
+
 /**
  * Data shape accepted when updating an existing record.
  * Every field is optional — pass only what should change.

package/src/schema/Blueprint.ts

@@ -332,6 +332,19 @@ export class Blueprint {
     return this._add(new ColumnBuilder(name, "TEXT"));
   }
 
+  /**
+   * Alias of {@link Blueprint.dateTime}, spelled the way the column *type* is.
+   *
+   * The type string is lowercase (`@column({ type: "datetime" })`) while the builder
+   * method is camelCase, so reaching for `table.datetime(...)` is the natural mistake —
+   * and the blueprint is loosely typed, so it surfaced as a `TypeError` mid-migration
+   * rather than a compile error.
+   * @category Column types
+   */
+  datetime(name: string): ColumnBuilder {
+    return this.dateTime(name);
+  }
+
   /**
    * Timestamp column. Alias of {@link Blueprint.dateTime} — stored as `TEXT` (ISO-8601).
    * @category Column types

package/src/schema/MigrationCodegen.ts

@@ -6,12 +6,23 @@ import { columnDbName, type ModelColumn, type ModelSchema } from "./ModelInspect
 // Maps @column({ type }) to the Blueprint method that generates the right SQL.
 const BLUEPRINT_METHOD: Record<string, string> = {
   string: "string",
+  text: "text",
   number: "integer",
   boolean: "boolean",
   datetime: "dateTime",
   json: "json",
 };
 
+/**
+ * A column named `*_id` (or `*Id` before snake-casing) is a foreign key by convention,
+ * and an unindexed foreign key is a table scan on every join and every cascade check.
+ * The reference itself can't always be inferred — the target table is a guess — but the
+ * index can, and it is the half that matters for performance.
+ */
+function _looksLikeForeignKey(dbName: string): boolean {
+  return dbName.endsWith("_id") && dbName !== "_id";
+}
+
 // ── Code generation helpers ───────────────────────────────────────────────────
 
 function blueprintCall(col: ModelColumn, indent: string): string {
@@ -23,6 +34,26 @@ function blueprintCall(col: ModelColumn, indent: string): string {
   return line;
 }
 
+/**
+ * The index lines for a table: everything declared via `@column({ unique | index })`,
+ * plus an inferred index on each foreign-key-shaped column that doesn't already have one.
+ */
+function indexLines(columns: ModelColumn[], indent: string): string[] {
+  const lines: string[] = [];
+  for (const col of columns) {
+    if (col.primary) continue; // the PK is already indexed by increments()
+    const dbName = columnDbName(col.name);
+    if (col.unique) {
+      lines.push(`${indent}table.unique('${dbName}');`);
+    } else if (col.index) {
+      lines.push(`${indent}table.index('${dbName}');`);
+    } else if (_looksLikeForeignKey(dbName)) {
+      lines.push(`${indent}table.index('${dbName}');`);
+    }
+  }
+  return lines;
+}
+
 function createTableBlock(schema: ModelSchema): string {
   const lines: string[] = [];
   lines.push(`    await Schema.create('${schema.table}', (table) => {`);
@@ -36,6 +67,8 @@ function createTableBlock(schema: ModelSchema): string {
   if (schema.timestamps) lines.push("      table.timestamps();");
   if (schema.softDeletes) lines.push("      table.softDeletes();");
 
+  lines.push(...indexLines(schema.columns, "      "));
+
   lines.push("    });");
   return lines.join("\n");
 }
@@ -57,6 +90,12 @@ function alterTableBlocks(newColumns: NewColumn[]): string {
     const lines: string[] = [];
     lines.push(`    await Schema.table('${table}', (table) => {`);
     for (const nc of cols) lines.push(blueprintCall(nc.column, "      "));
+    lines.push(
+      ...indexLines(
+        cols.map((nc) => nc.column),
+        "      ",
+      ),
+    );
     lines.push("    });");
     blocks.push(lines.join("\n"));
   }

package/src/schema/ModelInspector.ts

@@ -6,10 +6,14 @@ import { columnRegistry, columnsFor } from "../model/decorators/_metadata.ts";
 
 export interface ModelColumn {
   name: string;
-  type: ColumnOptions["type"]; // 'string' | 'number' | 'boolean' | 'datetime' | 'json'
+  type: ColumnOptions["type"]; // 'string' | 'text' | 'number' | 'boolean' | 'datetime' | 'json'
   nullable: boolean;
   primary: boolean;
   default: unknown;
+  /** `@column({ unique: true })` — emit a unique index for this column. */
+  unique?: boolean;
+  /** `@column({ index: true })` — emit a plain index for this column. */
+  index?: boolean;
 }
 
 export interface ModelSchema {
@@ -59,6 +63,8 @@ function toModelColumns(fields: Map<string, ColumnOptions>): ModelColumn[] {
       nullable: opts.nullable ?? false,
       primary: opts.primary ?? false,
       default: opts.default,
+      unique: opts.unique ?? false,
+      index: opts.index ?? false,
     });
   }
   return columns;

package/src/schema/Schema.ts

@@ -101,6 +101,19 @@ export const Schema = {
     }
   },
 
+  /**
+   * Alias of {@link Schema.table}, for modifying an existing table.
+   *
+   * `alter` is the name Laravel and Knex use, so it is the first thing reached for — and
+   * because the blueprint callback is loosely typed, `Schema.alter(...)` was not a type
+   * error, only a `TypeError` at run time. A migration that fails there has already run
+   * whatever statements preceded it, leaving the schema half-changed, which is a worse
+   * outcome than one that never starts.
+   */
+  async alter(name: string, callback: (bp: Blueprint) => void): Promise<void> {
+    await Schema.table(name, callback);
+  },
+
   /** `DROP TABLE table_name` */
   async drop(table: string): Promise<void> {
     await ddl(`DROP TABLE ${table}`);

package/src/schema/autoMigrate.ts

@@ -9,6 +9,7 @@ import type { ModelColumn } from "./ModelInspector.ts";
 // `migrate:generate` would - but applies it directly instead of writing a migration file.
 const BLUEPRINT_METHOD: Record<string, string> = {
   string: "string",
+  text: "text",
   number: "integer",
   boolean: "boolean",
   datetime: "dateTime",
@@ -21,15 +22,22 @@ type TableBuilder = Record<string, (name: string) => ColumnBuilder> & {
   timestamps(): void;
   softDeletes(): void;
   dropColumn(...names: string[]): unknown;
+  unique(columns: string | string[], name?: string): unknown;
+  index(columns: string | string[], name?: string): unknown;
 };
 
 function applyColumn(table: TableBuilder, col: ModelColumn): void {
   const method = BLUEPRINT_METHOD[col.type ?? "string"] ?? "string";
   // Models declare columns in camelCase; the ORM reads/writes snake_case — emit snake_case
   // so synchronize produces columns the runtime can actually read (e.g. two_factor_secret).
-  const builder = table[method]!(columnDbName(col.name));
+  const dbName = columnDbName(col.name);
+  const builder = table[method]!(dbName);
   if (col.nullable) builder.nullable();
   if (col.default !== undefined) builder.default(col.default);
+  // Declared constraints travel with the column, so a synced schema carries the same
+  // uniqueness guarantee the model asserts rather than only the column's storage type.
+  if (col.unique) table.unique(dbName);
+  else if (col.index) table.index(dbName);
 }
 
 /** Options for {@link synchronizeSchema}. */