@c9up/atlas 0.1.19 → 0.2.1

package/dist/schema/TableBuilder.js

@@ -10,14 +10,65 @@ import { compileStatementNative, getAtlasDialect, } from "../query/native.js";
 import { RawSql } from "../query/QueryBuilder.js";
 import { renderDefaultValue } from "./raw.js";
 import { TYPE_KIND_MAP, } from "./types.js";
+/**
+ * The chainable returned by `table.foreign([...])`, so the target reads in
+ * Knex order: `.references([...]).inTable('other').onDelete('cascade')`. It
+ * mutates the already-recorded constraint in place.
+ */
+export class ForeignKeyBuilder {
+    #references;
+    constructor(references) {
+        this.#references = references;
+    }
+    /** Target column(s) on the referenced table. */
+    references(columns) {
+        this.#references.columns =
+            typeof columns === "string" ? [columns] : [...columns];
+        return this;
+    }
+    /**
+     * Referenced table. Keeps returning this builder so `.onDelete()` /
+     * `.onUpdate()` can follow, as in Knex — the constraint was already
+     * recorded on the table when `foreign()` was called, so there is nothing to
+     * hand back to.
+     */
+    inTable(table) {
+        this.#references.table = table;
+        return this;
+    }
+    onDelete(action) {
+        this.#references.onDelete = action;
+        return this;
+    }
+    onUpdate(action) {
+        this.#references.onUpdate = action;
+        return this;
+    }
+}
 /** Table builder — used inside `schema.createTable(name, callback)`. */
 export class TableBuilder {
     tableName;
+    mode;
     #columns = [];
     #indexes = [];
     #currentColumn;
-    constructor(tableName) {
+    /** Ordered ALTER TABLE ops. Empty (and unused) in `create` mode. */
+    #operations = [];
+    /** Table-level constraints. In `alter` mode these become `addConstraint` ops instead. */
+    #constraints = [];
+    #options = {};
+    /** The op the pending column modifiers apply to, in `alter` mode. */
+    #currentOp;
+    /**
+     * Whether `.nullable()` / `.notNullable()` was called on the current column.
+     * `ColumnDefinition.nullable` defaults to `true`, so without this flag
+     * `.alter()` could not tell "leave nullability alone" from "make it
+     * nullable" — see `AlterOperation.setNullable`.
+     */
+    #nullabilityTouched = false;
+    constructor(tableName, mode = "create") {
         this.tableName = tableName;
+        this.mode = mode;
     }
     // ─── Column types ─────────────────────────────────────────
     uuid(name) {
@@ -42,12 +93,29 @@ export class TableBuilder {
             this.#currentColumn.length = length;
         return this;
     }
-    text(name) {
-        return this.#addColumn(name, "text");
+    /**
+     * Text column (Lucid/Knex `text(name, textType)`). `textType` widens the
+     * MySQL type (`MEDIUMTEXT` / `LONGTEXT`); Postgres and SQLite have a single
+     * unbounded `TEXT` and ignore it.
+     */
+    text(name, textType = "text") {
+        return this.#addColumn(name, textType);
     }
     integer(name) {
         return this.#addColumn(name, "integer");
     }
+    /** 24-bit integer (Lucid/Knex `mediumint`). MySQL `MEDIUMINT`; pg/SQLite widen to `INTEGER`. */
+    mediumint(name) {
+        return this.#addColumn(name, "mediumint");
+    }
+    /** 8-bit integer (Lucid `tinyint`). MySQL `TINYINT`; Postgres widens to `SMALLINT`; SQLite `INTEGER`. */
+    tinyint(name) {
+        return this.#addColumn(name, "tinyint");
+    }
+    /** 16-bit integer (Lucid `smallint`). `SMALLINT` on pg/mysql, `INTEGER` on SQLite. */
+    smallint(name) {
+        return this.#addColumn(name, "smallint");
+    }
     bigInteger(name) {
         return this.#addColumn(name, "bigInteger");
     }
@@ -59,14 +127,52 @@ export class TableBuilder {
         }
         return this;
     }
+    /**
+     * Single-precision float (Lucid `float`). `REAL` on pg/sqlite, `FLOAT` on
+     * MySQL. `precision`/`scale` render `FLOAT(p, s)` on MySQL only — pg and
+     * SQLite have fixed-width floats and ignore them.
+     */
+    float(name, precision, scale) {
+        return this.#addFloat(name, "float", precision, scale);
+    }
+    /** Double-precision float (Lucid `double`). `DOUBLE PRECISION` on pg, `REAL` on SQLite, `DOUBLE` on MySQL. See {@link float} for precision/scale. */
+    double(name, precision, scale) {
+        return this.#addFloat(name, "double", precision, scale);
+    }
     boolean(name) {
         return this.#addColumn(name, "boolean");
     }
     date(name) {
         return this.#addColumn(name, "date");
     }
-    timestamp(name) {
-        return this.#addColumn(name, "timestamp");
+    /**
+     * Time of day (Lucid `time`). `TIME` on pg/mysql, `TEXT` on SQLite.
+     * `precision` renders `TIME(p)` fractional seconds (ignored on SQLite,
+     * which has no time type to carry it).
+     */
+    time(name, precision) {
+        this.#addColumn(name, "time");
+        if (this.#currentColumn)
+            this.#currentColumn.precision = precision;
+        return this;
+    }
+    /**
+     * Timestamp column (Lucid `timestamp(name, options)`).
+     *
+     * `useTz: true` selects the tz-aware type — the same thing
+     * {@link timestamptz} does, exposed here for Lucid's option spelling.
+     * `precision` renders `TIMESTAMP(p)` (ignored on SQLite, which stores
+     * timestamps as TEXT).
+     */
+    timestamp(name, options = {}) {
+        this.#addColumn(name, options.useTz ? "timestamptz" : "timestamp");
+        if (this.#currentColumn)
+            this.#currentColumn.precision = options.precision;
+        return this;
+    }
+    /** Alias of {@link timestamp} (Lucid `dateTime`). Use `{ useTz: true }` or {@link timestamptz} for a tz-aware column. */
+    dateTime(name, options = {}) {
+        return this.timestamp(name, options);
     }
     /**
      * `timestamp WITH time zone` — Postgres normalises every writer (atlas,
@@ -83,8 +189,55 @@ export class TableBuilder {
     json(name) {
         return this.#addColumn(name, "json");
     }
-    binary(name) {
-        return this.#addColumn(name, "binary");
+    /**
+     * Binary JSON (Lucid/Knex `jsonb`). `JSONB` on pg, `JSON` on MySQL, `TEXT`
+     * on SQLite.
+     *
+     * Deviation, named: atlas's {@link json} already maps to `JSONB` on
+     * Postgres (it predates this method), where Lucid's `json()` maps to
+     * `json`. Leaving `json()` alone avoids silently rewriting the physical
+     * type of existing columns and desyncing `SchemaCheck`, so on Postgres the
+     * two spellings coincide.
+     */
+    jsonb(name) {
+        return this.#addColumn(name, "jsonb");
+    }
+    /**
+     * Binary blob (Lucid/Knex `binary(name, length)`). `BYTEA` on pg, `BLOB` on
+     * SQLite; on MySQL `length` selects `VARBINARY(n)` over `BLOB`.
+     */
+    binary(name, length) {
+        this.#addColumn(name, "binary");
+        if (this.#currentColumn)
+            this.#currentColumn.length = length;
+        return this;
+    }
+    /**
+     * A column typed with a verbatim dialect type (Lucid/Knex `specificType`) —
+     * the escape hatch for types atlas has no method for (`inet`, `tsvector`,
+     * `geometry(Point, 4326)`…).
+     *
+     * Deviation, named: Knex passes the string straight through. Atlas cannot —
+     * it lands verbatim in DDL, so the Rust compiler validates it against a
+     * narrow grammar (letters, digits, spaces, `_`, and one parenthesised
+     * argument list) and rejects anything else with `E_UNSAFE_SQL`.
+     */
+    specificType(name, type) {
+        this.#addColumn(name, "specificType");
+        if (this.#currentColumn)
+            this.#currentColumn.rawType = type;
+        return this;
+    }
+    /**
+     * Fixed value-set column (Lucid `enum`). MySQL renders a native `ENUM(...)`;
+     * Postgres and SQLite render `TEXT` plus a `CHECK (col IN (...))` that pins the
+     * value set. At least one value is required.
+     */
+    enum(name, values) {
+        this.#addColumn(name, "enum");
+        if (this.#currentColumn)
+            this.#currentColumn.values = values;
+        return this;
     }
     // ─── Shortcuts ────────────────────────────────────────────
     /**
@@ -104,9 +257,8 @@ export class TableBuilder {
      *     t.uuid('id').primary()                  // no DEFAULT
      *     // and at insert: db.insert({ id: crypto.randomUUID(), ... })
      *
-     * See `AUDIT-migration-templates.md` (shipped at the package root) for
-     * the full audit and the escape-hatch procedure if a future story makes
-     * the helper dialect-aware.
+     * (A dialect-aware escape hatch can be added later if a future story needs
+     * per-dialect PK defaults.)
      */
     id() {
         return this.uuid("id").primary().defaultTo(new RawSql("gen_random_uuid()"));
@@ -130,34 +282,46 @@ export class TableBuilder {
      *     t.timestamp('updated_at').notNullable()
      *     // and at insert: db.insert({ created_at: new Date().toISOString(), ... })
      *
-     * See `AUDIT-migration-templates.md` (shipped at the package root) for
-     * the full audit and the escape-hatch procedure if a future story makes
-     * the helper dialect-aware.
+     * (A dialect-aware escape hatch can be added later if a future story needs
+     * per-dialect PK defaults.)
      */
-    timestamps() {
-        this.timestamp("created_at").notNullable().defaultTo(new RawSql("NOW()"));
-        this.timestamp("updated_at").notNullable().defaultTo(new RawSql("NOW()"));
+    /**
+     * Add `created_at` / `updated_at` columns (Adonis Lucid / Knex
+     * `timestamps(useTimestamps, defaultToNow)`).
+     *
+     * - `useTimestamps` (default `true`): `timestamp` type; `false` → `dateTime`.
+     * - `defaultToNow` (default `true`): `NOT NULL DEFAULT CURRENT_TIMESTAMP`;
+     *   `false` → nullable, no default.
+     *
+     * The default uses `CURRENT_TIMESTAMP`, which every dialect understands —
+     * unlike `NOW()`, which SQLite rejects. So `timestamps()` and the Lucid
+     * `timestamps(true, true)` form both port to SQLite/Postgres/MySQL unchanged.
+     */
+    timestamps(useTimestamps = true, defaultToNow = true) {
+        const add = (name) => {
+            if (useTimestamps)
+                this.timestamp(name);
+            else
+                this.dateTime(name);
+            if (defaultToNow) {
+                this.notNullable().defaultTo(new RawSql("CURRENT_TIMESTAMP"));
+            }
+        };
+        add("created_at");
+        add("updated_at");
         return this;
     }
     // ─── Column modifiers ─────────────────────────────────────
-    primary() {
-        if (this.#currentColumn)
-            this.#currentColumn.primary = true;
-        return this;
-    }
     notNullable() {
         if (this.#currentColumn)
             this.#currentColumn.nullable = false;
+        this.#nullabilityTouched = true;
         return this;
     }
     nullable() {
         if (this.#currentColumn)
             this.#currentColumn.nullable = true;
-        return this;
-    }
-    unique() {
-        if (this.#currentColumn)
-            this.#currentColumn.unique = true;
+        this.#nullabilityTouched = true;
         return this;
     }
     /**
@@ -171,9 +335,267 @@ export class TableBuilder {
         }
         return this;
     }
-    references(table, column = "id") {
+    /** MySQL `UNSIGNED` numeric modifier (Lucid `unsigned()`). No-op on pg/sqlite. */
+    unsigned() {
         if (this.#currentColumn)
-            this.#currentColumn.references = { table, column };
+            this.#currentColumn.unsigned = true;
+        return this;
+    }
+    /**
+     * Declare the current column a foreign key.
+     *
+     * - `references('users', 'id')` — atlas form `(table, column='id')`.
+     * - `references('users.id')` — Lucid/Knex dotted `'table.column'` shorthand, so
+     *   a migration copied from Lucid resolves the target the same way. A single
+     *   argument without a dot is treated as the table name (column defaults to
+     *   `id`), preserving the atlas one-arg behaviour.
+     */
+    references(tableOrPath, column) {
+        let table = tableOrPath;
+        let col = column ?? "id";
+        const dot = tableOrPath.indexOf(".");
+        // Dotted shorthand only when no explicit column was passed — an explicit
+        // second arg always wins, so `references('a.b', 'c')` stays (table 'a.b').
+        if (dot !== -1 && column === undefined) {
+            table = tableOrPath.slice(0, dot);
+            col = tableOrPath.slice(dot + 1);
+        }
+        if (this.#currentColumn) {
+            this.#currentColumn.references = { table, column: col };
+        }
+        return this;
+    }
+    /**
+     * Referential action for the current column's foreign key `ON DELETE`
+     * (Lucid parity). Must follow {@link references}.
+     */
+    onDelete(action) {
+        if (this.#currentColumn?.references) {
+            this.#currentColumn.references.onDelete = action;
+        }
+        return this;
+    }
+    /** Referential action for the current column's foreign key `ON UPDATE`. Must follow {@link references}. */
+    onUpdate(action) {
+        if (this.#currentColumn?.references) {
+            this.#currentColumn.references.onUpdate = action;
+        }
+        return this;
+    }
+    /**
+     * Comment the current **column** (Lucid/Knex column `comment()`). Inline on
+     * MySQL, a separate `COMMENT ON COLUMN` on Postgres, dropped on SQLite.
+     *
+     * Deviation, named: Knex's `table.comment()` is the TABLE comment, because
+     * its column methods return a separate column builder. Atlas flattens the
+     * column modifiers onto the table builder (`.notNullable()`, `.unique()`,
+     * `.defaultTo()` all work this way), so `comment()` follows that same rule
+     * and the table comment is {@link tableComment}. Resolving it by "is a
+     * column pending?" would be exactly the kind of guessing that bites later.
+     */
+    comment(text) {
+        if (this.#currentColumn)
+            this.#currentColumn.comment = text;
+        return this;
+    }
+    /** Collate the current **column** (Lucid/Knex column `collate()`). See {@link comment} for why the table form is {@link tableCollate}. */
+    collate(collation) {
+        if (this.#currentColumn)
+            this.#currentColumn.collate = collation;
+        return this;
+    }
+    /**
+     * Place an added column first (Lucid/Knex `first()`). MySQL-only —
+     * Postgres and SQLite always append, and the Rust compiler raises
+     * `E_UNSUPPORTED` rather than dropping the instruction silently.
+     */
+    first() {
+        if (this.#currentColumn)
+            this.#currentColumn.position = { at: "first" };
+        return this;
+    }
+    /** Place an added column after `column` (Lucid/Knex `after()`). MySQL-only — see {@link first}. */
+    after(column) {
+        if (this.#currentColumn) {
+            this.#currentColumn.position = { at: "after", column };
+        }
+        return this;
+    }
+    // ─── CHECK constraints ────────────────────────────────────
+    /** `CHECK (col > 0)` on the current column (Lucid/Knex `checkPositive`). */
+    checkPositive(constraintName) {
+        return this.#addCheck((column) => ({ check: "positive", column }), constraintName);
+    }
+    /** `CHECK (col < 0)` on the current column (Lucid/Knex `checkNegative`). */
+    checkNegative(constraintName) {
+        return this.#addCheck((column) => ({ check: "negative", column }), constraintName);
+    }
+    /** `CHECK (col IN (…))` on the current column (Lucid/Knex `checkIn`). Values are quoted, never interpolated raw. */
+    checkIn(values, constraintName) {
+        return this.#addCheck((column) => ({ check: "in", column, values: [...values] }), constraintName);
+    }
+    /** `CHECK (col NOT IN (…))` on the current column (Lucid/Knex `checkNotIn`). */
+    checkNotIn(values, constraintName) {
+        return this.#addCheck((column) => ({ check: "notIn", column, values: [...values] }), constraintName);
+    }
+    /**
+     * `CHECK (col BETWEEN lo AND hi)` on the current column (Lucid/Knex
+     * `checkBetween`). Accepts one `[min, max]` interval or a list of them —
+     * several intervals are OR'd together, as in Knex.
+     */
+    checkBetween(range, constraintName) {
+        // A single [min, max] vs a list of intervals: the first element of a
+        // list-of-intervals is itself an array.
+        const ranges = Array.isArray(range[0])
+            ? range.map((r) => [...r])
+            : [[...range]];
+        return this.#addCheck((column) => ({ check: "between", column, ranges }), constraintName);
+    }
+    /** `CHECK (LENGTH(col) <op> n)` on the current column (Lucid/Knex `checkLength`). The operator is allow-listed by the Rust compiler. */
+    checkLength(operator, length, constraintName) {
+        return this.#addCheck((column) => ({ check: "length", column, operator, length }), constraintName);
+    }
+    /**
+     * `CHECK (col ~ 'pattern')` on the current column (Lucid/Knex `checkRegex`).
+     * Postgres spells it `~`; MySQL and SQLite use `REGEXP`.
+     *
+     * SQLite parses `REGEXP` but ships no implementation — the constraint only
+     * works if the connection registers a `regexp` function. Knex behaves the
+     * same way, so this is parity rather than a new trap, but it is worth
+     * knowing before you rely on it there.
+     */
+    checkRegex(pattern, constraintName) {
+        return this.#addCheck((column) => ({ check: "regex", column, pattern }), constraintName);
+    }
+    /**
+     * A free-form `CHECK (predicate)` (Lucid/Knex `check`). The predicate is
+     * emitted verbatim — exactly as trusted as {@link Schema.raw}, so never
+     * build it from user input. Prefer the typed `check*` helpers, which are
+     * safe by construction.
+     */
+    check(predicate, constraintName) {
+        this.#pushConstraint({
+            constraint: "check",
+            name: constraintName,
+            expr: { check: "raw", predicate },
+        });
+        return this;
+    }
+    /** Drop named CHECK constraints (Lucid/Knex `dropChecks`). */
+    dropChecks(...constraintNames) {
+        this.#assertAlterMode("dropChecks()");
+        for (const name of constraintNames) {
+            this.#pushStandaloneOp({ op: "dropConstraint", name });
+        }
+        return this;
+    }
+    // ─── Table-level constraints ──────────────────────────────
+    /**
+     * With no argument, mark the current column as the primary key (the
+     * existing column modifier). With a column list, declare a composite
+     * `PRIMARY KEY (…)` table constraint (Lucid/Knex `primary([...])`).
+     */
+    primary(columns, constraintName) {
+        if (columns === undefined) {
+            if (this.#currentColumn)
+                this.#currentColumn.primary = true;
+            return this;
+        }
+        this.#pushConstraint({
+            constraint: "primary",
+            name: constraintName,
+            columns: [...columns],
+        });
+        return this;
+    }
+    /**
+     * With no argument, mark the current column `UNIQUE` (the existing column
+     * modifier). With a column list, declare a composite `UNIQUE (…)` table
+     * constraint (Lucid/Knex `unique([...])`).
+     *
+     * Note this is a real constraint, unlike {@link uniqueIndex}, which creates
+     * a separate `CREATE UNIQUE INDEX`.
+     */
+    unique(columns, constraintName) {
+        if (columns === undefined) {
+            if (this.#currentColumn)
+                this.#currentColumn.unique = true;
+            return this;
+        }
+        this.#pushConstraint({
+            constraint: "unique",
+            name: constraintName ?? this.#constraintName(columns, "unique"),
+            columns: [...columns],
+        });
+        return this;
+    }
+    /**
+     * Declare a composite foreign key (Lucid/Knex
+     * `foreign([...]).references([...]).inTable(…)`). Returns a small chainable
+     * so the target reads in Knex order; the constraint is recorded up front
+     * and filled in as you chain.
+     */
+    foreign(columns, constraintName) {
+        const cols = typeof columns === "string" ? [columns] : [...columns];
+        const references = { table: "", columns: [] };
+        this.#pushConstraint({
+            constraint: "foreign",
+            name: constraintName ?? this.#constraintName(cols, "foreign"),
+            columns: cols,
+            references,
+        });
+        // The constraint is already recorded; the builder fills `references` in
+        // place as the caller chains, so order of arrival doesn't matter.
+        return new ForeignKeyBuilder(references);
+    }
+    // ─── Dropping constraints ─────────────────────────────────
+    /** Drop the primary key (Lucid/Knex `dropPrimary`). MySQL drops it by keyword; Postgres by name (default `<table>_pkey`). */
+    dropPrimary(constraintName) {
+        this.#assertAlterMode("dropPrimary()");
+        this.#pushStandaloneOp({ op: "dropPrimary", name: constraintName });
+        return this;
+    }
+    /** Drop a unique constraint by columns (using the default name) or by explicit name (Lucid/Knex `dropUnique`). */
+    dropUnique(columns, constraintName) {
+        this.#assertAlterMode("dropUnique()");
+        this.#pushStandaloneOp({
+            op: "dropUnique",
+            name: constraintName ?? this.#constraintName(columns, "unique"),
+        });
+        return this;
+    }
+    /** Drop a foreign key by columns (using the default name) or by explicit name (Lucid/Knex `dropForeign`). */
+    dropForeign(columns, constraintName) {
+        this.#assertAlterMode("dropForeign()");
+        this.#pushStandaloneOp({
+            op: "dropForeign",
+            name: constraintName ?? this.#constraintName(columns, "foreign"),
+        });
+        return this;
+    }
+    /** Drop `created_at` + `updated_at` (Lucid/Knex `dropTimestamps`). */
+    dropTimestamps() {
+        return this.dropColumns("created_at", "updated_at");
+    }
+    // ─── Table options ────────────────────────────────────────
+    /** MySQL storage engine (Lucid/Knex `engine`). Ignored on pg/sqlite. */
+    engine(name) {
+        this.#options.engine = name;
+        return this;
+    }
+    /** MySQL default charset (Lucid/Knex `charset`). Ignored on pg/sqlite. */
+    charset(name) {
+        this.#options.charset = name;
+        return this;
+    }
+    /** MySQL default collation for the table. Named `tableCollate` because {@link collate} is the column modifier — see {@link comment}. */
+    tableCollate(name) {
+        this.#options.collate = name;
+        return this;
+    }
+    /** Table comment. Named `tableComment` because {@link comment} is the column modifier — see there for why. */
+    tableComment(text) {
+        this.#options.comment = text;
         return this;
     }
     // ─── Indexes ──────────────────────────────────────────────
@@ -195,6 +617,78 @@ export class TableBuilder {
         });
         return this;
     }
+    // ─── ALTER TABLE operations ───────────────────────────────
+    /**
+     * Apply the pending column definition as a type change instead of an
+     * `ADD COLUMN` (Lucid/Knex `alter()`). Must follow a column-type method.
+     *
+     * Nullability moves only if `.nullable()` / `.notNullable()` was called
+     * before this — a bare `t.string('x').alter()` changes the type and leaves
+     * the NOT NULL constraint exactly as it is.
+     *
+     * SQLite cannot alter a column in place; the Rust compiler rejects it with
+     * `E_UNSUPPORTED` rather than emitting a table rebuild behind your back.
+     */
+    alter() {
+        this.#assertAlterMode("alter()");
+        const pending = this.#currentOp;
+        if (!pending) {
+            throw new Error("E_ALTER_MISUSE: alter() must follow a column definition, e.g. table.string('email').alter()");
+        }
+        if (pending.op === "addColumn") {
+            const converted = {
+                op: "alterColumn",
+                column: pending.column,
+                setNullable: this.#nullabilityTouched
+                    ? pending.column.nullable
+                    : undefined,
+            };
+            this.#operations[this.#operations.indexOf(pending)] = converted;
+            this.#currentOp = converted;
+        }
+        return this;
+    }
+    /** Drop a column (Lucid/Knex `dropColumn`). */
+    dropColumn(name) {
+        this.#assertAlterMode("dropColumn()");
+        this.#pushStandaloneOp({ op: "dropColumn", name });
+        return this;
+    }
+    /** Drop several columns in call order (Lucid/Knex `dropColumns`). */
+    dropColumns(...names) {
+        for (const name of names)
+            this.dropColumn(name);
+        return this;
+    }
+    /** Rename a column (Lucid/Knex `renameColumn`). */
+    renameColumn(from, to) {
+        this.#assertAlterMode("renameColumn()");
+        this.#pushStandaloneOp({ op: "renameColumn", from, to });
+        return this;
+    }
+    /**
+     * Make an existing column nullable — `DROP NOT NULL` (Lucid/Knex
+     * `setNullable`).
+     *
+     * **Deviation from Knex, named deliberately.** Knex supports this on every
+     * dialect by querying `columnInfo()` at runtime to recover the column's
+     * type. Atlas compiles SQL synchronously in Rust with no round-trip, so
+     * this is Postgres-only — Postgres is the one dialect whose syntax needs no
+     * type. On MySQL use `table.<type>('col').nullable().alter()`, which
+     * restates the type; SQLite cannot alter a column in place at all. Both
+     * raise `E_UNSUPPORTED` with the alternative spelled out.
+     */
+    setNullable(name) {
+        this.#assertAlterMode("setNullable()");
+        this.#pushStandaloneOp({ op: "setNullable", name, nullable: true });
+        return this;
+    }
+    /** Make an existing column `NOT NULL` (Lucid/Knex `dropNullable`). Postgres-only — see {@link setNullable}. */
+    dropNullable(name) {
+        this.#assertAlterMode("dropNullable()");
+        this.#pushStandaloneOp({ op: "setNullable", name, nullable: false });
+        return this;
+    }
     // ─── Accessors ────────────────────────────────────────────
     getColumns() {
         return [...this.#columns];
@@ -202,32 +696,125 @@ export class TableBuilder {
     getIndexes() {
         return [...this.#indexes];
     }
+    /** Ordered ALTER TABLE operations. Empty in `create` mode. */
+    getOperations() {
+        return [...this.#operations];
+    }
     /** Compile to SQL statements via the Rust compiler. */
-    toStatements(dialect = getAtlasDialect()) {
-        const spec = {
-            kind: "createTable",
-            table: this.tableName,
-            columns: this.#columns.map((c) => ({
-                name: c.name,
-                kind: TYPE_KIND_MAP[c.type],
-                length: c.length ?? null,
-                precision: c.precision ?? null,
-                scale: c.scale ?? null,
-                nullable: c.nullable,
-                primary: c.primary,
-                autoIncrement: c.autoIncrement ?? false,
-                unique: c.unique,
-                default: c.defaultValue ?? null,
-                references: c.references ?? null,
-            })),
-            indexes: this.#indexes.map((i) => ({
-                name: i.name,
-                columns: i.columns,
-                unique: i.unique,
-            })),
-            ifNotExists: false,
+    toStatements(dialect = getAtlasDialect(), options = {}) {
+        const spec = this.mode === "alter"
+            ? {
+                kind: "alterTable",
+                table: this.tableName,
+                operations: this.#operations.map((op) => op.op === "addColumn"
+                    ? { op: op.op, column: this.#serializeColumn(op.column) }
+                    : op.op === "alterColumn"
+                        ? {
+                            op: op.op,
+                            column: this.#serializeColumn(op.column),
+                            setNullable: op.setNullable ?? null,
+                        }
+                        : op),
+            }
+            : {
+                kind: "createTable",
+                table: this.tableName,
+                columns: this.#columns.map((c) => this.#serializeColumn(c)),
+                indexes: this.#indexes.map((i) => ({
+                    name: i.name,
+                    columns: i.columns,
+                    unique: i.unique,
+                })),
+                ifNotExists: options.ifNotExists ?? false,
+                constraints: this.#constraints,
+                options: this.#options,
+            };
+        const statements = compileStatementNative(spec, dialect).statements;
+        // `alterTable` carries no index list — an index added alongside an
+        // ALTER compiles to its own CREATE INDEX, appended in declaration order.
+        if (this.mode === "alter" && this.#indexes.length > 0) {
+            for (const idx of this.#indexes) {
+                statements.push(...compileStatementNative({
+                    kind: "createIndex",
+                    table: this.tableName,
+                    name: idx.name,
+                    columns: idx.columns,
+                    unique: idx.unique,
+                }, dialect).statements);
+            }
+        }
+        return statements;
+    }
+    /** Flatten a column into the wire shape the Rust `ColumnDef` deserialises. */
+    #serializeColumn(c) {
+        return {
+            name: c.name,
+            kind: TYPE_KIND_MAP[c.type],
+            length: c.length ?? null,
+            precision: c.precision ?? null,
+            scale: c.scale ?? null,
+            // Flattened into the Rust ColumnTypeSpec — each read for one kind only.
+            values: c.values ?? null,
+            rawType: c.rawType ?? null,
+            nullable: c.nullable,
+            primary: c.primary,
+            autoIncrement: c.autoIncrement ?? false,
+            unique: c.unique,
+            unsigned: c.unsigned ?? false,
+            default: c.defaultValue ?? null,
+            references: c.references ?? null,
+            comment: c.comment ?? null,
+            collate: c.collate ?? null,
+            position: c.position ?? null,
         };
-        return compileStatementNative(spec, dialect).statements;
+    }
+    /**
+     * Record a constraint. In `create` mode it renders inside the
+     * `CREATE TABLE`; in `alter` mode it becomes an `ADD CONSTRAINT`, kept in
+     * call order with the surrounding column operations.
+     */
+    #pushConstraint(spec) {
+        if (this.mode === "alter") {
+            this.#operations.push({ op: "addConstraint", constraint: spec });
+        }
+        else {
+            this.#constraints.push(spec);
+        }
+    }
+    /** Build a CHECK against the pending column. */
+    #addCheck(build, constraintName) {
+        const column = this.#currentColumn?.name;
+        if (!column) {
+            throw new Error("E_CHECK_MISUSE: a check* helper must follow a column definition, e.g. table.integer('qty').checkPositive()");
+        }
+        this.#pushConstraint({
+            constraint: "check",
+            name: constraintName,
+            expr: build(column),
+        });
+        return this;
+    }
+    /**
+     * Default constraint name, following Knex's `<table>_<columns>_<suffix>`
+     * convention so `unique([...])` and `dropUnique([...])` agree without the
+     * caller naming anything. Distinct from {@link uniqueIndex}, which names a
+     * separate INDEX object `idx_…`.
+     */
+    #constraintName(columns, suffix) {
+        const cols = typeof columns === "string" ? [columns] : columns;
+        return `${this.tableName}_${cols.join("_")}_${suffix}`;
+    }
+    #assertAlterMode(method) {
+        if (this.mode !== "alter") {
+            throw new Error(`E_ALTER_MISUSE: ${method} is only available inside schema.alterTable() — a new table has nothing to alter`);
+        }
+    }
+    /** Record an op that takes no column modifiers, so `.nullable()` etc. can't silently attach to it. */
+    #pushStandaloneOp(op) {
+        this.#operations.push(op);
+        this.#currentColumn = undefined;
+        this.#currentOp = undefined;
+        this.#nullabilityTouched = false;
     }
     #addColumn(name, type) {
         const col = {
@@ -239,6 +826,23 @@ export class TableBuilder {
         };
         this.#columns.push(col);
         this.#currentColumn = col;
+        this.#nullabilityTouched = false;
+        if (this.mode === "alter") {
+            const op = {
+                op: "addColumn",
+                column: col,
+            };
+            this.#operations.push(op);
+            this.#currentOp = op;
+        }
+        return this;
+    }
+    #addFloat(name, type, precision, scale) {
+        this.#addColumn(name, type);
+        if (this.#currentColumn) {
+            this.#currentColumn.precision = precision;
+            this.#currentColumn.scale = scale;
+        }
         return this;
     }
     #addIncrements(name, type) {