@zhin.js/database 1.1.2 → 1.1.4

package/README.md

@@ -108,6 +108,22 @@ await db.start();
 
 ### MySQL Example
 
+框架初始化验证基线为 **MySQL 8.4 LTS**，驱动为 `mysql2` 3.x。项目配置中的
+`database.dialect: mysql` 用于选择方言，由 CLI 移除后再把连接参数传给驱动。
+不要为了消除驱动警告而删除项目配置中的 `dialect`。
+
+MySQL 方言将 `text` 的非空默认值和 `json` 默认值写成表达式，例如
+`TEXT DEFAULT ('')`；普通 `TEXT DEFAULT ''` 会被 MySQL 拒绝。
+声明了 `length` 的 `text` 使用 `VARCHAR(length)`；未声明长度的文本主键或唯一键
+使用 `VARCHAR(768)`，以完整值建立索引；显式声明的索引文本长度超过 768 时直接报错。文本主键和唯一键使用 `utf8mb4_0900_bin`，保留大小写及末尾空格的区别。其余文本仍为 `TEXT`。
+新表显式使用 InnoDB `ROW_FORMAT=DYNAMIC`。使用 4KB / 8KB InnoDB 页时，启动会先校验文本索引长度，并提示配置更大的页或显式声明更短的键长度。
+键值应在该长度内；需要更短的业务边界时显式声明 `length`。这里没有使用文本前缀唯一索引，
+避免将前缀相同的不同键误判为重复。
+
+如果启动报 `message_key can't have a default value`，请升级包含此修复的
+`@zhin.js/database` 与 `@zhin.js/cli` 后重启。该错误来自建表 SQL，无需降级
+MySQL 或 mysql2，也无需删除已有数据库。修复针对新建表，不会缩窄既有文本列。
+
 ```typescript
 const db = Registry.create('mysql', {
   host: 'localhost',

package/lib/dialects/mysql.d.ts

@@ -64,4 +64,5 @@ export declare class MySQLDialect<S extends Record<string, object> = Record<stri
 }
 export declare class MySQL<S extends Record<string, object> = Record<string, object>> extends RelatedDatabase<MySQLDialectConfig, S> {
     constructor(config: MySQLDialectConfig, definitions?: Database.DefinitionObj<S>);
+    protected initialize(): Promise<void>;
 }

package/lib/dialects/mysql.js

@@ -187,20 +187,36 @@ export class MySQLDialect extends Dialect {
         return `LIMIT ${offset}, ${limit}`;
     }
     formatCreateTable(tableName, columns) {
-        return `CREATE TABLE IF NOT EXISTS ${this.quoteIdentifier(String(tableName))} (${columns.join(', ')}) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4`;
+        return `CREATE TABLE IF NOT EXISTS ${this.quoteIdentifier(String(tableName))} (${columns.join(', ')}) ENGINE=InnoDB ROW_FORMAT=DYNAMIC DEFAULT CHARSET=utf8mb4`;
     }
     formatColumnDefinition(field, column) {
         const name = this.quoteIdentifier(String(field));
-        const type = this.mapColumnType(column.type);
-        const length = column.length ? `(${column.length})` : '';
+        // TEXT cannot be indexed in full. Bounded keys retain full-value uniqueness
+        // within InnoDB's 3072-byte index limit under utf8mb4 (4 bytes per character).
+        const boundedText = column.type.toLowerCase() === 'text'
+            && (column.length !== undefined || column.primary || column.unique);
+        const indexedText = boundedText && (column.primary || column.unique);
+        if (boundedText && (!Number.isInteger(column.length ?? 768) || (column.length ?? 768) < 1)) {
+            throw new RangeError(`MySQL text column ${field} requires a positive integer length`);
+        }
+        if (indexedText && (column.length ?? 768) > 768) {
+            throw new RangeError(`MySQL indexed text column ${field} exceeds the utf8mb4 index limit of 768 characters`);
+        }
+        const collation = indexedText ? ' CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_bin' : '';
+        const type = boundedText ? 'VARCHAR' : this.mapColumnType(column.type);
+        const length = boundedText ? `(${column.length ?? 768})` : column.length ? `(${column.length})` : '';
         const nullable = column.nullable === false ? ' NOT NULL' : '';
         const primary = column.primary ? ' PRIMARY KEY' : '';
         const unique = column.unique ? ' UNIQUE' : '';
         const autoIncrement = column.autoIncrement ? ' AUTO_INCREMENT' : '';
-        const defaultVal = column.default !== undefined
-            ? ` DEFAULT ${this.formatDefaultValue(column.default)}`
-            : '';
-        return `${name} ${type}${length}${primary}${unique}${autoIncrement}${nullable}${defaultVal}`;
+        let defaultVal = '';
+        if (column.default !== undefined) {
+            const value = this.formatDefaultValue(column.default);
+            // MySQL 8.0.13+ requires even literal TEXT/JSON defaults to be expressions.
+            const expression = (type === 'TEXT' || type === 'JSON') && column.default !== null;
+            defaultVal = ` DEFAULT ${expression ? `(${value})` : value}`;
+        }
+        return `${name} ${type}${length}${collation}${primary}${unique}${autoIncrement}${nullable}${defaultVal}`;
     }
     async reconcileDefinitions(definitions) {
         const expected = new Map();
@@ -320,5 +336,20 @@ export class MySQL extends RelatedDatabase {
     constructor(config, definitions) {
         super(new MySQLDialect(config), definitions);
     }
+    async initialize() {
+        const indexedText = [...this.definitions.values()].flatMap(definition => Object.entries(definition).filter(([, column]) => column.type.toLowerCase() === 'text' && (column.primary || column.unique)));
+        if (indexedText.length) {
+            const [settings] = await this.dialect.query('SELECT @@innodb_page_size AS page_size');
+            const maxLength = Math.min(768, Number(settings?.page_size) * 3 / 64);
+            if (!Number.isFinite(maxLength) || maxLength < 1)
+                throw new Error('Cannot determine MySQL InnoDB text index limit');
+            for (const [name, column] of indexedText) {
+                if ((column.length ?? 768) > maxLength) {
+                    throw new RangeError(`MySQL indexed text column ${name} requires ${column.length ?? 768} characters, but innodb_page_size=${settings.page_size} allows ${maxLength}; use a 16KB-or-larger InnoDB page size or declare a smaller key length`);
+                }
+            }
+        }
+        await super.initialize();
+    }
 }
 Registry.register('mysql', MySQL);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/database",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "Universal database abstraction layer for Zhin.js - supports SQLite, MySQL, PostgreSQL, MongoDB, Redis",
   "type": "module",
   "main": "./lib/index.js",
@@ -9,18 +9,17 @@
     ".": {
       "types": "./lib/index.d.ts",
       "import": "./lib/index.js",
-      "require": "./lib/index.js",
-      "development": "./src/index.ts"
+      "require": "./lib/index.js"
     }
   },
   "files": [
     "lib"
   ],
   "engines": {
-    "node": ">=22.5.0"
+    "node": ">=22.19.0"
   },
   "dependencies": {
-    "@zhin.js/logger": "1.1.1"
+    "@zhin.js/logger": "1.1.2"
   },
   "peerDependencies": {
     "mongodb": ">=3.1.13",