velocious 1.0.612 → 1.0.614

package/README.md

@@ -7,7 +7,7 @@
 * Connection-scoped advisory locks with automatic cleanup before pooled connections are reused or closed (see [docs/advisory-locks.md](docs/advisory-locks.md))
 * Built-in record auditing for model lifecycle changes (see [docs/auditing.md](docs/auditing.md))
 * Declarative state machines for models, with typed event methods generated into the base model (see [docs/state-machine.md](docs/state-machine.md))
-* Migrations for schema changes and UTC datetime storage (see [docs/database-migrations.md](docs/database-migrations.md))
+* Migrations for schema changes and UTC datetime storage, including recorded `changeTable` batches that combine operations into one `ALTER` on bulk-capable drivers (see [docs/database-migrations.md](docs/database-migrations.md) and [docs/change-table.md](docs/change-table.md))
 * Tenant-selected base-model and structure generation with one immutable, fail-closed physical database context; tenant-only model metadata initializes only after that context is active (see [docs/tenant-selected-database-generation.md](docs/tenant-selected-database-generation.md))
 * Read-only tenant migration deploy preflight with stable JSON output and fail-closed ledger reads (see [docs/tenant-migration-deploy-preflight.md](docs/tenant-migration-deploy-preflight.md))
 * External packages (engines) that contribute data models, frontend-model resources and migrations to a consuming app (see [docs/packages.md](docs/packages.md))
@@ -2396,7 +2396,7 @@ VELOCIOUS_BACKGROUND_JOBS_JOB_TIMEOUT_MS=5400000
 
 `maxConcurrentInlineJobs` (default: `4`) caps how many `executionMode: "inline"` jobs a single `background-jobs-worker` process runs in parallel. Concurrency is at the JS event-loop level: every job in flight shares the worker's process and DB connection pool, so the cap should fit the pool, not the CPU count. Forking remains the right tool when you need memory isolation across long-running jobs or want to use more cores; select it with `executionMode: "forked"`.
 
-New jobs default to `executionMode: "pooled"`: a worker runs them in warm, reusable Node child runners. `pooledRunnerCount` (default: `4`) bounds this independent per-worker pool, and `pooledRunnerConcurrency` (default: `1`) sets how many jobs each child runs at once on its own event loop, so total pooled capacity is `pooledRunnerCount × pooledRunnerConcurrency` — raise concurrency for I/O-bound jobs to get high throughput from a bounded, isolated set of processes. Workers advertise that exact free-slot count and the main consumes one slot per durable handoff, allowing one readiness notification to fill the pool. `pooledRunnerCount`, `pooledRunnerConcurrency`, and `pooledRunnerMaxJobs` must be finite positive integers; the RSS and lifetime limits must be finite positive numbers. A child is recycled after an acknowledged job when it reaches `pooledRunnerMaxJobs` (default: `100`), `pooledRunnerMaxRssBytes` (default: `536870912`, or 512 MiB), or `pooledRunnerMaxLifetimeMs` (default: `3600000`, or one hour). `execution_mode` is the single source of truth for a job's runtime — pooled rows persist as `execution_mode = "pooled"` directly. See [execution modes and pooled runners](docs/background-jobs.md#execution-modes-and-pooled-runners).
+New jobs default to `executionMode: "pooled"`: a worker runs them in warm, reusable Node child runners. `pooledRunnerCount` (default: `4`) bounds this independent per-worker pool, and `pooledRunnerConcurrency` (default: `1`) sets how many jobs each child runs at once on its own event loop, so total pooled capacity is `pooledRunnerCount × pooledRunnerConcurrency` — raise concurrency for I/O-bound jobs to get high throughput from a bounded, isolated set of processes. Workers advertise that exact free-slot count and the main consumes one slot per durable handoff, allowing one readiness notification to fill the pool. If an initialized child exits unexpectedly, the worker immediately advertises the freed capacity while failure reports retry; the replacement is spawned lazily by the next dispatch, and a pre-startup crash does not trigger a respawn loop. `pooledRunnerCount`, `pooledRunnerConcurrency`, and `pooledRunnerMaxJobs` must be finite positive integers; the RSS and lifetime limits must be finite positive numbers. A child is recycled after an acknowledged job when it reaches `pooledRunnerMaxJobs` (default: `100`), `pooledRunnerMaxRssBytes` (default: `536870912`, or 512 MiB), or `pooledRunnerMaxLifetimeMs` (default: `3600000`, or one hour). `execution_mode` is the single source of truth for a job's runtime — pooled rows persist as `execution_mode = "pooled"` directly. See [execution modes and pooled runners](docs/background-jobs.md#execution-modes-and-pooled-runners).
 
 Cold pooled jobs share one atomic model-bootstrap phase. If that phase fails, all
 waiting jobs receive the failure; a later job in the surviving child cannot run

package/build/background-jobs/pooled-runner-child.js

@@ -141,3 +141,4 @@ function handleMessage(message) {
 process.on("message", (message) => handleMessage(message))
 process.once("disconnect", () => void shutdownRunner(0))
 for (const signal of ["SIGTERM", "SIGINT"]) process.once(signal, () => void shutdownRunner(1))
+if (process.send) process.send({type: "ready"})

package/build/background-jobs/worker.js

@@ -194,8 +194,10 @@ export default class BackgroundJobsWorker {
     this.inflightPooledJobs = new Set()
     /** @type {Set<import("node:child_process").ChildProcess>} */
     this.pooledChildren = new Set()
-    /** @type {Map<import("node:child_process").ChildProcess, {createdAtMs: number, jobsRun: number, inflight: Map<string, {payload: import("./types.js").BackgroundJobPayload & {id: string}, resolve?: (value: void) => void, timeoutTimer?: ReturnType<typeof setTimeout> | null}>, lastDispatchSeq: number, retiring: boolean, settling?: boolean, timeoutSigkillTimer?: ReturnType<typeof setTimeout> | null}>} */
+    /** @type {Map<import("node:child_process").ChildProcess, {createdAtMs: number, jobsRun: number, inflight: Map<string, {payload: import("./types.js").BackgroundJobPayload & {id: string}, resolve?: (value: void) => void, pooledJob?: Promise<void>, timeoutTimer?: ReturnType<typeof setTimeout> | null}>, lastDispatchSeq: number, retiring: boolean, started?: boolean, settling?: boolean, timeoutSigkillTimer?: ReturnType<typeof setTimeout> | null}>} */
     this.pooledChildStates = new Map()
+    /** @type {WeakSet<Promise<void>>} */
+    this._pooledStartupFailureJobs = new WeakSet()
     // Monotonic dispatch counter for round-robin child selection: each dispatch stamps
     // the chosen child, and selection prefers the child dispatched least recently.
     this._pooledDispatchSeq = 0
@@ -600,16 +602,16 @@ export default class BackgroundJobsWorker {
   }
 
   /**
-   * Tells main we're ready for the next job — but only if we haven't been
-   * asked to drain. Once we've sent `draining` we don't want to take more
-   * work.
+   * Advertises current worker capacity unless the worker is draining.
+   * @param {object} [options] - Advertisement options.
+   * @param {boolean} [options.revokePooledAdmission] - Revoke pooled credits while preserving other execution modes.
    * @returns {void}
    */
-  _sendReadyIfRunning() {
+  _sendReadyIfRunning({revokePooledAdmission = false} = {}) {
     if (this.shouldStop) return
     if (!this.jsonSocket) return
 
-    const readyMessage = this._readyMessage()
+    const readyMessage = this._readyMessage({revokePooledAdmission})
 
     if (!readyMessage) return
     this.jsonSocket.send(readyMessage)
@@ -617,21 +619,24 @@ export default class BackgroundJobsWorker {
 
   /**
    * Runs ready message.
+   * @param {object} [options] - Advertisement options.
+   * @param {boolean} [options.revokePooledAdmission] - Revoke pooled credits while preserving other execution modes.
    * @returns {import("./types.js").BackgroundJobSocketMessage | null} - Ready message or null when the worker has no capacity.
    */
-  _readyMessage() {
+  _readyMessage({revokePooledAdmission = false} = {}) {
     const acceptsProcessJob = this.inflightProcessJobs.size < this.maxConcurrentForkedJobs
     const acceptsInline = this.inflightInlineJobs.size < this.maxConcurrentInlineJobs
-    const acceptsPooled = this._availablePooledSlots() > 0
+    const availablePooledSlots = revokePooledAdmission ? 0 : this._availablePooledSlots()
+    const acceptsPooled = availablePooledSlots > 0
 
-    if (!acceptsProcessJob && !acceptsInline && !acceptsPooled) return null
+    if (!revokePooledAdmission && !acceptsProcessJob && !acceptsInline && !acceptsPooled) return null
 
     return {
       type: "ready",
       acceptsForked: acceptsProcessJob,
       acceptsInline,
       acceptsPooled,
-      availablePooledSlots: this._availablePooledSlots(),
+      availablePooledSlots,
       acceptsSpawned: acceptsProcessJob
     }
   }
@@ -646,7 +651,7 @@ export default class BackgroundJobsWorker {
     let inflight
     inflight = pooledJob.finally(() => {
       this.inflightPooledJobs.delete(inflight)
-      if (!this.shouldStop) this._sendReadyIfRunning()
+      if (!this.shouldStop && !this._pooledStartupFailureJobs.has(pooledJob)) this._sendReadyIfRunning()
     })
     this.inflightPooledJobs.add(inflight)
   }
@@ -689,16 +694,22 @@ export default class BackgroundJobsWorker {
     // Stamp the round-robin cursor so the next dispatch prefers a different child.
     state.lastDispatchSeq = ++this._pooledDispatchSeq
 
-    return new Promise((resolve) => {
-      const timeoutTimer = this._armPooledJobTimeout({child, payload})
+    /**
+     * Resolves the pooled job promise.
+     * @type {(value: void) => void}
+     */
+    let resolvePooledJob = () => {}
+    const pooledJob = new Promise((resolve) => { resolvePooledJob = resolve })
+    const timeoutTimer = this._armPooledJobTimeout({child, payload})
 
-      state.inflight.set(payload.id, {payload, resolve, timeoutTimer})
-      try {
-        child.send({type: "job", payload, sharedTransactionBroker: this._pooledJobSharedTransactionBrokerConfig()})
-      } catch (error) {
-        void this._handlePooledChildFailure({child, error})
-      }
-    })
+    state.inflight.set(payload.id, {payload, resolve: resolvePooledJob, pooledJob, timeoutTimer})
+    try {
+      child.send({type: "job", payload, sharedTransactionBroker: this._pooledJobSharedTransactionBrokerConfig()})
+    } catch (error) {
+      void this._handlePooledChildFailure({child, error})
+    }
+
+    return pooledJob
   }
 
   /**
@@ -769,7 +780,8 @@ export default class BackgroundJobsWorker {
    * (SIGTERM, then SIGKILL after the grace) — a hung JS job cannot be cancelled
    * any other way. The non-clean exit flows through `_handlePooledChildFailure`,
    * which reports every in-flight job on the child failed (so they requeue) and
-   * drops it from tracking; capacity is refilled on the next dispatch.
+   * drops it from tracking; the failure path immediately re-advertises the
+   * resulting capacity once the runner has completed startup.
    * @param {object} args - Options.
    * @param {import("node:child_process").ChildProcess} args.child - Pooled child.
    * @param {string} args.jobId - Job id that overran.
@@ -810,7 +822,7 @@ export default class BackgroundJobsWorker {
     })
     this.pooledChildren.add(child)
     this.inflightProcessChildren.add(child)
-    this.pooledChildStates.set(child, {createdAtMs: Date.now(), jobsRun: 0, inflight: new Map(), lastDispatchSeq: 0, retiring: false})
+    this.pooledChildStates.set(child, {createdAtMs: Date.now(), jobsRun: 0, inflight: new Map(), lastDispatchSeq: 0, retiring: false, started: false})
     child.on("message", (message) => this._handlePooledChildMessage({child, message}))
     child.once("exit", (code, signal) => this._handlePooledChildFailure({child, error: new Error(`Pooled background job runner exited: code=${code} signal=${signal || "none"}`)}))
     child.once("error", (error) => this._handlePooledChildFailure({child, error}))
@@ -829,7 +841,12 @@ export default class BackgroundJobsWorker {
     if (!message || typeof message !== "object") return
     const record = /** @type {{type?: ReturnType<typeof JSON.parse>, jobId?: ReturnType<typeof JSON.parse>, acknowledged?: ReturnType<typeof JSON.parse>, rssBytes?: ReturnType<typeof JSON.parse>, error?: ReturnType<typeof JSON.parse>}} */ (message)
     const state = this.pooledChildStates.get(child)
+    if (record.type === "ready") {
+      if (state) state.started = true
+      return
+    }
     if (record.type !== "job-outcome" || !state || state.settling || typeof record.jobId !== "string") return
+    state.started = true
     const entry = state.inflight.get(record.jobId)
     if (!entry) return
 
@@ -907,9 +924,11 @@ export default class BackgroundJobsWorker {
   /**
    * Removes an exited/unhealthy pooled child and reports every job that was
    * in-flight on it as failed — a process-level crash's blast radius is the
-   * child's whole in-flight set. Capacity is refilled lazily on the next
-   * dispatch (a spawnable slot is still advertised), avoiding a tight respawn
-   * loop when a child crashes on startup.
+   * child's whole in-flight set. Once the child has completed startup, its
+   * freed capacity is advertised immediately; the replacement itself is still
+   * spawned lazily by the next dispatch. A child that exits before its startup
+   * handshake does not re-announce, avoiding a tight respawn loop on startup
+   * failure.
    * @param {object} args - Failure details.
    * @param {import("node:child_process").ChildProcess} args.child - Pooled child.
    * @param {ReturnType<typeof JSON.parse>} args.error - Failure.
@@ -934,7 +953,7 @@ export default class BackgroundJobsWorker {
     if (state) state.inflight.clear()
     this.pooledChildStates.delete(child)
 
-    await Promise.allSettled(entries.map(async (entry) => {
+    const failureReports = entries.map(async (entry) => {
       await this._reportJobResult({
         jobId: entry.payload.id,
         status: "failed",
@@ -944,7 +963,26 @@ export default class BackgroundJobsWorker {
         workerId: entry.payload.workerId || this.workerId
       })
       if (entry.resolve) entry.resolve(undefined)
-    }))
+    })
+
+    // Start every fallback report before announcing capacity so the main cannot
+    // observe a replacement slot before the failed jobs' reports are in flight.
+    // The report promises remain tracked below; a slow retry must not hold the
+    // newly freed runner capacity hostage.
+    if (state && state.started !== false) {
+      this._sendReadyIfRunning()
+    } else if (state) {
+      for (const entry of entries) {
+        if (entry.pooledJob) this._pooledStartupFailureJobs.add(entry.pooledJob)
+      }
+      // A previous ready message may still have unconsumed pooled credits at the
+      // main. Revoke them authoritatively without suppressing valid inline or
+      // process-runner readiness; otherwise queued jobs can trigger a startup
+      // crash loop using the stale credits.
+      this._sendReadyIfRunning({revokePooledAdmission: true})
+    }
+
+    await Promise.allSettled(failureReports)
   }
 
   /**

package/build/database/drivers/base.js

@@ -908,6 +908,25 @@ export default class VelociousDatabaseDriversBase {
     throw new Error("'type' not implemented")
   }
 
+  /**
+   * Whether this driver can combine unrelated alter-table operations into a
+   * single `ALTER TABLE` statement (Rails' `supports_bulk_alter`).
+   * @returns {boolean} - Whether bulk alter is supported.
+   */
+  supportsBulkAlter() {
+    return false
+  }
+
+  /**
+   * Whether a bulk `ALTER TABLE` statement can also carry `ADD INDEX` clauses.
+   * Only drivers that support this keep index adds inside the combined batch;
+   * the rest execute each index as its own statement.
+   * @returns {boolean} - Whether indexes can be added inside a bulk alter.
+   */
+  supportsBulkAlterIndexes() {
+    return false
+  }
+
   /**
    * Runs insert.
    * @param {InsertSqlArgsType} args - Options object.

package/build/database/drivers/mysql/index.js

@@ -345,6 +345,18 @@ export default class VelociousDatabaseDriversMysql extends Base{
    */
   getType() { return "mysql" }
 
+  /**
+   * Whether this driver supports combining operations into one bulk `ALTER`.
+   * @returns {boolean} - Whether bulk alter is supported.
+   */
+  supportsBulkAlter() { return true }
+
+  /**
+   * Whether the bulk `ALTER` can also carry `ADD INDEX` clauses.
+   * @returns {boolean} - Whether indexes can be added inside a bulk alter.
+   */
+  supportsBulkAlterIndexes() { return true }
+
   /**
    * Runs retryable database error.
    * @param {Error} error - Error instance.

package/build/database/drivers/mysql/sql/alter-table.js

@@ -26,13 +26,25 @@ export default class VelociousDatabaseConnectionDriversMysqlSqlAlterTable extend
     const indexes = this.tableData.getIndexes()
 
     if (indexes.length === 0) return sqls
-    if (sqls.length !== 1) throw new Error("Expected one MySQL ALTER TABLE statement when adding indexes")
+    if (sqls.length > 1) throw new Error("Expected one MySQL ALTER TABLE statement when adding indexes")
 
     const options = this.getOptions()
     let sql = sqls[0]
+    let needsIndexSeparator = true
+
+    if (sql === undefined) {
+      sql = `ALTER TABLE ${options.quoteTableName(this.tableData.getName())} `
+      needsIndexSeparator = false
+    }
 
     for (const index of indexes) {
-      sql += ", ADD"
+      if (needsIndexSeparator) {
+        sql += ", "
+      } else {
+        needsIndexSeparator = true
+      }
+
+      sql += "ADD"
 
       if (index.getUnique()) sql += " UNIQUE"
 

package/build/database/drivers/pgsql/index.js

@@ -203,6 +203,19 @@ export default class VelociousDatabaseDriversPgsql extends Base{
 
   getType() { return "pgsql" }
 
+  /**
+   * Whether this driver supports combining operations into one bulk `ALTER`.
+   * @returns {boolean} - Whether bulk alter is supported.
+   */
+  supportsBulkAlter() { return true }
+
+  /**
+   * Whether the bulk `ALTER` can also carry `ADD INDEX` clauses. PostgreSQL's
+   * `ALTER TABLE` cannot express index creation, so indexes stay standalone.
+   * @returns {boolean} - Whether indexes can be added inside a bulk alter.
+   */
+  supportsBulkAlterIndexes() { return false }
+
   /**
    * Runs query actual.
    * @param {string} sql - SQL string.

package/build/database/migration/change-table.js

@@ -0,0 +1,324 @@
+// @ts-check
+
+/**
+ * ChangeTableAddIndexArgsType type.
+ * @typedef {object} ChangeTableAddIndexArgsType
+ * @property {boolean} [ifNotExists] - Skip creation if the index already exists.
+ * @property {string} [name] - Explicit index name to use.
+ * @property {boolean} [unique] - Whether the index should be unique.
+ */
+
+/**
+ * ChangeTableRemoveIndexArgsType type.
+ * @typedef {object} ChangeTableRemoveIndexArgsType
+ * @property {string} [name] - Explicit index name to remove.
+ */
+
+/**
+ * ChangeTableRemoveReferenceArgsType type.
+ * @typedef {object} ChangeTableRemoveReferenceArgsType
+ * @property {string} [columnName] - Override the derived reference column name.
+ * @property {string} [indexName] - Explicit generated index name to remove.
+ */
+
+/**
+ * ChangeTableAddColumnOperationType type.
+ * @typedef {object} ChangeTableAddColumnOperationType
+ * @property {"addColumn"} type - Operation type.
+ * @property {string} columnName - Column name.
+ * @property {string} columnType - Column type.
+ * @property {import("../table-data/table-column.js").TableColumnArgsType | undefined} args - Column args.
+ */
+
+/**
+ * ChangeTableRemoveColumnOperationType type.
+ * @typedef {object} ChangeTableRemoveColumnOperationType
+ * @property {"removeColumn"} type - Operation type.
+ * @property {string} columnName - Column name.
+ */
+
+/**
+ * ChangeTableAddIndexOperationType type.
+ * @typedef {object} ChangeTableAddIndexOperationType
+ * @property {"addIndex"} type - Operation type.
+ * @property {Array<string | import("../table-data/table-column.js").default>} columns - Columns to index.
+ * @property {ChangeTableAddIndexArgsType | undefined} args - Index args.
+ */
+
+/**
+ * ChangeTableRemoveIndexOperationType type.
+ * @typedef {object} ChangeTableRemoveIndexOperationType
+ * @property {"removeIndex"} type - Operation type.
+ * @property {string | Array<string | import("../table-data/table-column.js").default>} nameOrColumns - Index name or columns.
+ * @property {ChangeTableRemoveIndexArgsType | undefined} args - Index args.
+ */
+
+/**
+ * ChangeTableAddReferenceOperationType type.
+ * @typedef {object} ChangeTableAddReferenceOperationType
+ * @property {"addReference"} type - Operation type.
+ * @property {string} referenceName - Reference name.
+ * @property {object | undefined} args - Reference args.
+ */
+
+/**
+ * ChangeTableRemoveReferenceOperationType type.
+ * @typedef {object} ChangeTableRemoveReferenceOperationType
+ * @property {"removeReference"} type - Operation type.
+ * @property {string} referenceName - Reference name.
+ * @property {ChangeTableRemoveReferenceArgsType | undefined} args - Reference args.
+ */
+
+/**
+ * ChangeTableRenameColumnOperationType type.
+ * @typedef {object} ChangeTableRenameColumnOperationType
+ * @property {"renameColumn"} type - Operation type.
+ * @property {string} oldColumnName - Previous column name.
+ * @property {string} newColumnName - New column name.
+ */
+
+/**
+ * ChangeTableChangeColumnNullOperationType type.
+ * @typedef {object} ChangeTableChangeColumnNullOperationType
+ * @property {"changeColumnNull"} type - Operation type.
+ * @property {string} columnName - Column name.
+ * @property {boolean} nullable - Whether the column becomes nullable.
+ */
+
+/**
+ * ChangeTableOperationType type.
+ * @typedef {ChangeTableAddColumnOperationType | ChangeTableRemoveColumnOperationType | ChangeTableAddIndexOperationType | ChangeTableRemoveIndexOperationType | ChangeTableAddReferenceOperationType | ChangeTableRemoveReferenceOperationType | ChangeTableRenameColumnOperationType | ChangeTableChangeColumnNullOperationType} ChangeTableOperationType
+ */
+
+/**
+ * Table-scoped recorder used by `migration.changeTable`. Each call records a
+ * single DDL operation synchronously; `changeTable` replays them after the
+ * callback completes so a failed callback executes zero recorded DDL.
+ */
+export default class VelociousDatabaseMigrationChangeTable {
+  /**
+   * Operations.
+   * @type {ChangeTableOperationType[]} */
+  _operations = []
+
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {string} args.tableName - Table name.
+   */
+  constructor({tableName}) {
+    if (!tableName) throw new Error(`Invalid table name: ${tableName}`)
+
+    this._tableName = tableName
+  }
+
+  /**
+   * Runs get table name.
+   * @returns {string} - The table name.
+   */
+  getTableName() { return this._tableName }
+
+  /**
+   * Runs get operations.
+   * @returns {ChangeTableOperationType[]} - The recorded operations.
+   */
+  getOperations() { return this._operations }
+
+  /**
+   * Records a new column.
+   * @param {string} name - Column name.
+   * @param {string} type - Column type.
+   * @param {import("../table-data/table-column.js").TableColumnArgsType} [args] - Options object.
+   * @returns {void} - No return value.
+   */
+  column(name, type, args) {
+    this._operations.push({type: "addColumn", columnName: name, columnType: type, args})
+  }
+
+  /**
+   * Records a bigint column.
+   * @param {string} name - Column name.
+   * @param {import("../table-data/table-column.js").TableColumnArgsType} [args] - Options object.
+   * @returns {void} - No return value.
+   */
+  bigint(name, args) { this.column(name, "bigint", args) }
+
+  /**
+   * Records a blob column.
+   * @param {string} name - Column name.
+   * @param {import("../table-data/table-column.js").TableColumnArgsType} [args] - Options object.
+   * @returns {void} - No return value.
+   */
+  blob(name, args) { this.column(name, "blob", args) }
+
+  /**
+   * Records a boolean column.
+   * @param {string} name - Column name.
+   * @param {import("../table-data/table-column.js").TableColumnArgsType} [args] - Options object.
+   * @returns {void} - No return value.
+   */
+  boolean(name, args) { this.column(name, "boolean", args) }
+
+  /**
+   * Records a datetime column.
+   * @param {string} name - Column name.
+   * @param {import("../table-data/table-column.js").TableColumnArgsType} [args] - Options object.
+   * @returns {void} - No return value.
+   */
+  datetime(name, args) { this.column(name, "datetime", args) }
+
+  /**
+   * Records a decimal column.
+   * @param {string} name - Column name.
+   * @param {import("../table-data/table-column.js").TableColumnArgsType} [args] - Options object.
+   * @returns {void} - No return value.
+   */
+  decimal(name, args) { this.column(name, "decimal", args) }
+
+  /**
+   * Records an integer column.
+   * @param {string} name - Column name.
+   * @param {import("../table-data/table-column.js").TableColumnArgsType} [args] - Options object.
+   * @returns {void} - No return value.
+   */
+  integer(name, args) { this.column(name, "integer", args) }
+
+  /**
+   * Records a json column.
+   * @param {string} name - Column name.
+   * @param {import("../table-data/table-column.js").TableColumnArgsType} [args] - Options object.
+   * @returns {void} - No return value.
+   */
+  json(name, args) { this.column(name, "json", args) }
+
+  /**
+   * Records a string column.
+   * @param {string} name - Column name.
+   * @param {import("../table-data/table-column.js").TableColumnArgsType} [args] - Options object.
+   * @returns {void} - No return value.
+   */
+  string(name, args) { this.column(name, "string", args) }
+
+  /**
+   * Records a text column.
+   * @param {string} name - Column name.
+   * @param {import("../table-data/table-column.js").TableColumnArgsType} [args] - Options object.
+   * @returns {void} - No return value.
+   */
+  text(name, args) { this.column(name, "text", args) }
+
+  /**
+   * Records a tinyint column.
+   * @param {string} name - Column name.
+   * @param {import("../table-data/table-column.js").TableColumnArgsType} [args] - Options object.
+   * @returns {void} - No return value.
+   */
+  tinyint(name, args) { this.column(name, "tinyint", args) }
+
+  /**
+   * Records a uuid column.
+   * @param {string} name - Column name.
+   * @param {import("../table-data/table-column.js").TableColumnArgsType} [args] - Options object.
+   * @returns {void} - No return value.
+   */
+  uuid(name, args) { this.column(name, "uuid", args) }
+
+  /**
+   * Records created_at and updated_at datetime columns.
+   * @param {import("../table-data/table-column.js").TableColumnArgsType} [args] - Options object.
+   * @returns {void} - No return value.
+   */
+  timestamps(args) {
+    this.datetime("created_at", args)
+    this.datetime("updated_at", args)
+  }
+
+  /**
+   * Records a new index.
+   * @param {string | Array<string | import("../table-data/table-column.js").default>} columns - Column name or array of column names.
+   * @param {ChangeTableAddIndexArgsType} [args] - Options object.
+   * @returns {void} - No return value.
+   */
+  index(columns, args) {
+    const normalizedColumns = typeof columns == "string" ? [columns] : columns
+
+    this._operations.push({type: "addIndex", columns: normalizedColumns, args})
+  }
+
+  /**
+   * Records a reference column, index, and optional foreign key.
+   * @param {string} name - Reference name.
+   * @param {object} [args] - Options object.
+   * @returns {void} - No return value.
+   */
+  references(name, args) {
+    this._operations.push({type: "addReference", referenceName: name, args})
+  }
+
+  /**
+   * Alias for {@link references}.
+   * @param {string} name - Reference name.
+   * @param {object} [args] - Options object.
+   * @returns {void} - No return value.
+   */
+  belongsTo(name, args) { this.references(name, args) }
+
+  /**
+   * Records removal of one or more columns.
+   * @param {string[]} columnNames - Column names to remove.
+   * @returns {void} - No return value.
+   */
+  remove(...columnNames) {
+    for (const columnName of columnNames) {
+      this._operations.push({type: "removeColumn", columnName})
+    }
+  }
+
+  /**
+   * Records removal of an index.
+   * @param {string | Array<string | import("../table-data/table-column.js").default>} nameOrColumns - Index name or columns.
+   * @param {ChangeTableRemoveIndexArgsType} [args] - Options object.
+   * @returns {void} - No return value.
+   */
+  removeIndex(nameOrColumns, args) {
+    this._operations.push({type: "removeIndex", nameOrColumns, args})
+  }
+
+  /**
+   * Records removal of a reference column and its generated index and foreign keys.
+   * @param {string} name - Reference name.
+   * @param {ChangeTableRemoveReferenceArgsType} [args] - Options object.
+   * @returns {void} - No return value.
+   */
+  removeReferences(name, args) {
+    this._operations.push({type: "removeReference", referenceName: name, args})
+  }
+
+  /**
+   * Records removal of the created_at and updated_at columns.
+   * @returns {void} - No return value.
+   */
+  removeTimestamps() {
+    this.remove("created_at", "updated_at")
+  }
+
+  /**
+   * Records a column rename.
+   * @param {string} oldColumnName - Previous column name.
+   * @param {string} newColumnName - New column name.
+   * @returns {void} - No return value.
+   */
+  rename(oldColumnName, newColumnName) {
+    this._operations.push({type: "renameColumn", oldColumnName, newColumnName})
+  }
+
+  /**
+   * Records a change to a column's nullability.
+   * @param {string} columnName - Column name.
+   * @param {boolean} nullable - Whether the column becomes nullable.
+   * @returns {void} - No return value.
+   */
+  changeNull(columnName, nullable) {
+    this._operations.push({type: "changeColumnNull", columnName, nullable})
+  }
+}