@zerotal/orm 1.7.3 → 1.7.5

package/CHANGELOG.md

@@ -8,6 +8,29 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.7.4] — 2026-08-21
+
+### Fixed
+
+- **A string column could not carry an index on MySQL.** `table.string()` compiled to `TEXT`
+  on every engine and discarded its `length` argument — the parameter existed and was
+  documented as "accepted for multi-DB compatibility", wired to nothing. MySQL refuses to key
+  a TEXT column without a prefix length, so `table.string("email").unique()` failed at
+  `CREATE TABLE`:
+
+  ```text
+  BLOB/TEXT column 'email' used in key specification without a key length
+  ```
+
+  Any natural key — an email, a slug — was unusable on MySQL, and `index()` the same. The
+  storage type now comes from the dialect, beside `booleanType` and `autoIncrementColumn`:
+  MySQL gets `VARCHAR(length)`, while SQLite and PostgreSQL keep `TEXT`, which PostgreSQL
+  indexes happily. `char()` had the identical bug and the identical fix.
+
+  Found by the new MySQL smoke suite on its first run against a real server.
+
+## [1.7.3] — 2026-08-20
+
 ### Fixed
 
 - **A boolean column could not hold a boolean on PostgreSQL.** `table.boolean()` compiled to
@@ -19,6 +42,10 @@ follows the Zerotal monorepo's unified versioning.
   tables keep their integer columns until a migration alters them. Found by the new smoke suite
   that runs the ORM against a real PostgreSQL in CI.
 
+## [1.7.2] — 2026-08-18
+
+### Fixed
+
 - **A seeder that failed partway left its rows behind.** `Seeder.call()` has always wrapped
   _composed_ seeders in a transaction, so a `DatabaseSeeder` that delegates was atomic and one that
   does its work inline — which is most of them — was not. A failure on the fourth table committed
@@ -31,8 +58,6 @@ follows the Zerotal monorepo's unified versioning.
   no connection is bound, because a seeder is not obliged to touch the database and an app that has
   not configured one should not fail to seed over a transaction it never needed.
 
-### Fixed
-
 - **`DatabaseProvider` now runs in `worker`, so `zt queue:work` can boot.** It did not, and the
   consequence was total rather than partial: `QueueProvider` _does_ run in `worker`, the
   queue's own default driver is `sqlite`, and so the worker asked for a connection this
@@ -51,6 +76,10 @@ follows the Zerotal monorepo's unified versioning.
 
   Found building the first cookbook app, whose first queued job could not run.
 
+## [1.7.1] — 2026-08-16
+
+### Fixed
+
 - **Relation keys now accept the JS spelling, like every other identifier.** The convention is
   camelCase in the application and snake_case in the database, converted on the way through —
   and relation keys were the one place it did not happen. `@hasMany(() => Issue, { foreignKey:

package/api-surface.md

@@ -116,7 +116,7 @@ class Blueprint = {
   bigInteger: (name: string) => ColumnBuilder
   binary: (name: string) => ColumnBuilder
   boolean: (name: string) => ColumnBuilder
-  char: (name: string, _length?: number) => ColumnBuilder
+  char: (name: string, length?: number) => ColumnBuilder
   date: (name: string) => ColumnBuilder
   dateTime: (name: string) => ColumnBuilder
   datetime: (name: string) => ColumnBuilder
@@ -153,7 +153,7 @@ class Blueprint = {
   smallInteger: (name: string) => ColumnBuilder
   softDeletes: (column?: string) => void
   spatialIndex: (columns: string | string[], name?: string) => Blueprint
-  string: (name: string, _length?: number) => ColumnBuilder
+  string: (name: string, length?: number) => ColumnBuilder
   text: (name: string) => ColumnBuilder
   time: (name: string) => ColumnBuilder
   timestamp: (name: string) => ColumnBuilder
@@ -182,7 +182,7 @@ class Cast = {
 }
 
 class ColumnBuilder = {
-  new <Locked extends string = never>(name: string, _sqlType: string, isPrimary?: boolean, isAutoIncrement?: boolean, _isBoolean?: boolean): ColumnBuilder<Locked>
+  new <Locked extends string = never>(name: string, _sqlType: string, isPrimary?: boolean, isAutoIncrement?: boolean, _isBoolean?: boolean, _stringLength?: number | undefined): ColumnBuilder<Locked>
   after: (_column: string) => ColumnBuilder<Locked>
   alter: () => ColumnBuilder<Locked>
   before: (_column: string) => ColumnBuilder<Locked>
@@ -277,13 +277,6 @@ class ForeignKeyBuilder = {
   toConstraintSQL: () => string
 }
 
-class HookRegistry = {
-  new (): HookRegistry
-  static onAfterRun: ((ModelClass: ClassRef, hook: HookName, model: unknown) => void) | undefined
-  static register: <T>(ModelClass: ClassRef, hook: HookName, fn: HookFn<T>) => void
-  static run: <T>(ModelClass: ClassRef, hook: HookName, model: T) => Promise<void>
-}
-
 class JsonCast = {
   new <T = unknown>(mapper?: CastMapper<T> | undefined): JsonCast<T>
   fields: () => CastField[]
@@ -574,6 +567,7 @@ class MysqlDialect = {
   readonly name: 'mysql'
   readonly supportsAdvisoryLocks: true
   readonly supportsTransactionalDdl: false
+  stringType: (length: number) => string
 }
 
 class NPlusOneDetected = {
@@ -615,6 +609,7 @@ class PostgresDialect = {
   readonly name: 'postgres'
   readonly supportsAdvisoryLocks: true
   readonly supportsTransactionalDdl: true
+  stringType: () => string
 }
 
 class QueryBuilder = {
@@ -754,6 +749,7 @@ class SqliteDialect = {
   readonly name: 'sqlite'
   readonly supportsAdvisoryLocks: false
   readonly supportsTransactionalDdl: true
+  stringType: () => string
 }
 
 class StateError = {
@@ -798,14 +794,10 @@ class UnsupportedDialectError = {
   readonly status: number
 }
 
-const columnRegistry = Map<ClassRef, Map<string, ColumnOptions>>
-
 const DB = {    table(tableName: string): QueryBuilder;    raw<T = Record<string, unknown>>(sql: TemplateStringsArray | string, ...rest: unknown[]): Promise<T[]>;    transaction<T>(callback: (tx?: SQLInstance) => Promise<T>, attempts?: number): Promise<T>;    beginTransaction(): Promise<ManualTransaction>;    onPrimary(): {        table(name: string): QueryBuilder;    };    currentTx(): unknown | undefined;    advisoryLock<T>(key: number, callback: () => Promise<T>): Promise<T>;    preventNPlusOne(options?: NPlusOneOptions): void;    allowNPlusOne(pattern: string, options?: {        once?: boolean;    }): void;}
 
 const ModelInspector = {    load(pattern: string, cwd?: string): Promise<void>;    all(): ModelSchema[];    fromClass(ctor: ClassRef): ModelSchema | null;}
 
-const modelsByName = Map<string, ClassRef>
-
 const relationRegistry = Map<ClassRef, Map<string, RelationMetadata>>
 
 const Schema = {    create(table: string, callback: (bp: Blueprint) => void): Promise<void>;    createIfNotExists(table: string, callback: (bp: Blueprint) => void): Promise<void>;    table(name: string, callback: (bp: Blueprint) => void): Promise<void>;    alter(name: string, callback: (bp: Blueprint) => void): Promise<void>;    drop(table: string): Promise<void>;    dropIfExists(table: string): Promise<void>;    rename(from: string, to: string): Promise<void>;    hasTable(table: string): Promise<boolean>;    hasColumn(table: string, column: string): Promise<boolean>;}
@@ -816,32 +808,14 @@ const SchemaInspector = {    tables(): Promise<string[]>;    columns(table: stri
 
 const TransactionContext = AsyncLocalStorage<SQLInstance>
 
-function _clearModelConnections = () => void
-
-function _clearTransitionCallbacks = () => void
-
 function _getConnection = () => SQLInstance
 
 function _getDbConnectionOverride = () => SQLInstance | null
 
-function _getDialect = () => 'sqlite' | 'postgres' | 'mysql'
-
-function _getModelConnection = () => SQLInstance
-
 function _globalScopeRegistry = () => Map<ClassRef, Map<string, GlobalScopeCallback>>
 
-function _normaliseSqliteUrl = (raw: string) => string
-
-function _resolveConn = (ModelClass?: typeof BaseModel) => SQLInstance
-
-function _setBaseModelConnection = (conn: SQLInstance | null) => void
-
-function _setBaseModelDialect = (dialect: 'sqlite' | 'postgres' | 'mysql') => void
-
 function _setDbConnection = (conn: SQLInstance | null) => void
 
-function _setQueryBuilderDialect = (d: Dialect) => void
-
 function _setReadReplicas = (primary: SQLInstance, replicas: SQLInstance[]) => void
 
 function _suppressHooks = <T>(fn: () => Promise<T>) => Promise<T>
@@ -854,8 +828,6 @@ function belongsTo = (related: () => unknown, options: BelongsToOptions) => (_va
 
 function column = {    (): ColumnDecorator;    (type: ColumnShorthand): ColumnDecorator;    (options: ColumnOptions): ColumnDecorator;    (type: ColumnShorthand, options: Omit<ColumnOptions, 'type'>): ColumnDecorator;}
 
-function columnsFor = (ctor: ClassRef) => Map<string, ColumnOptions> | null
-
 function createReadWriteRouter = (primary: SQLInstance, replicas: SQLInstance[]) => SQLInstance
 
 function currentOrmContext = () => OrmContext
@@ -882,10 +854,6 @@ function json = <T = unknown>(mapper?: CastMapper<T>) => JsonCast<T>
 
 function manyToMany = (related: () => unknown, options: ManyToManyOptions) => (_value: unknown, context: ClassFieldDecoratorContext) => void
 
-function modelByName = (name: string) => ClassRef | undefined
-
-function modelForParam = (paramName: string) => ImplicitModel | undefined
-
 function morphedByMany = (related: () => unknown, options: MorphedByManyOptions) => (_value: unknown, context: ClassFieldDecoratorContext) => void
 
 function morphMany = (related: () => unknown, options: MorphManyOptions) => (_value: unknown, context: ClassFieldDecoratorContext) => void
@@ -900,14 +868,10 @@ function objectOf = <T = unknown>(mapper?: CastMapper<T>) => JsonCast<T>
 
 function preventNPlusOne = (options?: NPlusOneOptions) => void
 
-function registerColumn = (ctor: ClassRef, name: string, options: ColumnOptions) => void
-
 function registerConnectionResolver = (fn: ContextConnectionResolver | null) => void
 
 function registerImplicitBinding = () => void
 
-function registerModel = (ctor: ClassRef) => void
-
 function registerModelConnection = (name: string, conn: SQLInstance, dialect?: Dialect) => void
 
 function resetOrmContext = () => void
@@ -1203,21 +1167,6 @@ interface PaginateResult = {
   url: (page: number, baseUrl?: string, query?: Record<string, string>) => string
 }
 
-interface QueryState = {
-  distinct: boolean
-  groupBys: string[]
-  havings: HavingClause[]
-  joins: JoinClause[]
-  limit: number | undefined
-  lock: string | undefined
-  offset: number | undefined
-  orders: OrderClause[]
-  selects: string[]
-  table: string
-  unions: UnionClause[]
-  wheres: WhereClause[]
-}
-
 interface RelationMetadata = {
   firstKey?: string
   foreignKey: string
@@ -1274,6 +1223,7 @@ interface SqlDialect = {
   readonly name: DialectName
   readonly supportsAdvisoryLocks: boolean
   readonly supportsTransactionalDdl: boolean
+  stringType: (length: number) => string
 }
 
 interface SQLInstance = {
@@ -1311,17 +1261,15 @@ interface TransitionContext = {
 
 type CastMapper = ((raw: unknown) => T) | (new (...args: never[]) => T)
 
-type ClassRef = abstract new (...args: never[]) => unknown
-
 type Columns = { [K in keyof T & string]: K extends `_${string}` ? never : T[K] extends (...args: any[]) => any ? never : K; }[keyof T & string]
 
-type ColumnShorthand = 'string' | 'number' | 'boolean' | 'text' | 'date' | 'datetime' | 'array' | 'integer' | 'json' | 'float' | 'encrypted' | 'encrypted:json'
+type ColumnShorthand = 'string' | 'text' | 'integer' | 'number' | 'float' | 'boolean' | 'datetime' | 'date' | 'json' | 'array' | 'encrypted' | 'encrypted:json'
 
 type Constructor = new (...args: any[]) => T
 
 type ContextConnectionResolver = (ModelClass?: typeof BaseModel) => SQLInstance | null
 
-type DatePart = 'date' | 'time' | 'year' | 'month' | 'day'
+type DatePart = 'date' | 'time' | 'day' | 'month' | 'year'
 
 type DialectName = 'sqlite' | 'postgres' | 'mysql'
 

package/package.json

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

package/src/config.ts

@@ -19,11 +19,14 @@ export interface DatabaseConfigShape {
    * mutating queries (INSERT, UPDATE, DELETE, DDL) plus transactions to the
    * primary. No code changes are required in controllers or models.
    *
+   * `env()` with no fallback is `string | undefined`, so an unset replica has to
+   * drop out rather than widen the array — this field is `string[]`.
+   *
    * @example
    * replicas: [
    *   env('REPLICA_1_URL'),
    *   env('REPLICA_2_URL'),
-   * ]
+   * ].filter((url) => url !== undefined)
    */
   replicas?: string[];
   /**

package/src/db/dialects/MysqlDialect.ts

@@ -58,6 +58,12 @@ export class MysqlDialect implements SqlDialect {
     return value ? "1" : "0";
   }
 
+  // VARCHAR so the column can carry an index or a unique constraint; MySQL
+  // refuses to key a TEXT column without a prefix length.
+  stringType(length: number): string {
+    return `VARCHAR(${length})`;
+  }
+
   advisoryLockSql(key: number): DialectQuery {
     return { sql: `SELECT GET_LOCK(?, -1)`, params: [`zerotal_lock_${key}`] };
   }

package/src/db/dialects/PostgresDialect.ts

@@ -54,6 +54,11 @@ export class PostgresDialect implements SqlDialect {
     return value ? "TRUE" : "FALSE";
   }
 
+  // PostgreSQL indexes TEXT without a key length, so the portable type stands.
+  stringType(): string {
+    return "TEXT";
+  }
+
   advisoryLockSql(key: number): DialectQuery {
     return { sql: `SELECT pg_advisory_lock(?)`, params: [key] };
   }

package/src/db/dialects/SqliteDialect.ts

@@ -55,6 +55,11 @@ export class SqliteDialect implements SqlDialect {
     return value ? "1" : "0";
   }
 
+  // SQLite has one string type and no length to honour.
+  stringType(): string {
+    return "TEXT";
+  }
+
   advisoryLockSql(): DialectQuery | null {
     return null;
   }

package/src/db/dialects/types.ts

@@ -76,6 +76,22 @@ export interface SqlDialect {
   /** A boolean as this engine spells it in a `DEFAULT` clause. */
   booleanLiteral(value: boolean): string;
 
+  /**
+   * The column type a portable `table.string(name, length)` compiles to.
+   *
+   * SQLite has one string type and ignores the length, so the Blueprint emitted
+   * `TEXT` for every engine and threw the length away. MySQL cannot index a TEXT
+   * column without a key length, so `table.string("name").unique()` — an email, a
+   * slug, any natural key — failed at `CREATE TABLE`:
+   *
+   *     BLOB/TEXT column 'name' used in key specification without a key length
+   *
+   * The length was already in the signature and already documented as accepted;
+   * it just had nowhere to go. PostgreSQL keeps `TEXT`, which it indexes happily
+   * and which is the idiomatic choice there.
+   */
+  stringType(length: number): string;
+
   /** Whether the engine supports application-level advisory locks. */
   readonly supportsAdvisoryLocks: boolean;
 

package/src/schema/Blueprint.ts

@@ -202,19 +202,21 @@ export class Blueprint {
   /**
    * Variable-length string column (`VARCHAR`-style), stored as `TEXT`.
    * @param name - Column name.
-   * @param _length - Max length; accepted for multi-DB compatibility but ignored on SQLite.
+   * @param length - Max length. Ignored on SQLite and PostgreSQL, which have one
+   *   string type; on MySQL it becomes `VARCHAR(length)`, which is what lets the
+   *   column carry an index or a unique constraint.
    * @category Column types
    */
-  string(name: string, _length = 255): ColumnBuilder {
-    return this._add(new ColumnBuilder(name, "TEXT"));
+  string(name: string, length = 255): ColumnBuilder {
+    return this._add(new ColumnBuilder(name, "TEXT", false, false, false, length));
   }
 
   /**
    * Fixed-length `CHAR` column. Stored as `TEXT` on SQLite; `_length` is ignored.
    * @category Column types
    */
-  char(name: string, _length = 255): ColumnBuilder {
-    return this._add(new ColumnBuilder(name, "TEXT"));
+  char(name: string, length = 255): ColumnBuilder {
+    return this._add(new ColumnBuilder(name, "TEXT", false, false, false, length));
   }
 
   /**

package/src/schema/ColumnDefinition.ts

@@ -69,6 +69,11 @@ export class ColumnBuilder<Locked extends string = never> {
      * storage type at compile time — see {@link SqlDialect.booleanType}.
      */
     private _isBoolean = false,
+    /**
+     * Declared max length for a portable string column. The engine decides
+     * whether it matters — see {@link SqlDialect.stringType}.
+     */
+    private _stringLength?: number,
   ) {
     this._isPrimary = isPrimary;
     this._isAutoIncr = isAutoIncrement;
@@ -329,9 +334,15 @@ export class ColumnBuilder<Locked extends string = never> {
     // PostgreSQL a syntax error and against MySQL a 1064.
     if (this._isAutoIncr) return getDialect(dialect).autoIncrementColumn(this.name);
 
-    // A boolean's storage type is the engine's to choose: SQLite stores 0/1 in an
-    // INTEGER, PostgreSQL has a real one and rejects the integer form outright.
-    const sqlType = this._isBoolean ? getDialect(dialect).booleanType : this._sqlType;
+    // Storage type is the engine's to choose wherever the engines disagree:
+    // SQLite keeps 0/1 in an INTEGER where PostgreSQL has a real boolean, and
+    // MySQL needs a VARCHAR length before it will index a string at all.
+    const d = getDialect(dialect);
+    const sqlType = this._isBoolean
+      ? d.booleanType
+      : this._stringLength !== undefined
+        ? d.stringType(this._stringLength)
+        : this._sqlType;
     const parts: string[] = [`${this.name} ${sqlType}`];
 
     if (this._isPrimary) parts.push("PRIMARY KEY");