@zhin.js/database 1.1.1 → 1.1.2

package/lib/base/dialect.d.ts

@@ -1,4 +1,4 @@
-import { Transaction, TransactionOptions, IsolationLevel } from '../types.js';
+import { Transaction, TransactionOptions, IsolationLevel, type Column, type Definition } from '../types.js';
 export declare abstract class Dialect<T, S extends Record<string, object>, Q> {
     readonly name: string;
     readonly config: T;
@@ -25,6 +25,10 @@ export declare abstract class Dialect<T, S extends Record<string, object>, Q> {
     abstract formatDropTable<T extends keyof S>(tableName: T, ifExists?: boolean): string;
     abstract formatDropIndex<T extends keyof S>(indexName: string, tableName: T, ifExists?: boolean): string;
     abstract dispose(): Promise<void>;
+    /** Format one column while preserving dialect-specific identity syntax. */
+    formatColumnDefinition(field: string, column: Column<any>): string;
+    /** Apply widening-only schema updates that CREATE TABLE IF NOT EXISTS cannot. */
+    reconcileDefinitions(_definitions: ReadonlyMap<keyof S, Definition<S[keyof S]>>): Promise<void>;
     /**
      * 是否支持事务
      */

package/lib/base/dialect.js

@@ -11,6 +11,22 @@ export class Dialect {
         this.name = name;
         this.config = config;
     }
+    /** Format one column while preserving dialect-specific identity syntax. */
+    formatColumnDefinition(field, column) {
+        const name = this.quoteIdentifier(field);
+        const type = this.mapColumnType(column.type);
+        const length = 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 ? ' AUTOINCREMENT' : '';
+        const defaultValue = column.default !== undefined
+            ? ` DEFAULT ${this.formatDefaultValue(column.default)}`
+            : '';
+        return `${name} ${type}${length}${primary}${unique}${autoIncrement}${nullable}${defaultValue}`;
+    }
+    /** Apply widening-only schema updates that CREATE TABLE IF NOT EXISTS cannot. */
+    async reconcileDefinitions(_definitions) { }
     // ============================================================================
     // Transaction Support (optional, default implementations)
     // ============================================================================

package/lib/dialects/memory.d.ts

@@ -1,4 +1,4 @@
-import { Dialect } from '../base/index.js';
+import { Database, Dialect } from '../base/index.js';
 import { RelatedDatabase } from "../type/related/database.js";
 export interface MemoryConfig {
 }
@@ -6,6 +6,7 @@ export declare class MemoryDialect<S extends Record<string, object>> extends Dia
     private connected;
     private tables;
     private autoIncrementCounters;
+    private declaredSchemas;
     constructor(config?: MemoryConfig);
     isConnected(): boolean;
     connect(): Promise<void>;
@@ -13,6 +14,7 @@ export declare class MemoryDialect<S extends Record<string, object>> extends Dia
     healthCheck(): Promise<boolean>;
     query<U = any>(sql: string, params?: any[]): Promise<U>;
     dispose(): Promise<void>;
+    registerTableSchema(table: string, definition: Record<string, any>): void;
     mapColumnType(type: string): string;
     quoteIdentifier(identifier: string | symbol | number): string;
     getParameterPlaceholder(index: number): string;
@@ -52,5 +54,5 @@ export declare class MemoryDialect<S extends Record<string, object>> extends Dia
     private applyOrderBy;
 }
 export declare class Memory<S extends Record<string, object>> extends RelatedDatabase<MemoryConfig, S> {
-    constructor(config?: MemoryConfig);
+    constructor(config?: MemoryConfig, definitions?: Database.DefinitionObj<S>);
 }

package/lib/dialects/memory.js

@@ -57,6 +57,7 @@ export class MemoryDialect extends Dialect {
     connected = false;
     tables = new Map();
     autoIncrementCounters = new Map();
+    declaredSchemas = new Map();
     constructor(config = {}) {
         super('memory', config);
     }
@@ -115,12 +116,16 @@ export class MemoryDialect extends Dialect {
     async dispose() {
         await this.disconnect();
     }
+    registerTableSchema(table, definition) {
+        this.declaredSchemas.set(table, structuredClone(definition));
+    }
     // SQL generation methods
     mapColumnType(type) {
         // 内存数据库不需要严格的类型映射，但保持一致性
         const typeMap = {
             'text': 'TEXT',
             'integer': 'INTEGER',
+            'bigint': 'INTEGER',
             'float': 'REAL',
             'boolean': 'BOOLEAN',
             'date': 'DATE',
@@ -202,12 +207,14 @@ export class MemoryDialect extends Dialect {
         const tableName = match[1];
         const columnsStr = match[2];
         // 解析列定义
-        const schema = {};
+        const schema = structuredClone(this.declaredSchemas.get(tableName) ?? {});
         const columnDefs = columnsStr.split(',').map(col => col.trim());
         for (const colDef of columnDefs) {
             const parts = colDef.split(/\s+/);
             const columnName = parts[0].replace(/"/g, '');
             const columnType = parts[1];
+            if (schema[columnName])
+                continue;
             schema[columnName] = {
                 type: columnType,
                 primary: colDef.toLowerCase().includes('primary key'),
@@ -820,8 +827,8 @@ export class MemoryDialect extends Dialect {
     }
 }
 export class Memory extends RelatedDatabase {
-    constructor(config = {}) {
-        super(new MemoryDialect(config));
+    constructor(config = {}, definitions) {
+        super(new MemoryDialect(config), definitions);
     }
 }
 Registry.register('memory', Memory);

package/lib/dialects/mongodb.d.ts

@@ -81,6 +81,7 @@ export declare class MongoDBDialect<S extends Record<string, object> = Record<st
     private executeCreateIndex;
     private executeDropIndex;
     private executeDropCollection;
+    private executeCreateCollection;
     get dialectInfo(): DatabaseDialect;
 }
 export declare class MongoDB<S extends Record<string, object> = Record<string, object>> extends DocumentDatabase<MongoDBDialectConfig, S> {

package/lib/dialects/mongodb.js

@@ -49,7 +49,8 @@ export class MongoDBDialect extends Dialect {
         try {
             // 动态导入 mongodb 客户端
             const { MongoClient } = await import('mongodb');
-            this.client = new MongoClient(this.config.url, this.config);
+            const { url, dbName: _dbName, ...clientOptions } = this.config;
+            this.client = new MongoClient(url, clientOptions);
             await this.client.connect();
             this.db = this.client.db(this.config.dbName);
         }
@@ -105,6 +106,8 @@ export class MongoDBDialect extends Dialect {
                     return await this.executeDropIndex(collection, query, params);
                 case 'dropCollection':
                     return await this.executeDropCollection(collection);
+                case 'createCollection':
+                    return await this.executeCreateCollection(query.collection);
                 default:
                     throw new Error(`不支持的 MongoDB 操作: ${query.operation}`);
             }
@@ -145,6 +148,8 @@ export class MongoDBDialect extends Dialect {
                 return 'String';
             case 'integer':
                 return 'Int32';
+            case 'bigint':
+                return 'Double';
             case 'float':
                 return 'Double';
             case 'boolean':
@@ -427,6 +432,20 @@ export class MongoDBDialect extends Dialect {
         const result = await collection.drop();
         return [{ result }];
     }
+    async executeCreateCollection(name) {
+        const existing = await this.db.listCollections({ name }, { nameOnly: true }).hasNext();
+        if (!existing) {
+            try {
+                await this.db.createCollection(name);
+            }
+            catch (error) {
+                const duplicate = error;
+                if (duplicate.code !== 48 && duplicate.codeName !== 'NamespaceExists')
+                    throw error;
+            }
+        }
+        return [];
+    }
     get dialectInfo() {
         return {
             name: this.name,
@@ -442,6 +461,7 @@ export class MongoDBDialect extends Dialect {
             dataTypes: {
                 'string': 'String',
                 'integer': 'Int32',
+                'bigint': 'Double',
                 'float': 'Double',
                 'boolean': 'Boolean',
                 'date': 'Date',

package/lib/dialects/mysql.d.ts

@@ -1,7 +1,7 @@
 import { Dialect, Database } from '../base/index.js';
 import { RelatedDatabase } from "../type/related/database.js";
 import type { ConnectionOptions } from 'mysql2/promise';
-import { Column, Transaction, TransactionOptions, PoolConfig } from "../types.js";
+import { Column, Transaction, TransactionOptions, PoolConfig, type Definition } from "../types.js";
 export interface MySQLDialectConfig extends ConnectionOptions {
     /**
      * 连接池配置
@@ -13,12 +13,18 @@ export declare class MySQLDialect<S extends Record<string, object> = Record<stri
     private connection;
     private pool;
     private usePool;
+    private readonly booleanColumns;
+    private readonly bigintColumns;
     constructor(config: MySQLDialectConfig);
     isConnected(): boolean;
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     healthCheck(): Promise<boolean>;
     query<U = any>(sql: string, params?: any[]): Promise<U>;
+    registerTableSchema(table: string, definition: Record<string, {
+        type: string;
+    }>): void;
+    private processQueryResults;
     dispose(): Promise<void>;
     /**
      * 获取连接池统计信息（仅在使用连接池时有效）
@@ -42,6 +48,7 @@ export declare class MySQLDialect<S extends Record<string, object> = Record<stri
     formatLimitOffset(limit: number, offset: number): string;
     formatCreateTable<T extends keyof S>(tableName: T, columns: string[]): string;
     formatColumnDefinition(field: string, column: Column<any>): string;
+    reconcileDefinitions(definitions: ReadonlyMap<keyof S, Definition<S[keyof S]>>): Promise<void>;
     formatAlterTable<T extends keyof S>(tableName: T, alterations: string[]): string;
     formatDropTable<T extends keyof S>(tableName: T, ifExists?: boolean): string;
     formatDropIndex<T extends keyof S>(indexName: string, tableName: T, ifExists?: boolean): string;

package/lib/dialects/mysql.js

@@ -7,6 +7,8 @@ export class MySQLDialect extends Dialect {
     connection = null;
     pool = null;
     usePool = false;
+    booleanColumns = new Set();
+    bigintColumns = new Set();
     constructor(config) {
         super('mysql', config);
         this.usePool = !!config.pool;
@@ -19,12 +21,13 @@ export class MySQLDialect extends Dialect {
         try {
             if (this.usePool) {
                 const { createPool } = await import('mysql2/promise');
+                const { pool, ...connectionOptions } = this.config;
                 const poolConfig = {
-                    ...this.config,
+                    ...connectionOptions,
                     waitForConnections: true,
-                    connectionLimit: this.config.pool?.max ?? 10,
+                    connectionLimit: pool?.max ?? 10,
                     queueLimit: 0,
-                    idleTimeout: this.config.pool?.idleTimeoutMillis ?? 60000,
+                    idleTimeout: pool?.idleTimeoutMillis ?? 60000,
                 };
                 this.pool = createPool(poolConfig);
                 logger.info(`MySQL 连接池已创建 (max: ${poolConfig.connectionLimit})`);
@@ -63,14 +66,48 @@ export class MySQLDialect extends Dialect {
     }
     async query(sql, params) {
         if (this.usePool) {
-            const [rows] = await this.pool.execute(sql, params);
-            return rows;
+            const [rows, fields] = await this.pool.execute(sql, params);
+            return this.processQueryResults(rows, fields);
         }
         else {
-            const [rows] = await this.connection.execute(sql, params);
-            return rows;
+            const [rows, fields] = await this.connection.execute(sql, params);
+            return this.processQueryResults(rows, fields);
         }
     }
+    registerTableSchema(table, definition) {
+        for (const [columnName, column] of Object.entries(definition)) {
+            if (column.type === 'boolean')
+                this.booleanColumns.add(`${table}.${columnName}`);
+            if (column.type === 'bigint')
+                this.bigintColumns.add(`${table}.${columnName}`);
+        }
+    }
+    processQueryResults(data, fields) {
+        if (!Array.isArray(data))
+            return data;
+        return data.map((row) => {
+            if (!row || typeof row !== 'object')
+                return row;
+            const normalized = { ...row };
+            for (const field of Array.isArray(fields) ? fields : []) {
+                const table = String(field.orgTable ?? field.table ?? '');
+                const column = String(field.orgName ?? field.name ?? '');
+                const outputName = String(field.name ?? column);
+                if (this.booleanColumns.has(`${table}.${column}`) &&
+                    typeof normalized[outputName] === 'number') {
+                    normalized[outputName] = normalized[outputName] !== 0;
+                }
+                if (this.bigintColumns.has(`${table}.${column}`) &&
+                    typeof normalized[outputName] === 'string' &&
+                    /^-?\d+$/u.test(normalized[outputName])) {
+                    const number = Number(normalized[outputName]);
+                    if (Number.isSafeInteger(number))
+                        normalized[outputName] = number;
+                }
+            }
+            return normalized;
+        });
+    }
     async dispose() {
         await this.disconnect();
     }
@@ -91,6 +128,7 @@ export class MySQLDialect extends Dialect {
         const typeMap = {
             'text': 'TEXT',
             'integer': 'INT',
+            'bigint': 'BIGINT',
             'float': 'FLOAT',
             'boolean': 'BOOLEAN',
             'date': 'DATETIME',
@@ -164,6 +202,39 @@ export class MySQLDialect extends Dialect {
             : '';
         return `${name} ${type}${length}${primary}${unique}${autoIncrement}${nullable}${defaultVal}`;
     }
+    async reconcileDefinitions(definitions) {
+        const expected = new Map();
+        for (const [tableName, definition] of definitions) {
+            for (const [columnName, column] of Object.entries(definition)) {
+                if (column.type === 'bigint' || column.autoIncrement) {
+                    expected.set(`${String(tableName)}\0${columnName}`, column);
+                }
+            }
+        }
+        if (expected.size === 0)
+            return;
+        const tableNames = [...new Set([...expected.keys()].map((key) => key.slice(0, key.indexOf('\0'))))];
+        const placeholders = tableNames.map(() => '?').join(', ');
+        const rows = await this.query(`SELECT TABLE_NAME AS table_name, COLUMN_NAME AS column_name, DATA_TYPE AS data_type, EXTRA AS extra
+       FROM INFORMATION_SCHEMA.COLUMNS
+       WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME IN (${placeholders})`, tableNames);
+        const narrowTypes = new Set(['tinyint', 'smallint', 'mediumint', 'int', 'integer']);
+        for (const row of rows) {
+            const column = expected.get(`${row.table_name}\0${row.column_name}`);
+            if (!column)
+                continue;
+            const needsBigint = column.type === 'bigint' && narrowTypes.has(row.data_type.toLowerCase());
+            const needsAutoIncrement = Boolean(column.autoIncrement) && !row.extra.toLowerCase().includes('auto_increment');
+            if (!needsBigint && !needsAutoIncrement)
+                continue;
+            const definition = this.formatColumnDefinition(row.column_name, {
+                ...column,
+                primary: false,
+                unique: false,
+            });
+            await this.query(`ALTER TABLE ${this.quoteIdentifier(row.table_name)} MODIFY COLUMN ${definition}`);
+        }
+    }
     formatAlterTable(tableName, alterations) {
         return `ALTER TABLE ${this.quoteIdentifier(String(tableName))} ${alterations.join(', ')}`;
     }
@@ -189,19 +260,20 @@ export class MySQLDialect extends Dialect {
      * 在连接池模式下，会获取一个专用连接用于事务
      */
     async beginTransaction(options) {
+        const dialect = this;
         if (this.usePool) {
             // 从连接池获取一个连接用于事务
             const connection = await this.pool.getConnection();
             // 设置隔离级别
             if (options?.isolationLevel) {
-                await connection.execute(`SET TRANSACTION ISOLATION LEVEL ${this.formatIsolationLevel(options.isolationLevel)}`);
+                await connection.query(`SET TRANSACTION ISOLATION LEVEL ${this.formatIsolationLevel(options.isolationLevel)}`);
             }
             // 开始事务
-            await connection.execute('START TRANSACTION');
+            await connection.beginTransaction();
             return {
                 async commit() {
                     try {
-                        await connection.execute('COMMIT');
+                        await connection.commit();
                     }
                     finally {
                         connection.release(); // 归还连接到池
@@ -209,36 +281,36 @@ export class MySQLDialect extends Dialect {
                 },
                 async rollback() {
                     try {
-                        await connection.execute('ROLLBACK');
+                        await connection.rollback();
                     }
                     finally {
                         connection.release(); // 归还连接到池
                     }
                 },
                 async query(sql, params) {
-                    const [rows] = await connection.execute(sql, params);
-                    return rows;
+                    const [rows, fields] = await connection.execute(sql, params);
+                    return dialect.processQueryResults(rows, fields);
                 }
             };
         }
         else {
-            // 单连接模式
-            const dialect = this;
             // 设置隔离级别
             if (options?.isolationLevel) {
-                await this.query(`SET TRANSACTION ISOLATION LEVEL ${this.formatIsolationLevel(options.isolationLevel)}`);
+                await this.connection.query(`SET TRANSACTION ISOLATION LEVEL ${this.formatIsolationLevel(options.isolationLevel)}`);
             }
             // 开始事务
-            await this.query('START TRANSACTION');
+            await this.connection.beginTransaction();
+            const connection = this.connection;
             return {
                 async commit() {
-                    await dialect.query('COMMIT');
+                    await connection.commit();
                 },
                 async rollback() {
-                    await dialect.query('ROLLBACK');
+                    await connection.rollback();
                 },
                 async query(sql, params) {
-                    return dialect.query(sql, params);
+                    const [rows, fields] = await connection.execute(sql, params);
+                    return dialect.processQueryResults(rows, fields);
                 }
             };
         }

package/lib/dialects/pg.d.ts

@@ -1,7 +1,7 @@
 import { Dialect, Database } from '../base/index.js';
 import { RelatedDatabase } from "../type/related/database.js";
 import type { ClientConfig } from 'pg';
-import { Column, Transaction, TransactionOptions, PoolConfig } from "../types.js";
+import { Column, Transaction, TransactionOptions, PoolConfig, type Definition } from "../types.js";
 export interface PostgreSQLDialectConfig extends ClientConfig {
     /**
      * 连接池配置
@@ -19,6 +19,7 @@ export declare class PostgreSQLDialect<S extends Record<string, object> = Record
     disconnect(): Promise<void>;
     healthCheck(): Promise<boolean>;
     query<U = any>(sql: string, params?: any[]): Promise<U>;
+    private normalizeResult;
     dispose(): Promise<void>;
     /**
      * 获取连接池统计信息（仅在使用连接池时有效）
@@ -42,6 +43,7 @@ export declare class PostgreSQLDialect<S extends Record<string, object> = Record
     formatLimitOffset(limit: number, offset: number): string;
     formatCreateTable<T extends keyof S>(tableName: T, columns: string[]): string;
     formatColumnDefinition(field: string, column: Column<any>): string;
+    reconcileDefinitions(definitions: ReadonlyMap<keyof S, Definition<S[keyof S]>>): Promise<void>;
     formatAlterTable<T extends keyof S>(tableName: T, alterations: string[]): string;
     formatDropTable<T extends keyof S>(tableName: T, ifExists?: boolean): string;
     formatDropIndex<T extends keyof S>(indexName: string, tableName: T, ifExists?: boolean): string;

package/lib/dialects/pg.js

@@ -19,12 +19,13 @@ export class PostgreSQLDialect extends Dialect {
         try {
             if (this.usePool) {
                 const { Pool } = await import('pg');
+                const { pool, ...connectionOptions } = this.config;
                 const poolConfig = {
-                    ...this.config,
-                    max: this.config.pool?.max ?? 10,
-                    min: this.config.pool?.min ?? 2,
-                    idleTimeoutMillis: this.config.pool?.idleTimeoutMillis ?? 30000,
-                    connectionTimeoutMillis: this.config.pool?.acquireTimeoutMillis ?? 10000,
+                    ...connectionOptions,
+                    max: pool?.max ?? 10,
+                    min: pool?.min ?? 2,
+                    idleTimeoutMillis: pool?.idleTimeoutMillis ?? 30000,
+                    connectionTimeoutMillis: pool?.acquireTimeoutMillis ?? 10000,
                 };
                 this.pool = new Pool(poolConfig);
                 logger.info(`PostgreSQL 连接池已创建 (max: ${poolConfig.max})`);
@@ -65,13 +66,32 @@ export class PostgreSQLDialect extends Dialect {
     async query(sql, params) {
         if (this.usePool) {
             const result = await this.pool.query(sql, params);
-            return result.rows;
+            return this.normalizeResult(result);
         }
         else {
             const result = await this.connection.query(sql, params);
-            return result.rows;
+            return this.normalizeResult(result);
         }
     }
+    normalizeResult(result) {
+        const bigintFields = new Set((result.fields ?? [])
+            .filter((field) => field.dataTypeID === 20)
+            .map((field) => field.name));
+        if (bigintFields.size === 0)
+            return result.rows;
+        return result.rows.map((row) => {
+            const normalized = { ...row };
+            for (const field of bigintFields) {
+                const value = normalized[field];
+                if (typeof value !== 'string' || !/^-?\d+$/u.test(value))
+                    continue;
+                const number = Number(value);
+                if (Number.isSafeInteger(number))
+                    normalized[field] = number;
+            }
+            return normalized;
+        });
+    }
     async dispose() {
         await this.disconnect();
     }
@@ -92,6 +112,7 @@ export class PostgreSQLDialect extends Dialect {
         const typeMap = {
             'text': 'TEXT',
             'integer': 'INTEGER',
+            'bigint': 'BIGINT',
             'float': 'REAL',
             'boolean': 'BOOLEAN',
             'date': 'TIMESTAMP',
@@ -159,10 +180,46 @@ export class PostgreSQLDialect extends Dialect {
         const nullable = column.nullable === false ? ' NOT NULL' : '';
         const primary = column.primary ? ' PRIMARY KEY' : '';
         const unique = column.unique ? ' UNIQUE' : '';
+        const autoIncrement = column.autoIncrement ? ' GENERATED BY DEFAULT AS IDENTITY' : '';
         const defaultVal = column.default !== undefined
             ? ` DEFAULT ${this.formatDefaultValue(column.default)}`
             : '';
-        return `${name} ${type}${length}${primary}${unique}${nullable}${defaultVal}`;
+        return `${name} ${type}${length}${autoIncrement}${primary}${unique}${nullable}${defaultVal}`;
+    }
+    async reconcileDefinitions(definitions) {
+        const expected = new Map();
+        for (const [tableName, definition] of definitions) {
+            for (const [columnName, column] of Object.entries(definition)) {
+                if (column.type === 'bigint' || column.autoIncrement) {
+                    expected.set(`${String(tableName)}\0${columnName}`, column);
+                }
+            }
+        }
+        if (expected.size === 0)
+            return;
+        const tableNames = [...new Set([...expected.keys()].map((key) => key.slice(0, key.indexOf('\0'))))];
+        const rows = await this.query(`SELECT table_name, column_name, data_type, is_identity, column_default
+       FROM information_schema.columns
+       WHERE table_schema = current_schema() AND table_name = ANY($1::text[])`, [tableNames]);
+        for (const row of rows) {
+            const definition = expected.get(`${row.table_name}\0${row.column_name}`);
+            if (!definition)
+                continue;
+            const table = this.quoteIdentifier(row.table_name);
+            const column = this.quoteIdentifier(row.column_name);
+            if (definition.type === 'bigint' && (row.data_type === 'smallint' || row.data_type === 'integer')) {
+                await this.query(`ALTER TABLE ${table} ALTER COLUMN ${column} TYPE BIGINT USING ${column}::BIGINT`);
+            }
+            const hasSequenceDefault = row.column_default?.startsWith('nextval(') ?? false;
+            if (definition.autoIncrement && row.is_identity !== 'YES' && !hasSequenceDefault) {
+                await this.query(`ALTER TABLE ${table} ALTER COLUMN ${column} ADD GENERATED BY DEFAULT AS IDENTITY`);
+                const maximum = await this.query(`SELECT MAX(${column}) AS max_value FROM ${table}`);
+                const maximumValue = maximum[0]?.max_value;
+                const next = (maximumValue == null ? 1n : BigInt(maximumValue) + 1n).toString();
+                const relation = `"${row.table_name.replaceAll('"', '""')}"`;
+                await this.query('SELECT setval(pg_get_serial_sequence($1, $2), $3, false)', [relation, row.column_name, next]);
+            }
+        }
     }
     formatAlterTable(tableName, alterations) {
         return `ALTER TABLE ${this.quoteIdentifier(String(tableName))} ${alterations.join(', ')}`;
@@ -189,6 +246,7 @@ export class PostgreSQLDialect extends Dialect {
      * 在连接池模式下，会获取一个专用连接用于事务
      */
     async beginTransaction(options) {
+        const dialect = this;
         if (this.usePool) {
             // 从连接池获取一个连接用于事务
             const client = await this.pool.connect();
@@ -217,7 +275,7 @@ export class PostgreSQLDialect extends Dialect {
                 },
                 async query(sql, params) {
                     const result = await client.query(sql, params);
-                    return result.rows;
+                    return dialect.normalizeResult(result);
                 }
             };
         }

package/lib/dialects/redis.js

@@ -436,7 +436,7 @@ export class RedisDialect extends Dialect {
             throw new Error('EXPIRE 操作需要指定 key');
         }
         const key = `${keyPrefix}${query.key}`;
-        const ttl = params[0] || query.ttl;
+        const ttl = query.ttl ?? params[0];
         const result = await this.client.expire(key, ttl);
         return [{ key: query.key, result }];
     }
@@ -481,6 +481,7 @@ export class RedisDialect extends Dialect {
             dataTypes: {
                 'string': 'String',
                 'integer': 'Integer',
+                'bigint': 'Integer',
                 'float': 'Float',
                 'boolean': 'Boolean',
                 'date': 'Timestamp',

package/lib/dialects/sqlite.js

@@ -154,6 +154,7 @@ export class SQLiteDialect extends Dialect {
         const typeMap = {
             'text': 'TEXT',
             'integer': 'INTEGER',
+            'bigint': 'INTEGER',
             'float': 'REAL',
             'boolean': 'INTEGER',
             'date': 'TEXT',
@@ -217,14 +218,16 @@ export class SQLiteDialect extends Dialect {
     formatColumnDefinition(field, column) {
         const name = this.quoteIdentifier(String(field));
         const type = this.mapColumnType(column.type);
-        const length = column.length ? `(${column.length})` : '';
+        // SQLite only enables rowid auto-increment for the exact INTEGER PRIMARY KEY form.
+        const length = column.length && !column.autoIncrement ? `(${column.length})` : '';
         const nullable = column.nullable === false ? ' NOT NULL' : '';
         const primary = column.primary ? ' PRIMARY KEY' : '';
         const unique = column.unique ? ' UNIQUE' : '';
+        const autoIncrement = column.autoIncrement ? ' AUTOINCREMENT' : '';
         const defaultVal = column.default !== undefined
             ? ` DEFAULT ${this.formatDefaultValue(column.default)}`
             : '';
-        return `${name} ${type}${length}${primary}${unique}${nullable}${defaultVal}`;
+        return `${name} ${type}${length}${primary}${autoIncrement}${unique}${nullable}${defaultVal}`;
     }
     formatAlterTable(tableName, alterations) {
         return `ALTER TABLE ${this.quoteIdentifier(String(tableName))} ${alterations.join(', ')}`;

package/lib/migration.js

@@ -245,21 +245,9 @@ export class MigrationRunner {
         const db = this.database;
         return {
             async createTable(tableName, columns) {
-                const columnDefs = Object.entries(columns).map(([name, col]) => {
-                    let def = `"${name}" ${mapColumnType(col.type)}`;
-                    if (col.primary)
-                        def += ' PRIMARY KEY';
-                    if (col.autoIncrement)
-                        def += ' AUTOINCREMENT';
-                    if (col.unique)
-                        def += ' UNIQUE';
-                    if (!col.nullable)
-                        def += ' NOT NULL';
-                    if (col.default !== undefined)
-                        def += ` DEFAULT ${formatDefault(col.default)}`;
-                    return def;
-                }).join(', ');
-                const sql = `CREATE TABLE IF NOT EXISTS "${tableName}" (${columnDefs})`;
+                const columnDefs = Object.entries(columns)
+                    .map(([name, column]) => db.dialect.formatColumnDefinition(name, column));
+                const sql = db.dialect.formatCreateTable(tableName, columnDefs);
                 await db.query(sql);
             },
             async dropTable(tableName) {
@@ -267,14 +255,8 @@ export class MigrationRunner {
                 await db.query(sql);
             },
             async addColumn(tableName, columnName, column) {
-                let def = `"${columnName}" ${mapColumnType(column.type)}`;
-                if (column.unique)
-                    def += ' UNIQUE';
-                if (!column.nullable)
-                    def += ' NOT NULL';
-                if (column.default !== undefined)
-                    def += ` DEFAULT ${formatDefault(column.default)}`;
-                const sql = `ALTER TABLE "${tableName}" ADD COLUMN ${def}`;
+                const def = db.dialect.formatColumnDefinition(columnName, column);
+                const sql = `ALTER TABLE ${db.dialect.quoteIdentifier(tableName)} ADD COLUMN ${def}`;
                 await db.query(sql);
             },
             async dropColumn(tableName, columnName) {
@@ -437,33 +419,6 @@ export class MigrationRunner {
         return { rolledBack, migrated };
     }
 }
-/**
- * 映射列类型到 SQL 类型
- */
-function mapColumnType(type) {
-    const typeMap = {
-        'text': 'TEXT',
-        'integer': 'INTEGER',
-        'float': 'REAL',
-        'boolean': 'INTEGER',
-        'date': 'DATETIME',
-        'json': 'TEXT'
-    };
-    return typeMap[type] || type.toUpperCase();
-}
-/**
- * 格式化默认值
- */
-function formatDefault(value) {
-    if (value === null)
-        return 'NULL';
-    // 与各方言 escapeString 一致：单引号 doubling，避免默认值中的引号破坏 SQL
-    if (typeof value === 'string')
-        return `'${value.replace(/'/g, "''")}'`;
-    if (typeof value === 'boolean')
-        return value ? '1' : '0';
-    return String(value);
-}
 /**
  * 创建迁移辅助函数
  *

package/lib/type/document/database.js

@@ -45,6 +45,7 @@ export class DocumentDatabase extends Database {
         return {
             query: {
                 collection: params.tableName,
+                operation: 'createCollection',
                 filter: {},
                 projection: {}
             },
@@ -62,6 +63,7 @@ export class DocumentDatabase extends Database {
         }
         const query = {
             collection: params.tableName,
+            operation: 'find',
             filter
         };
         if (params.orderings) {
@@ -94,6 +96,7 @@ export class DocumentDatabase extends Database {
         return {
             query: {
                 collection: params.tableName,
+                operation: 'insertOne',
                 filter: {},
                 projection: {}
             },
@@ -111,6 +114,7 @@ export class DocumentDatabase extends Database {
         return {
             query: {
                 collection: params.tableName,
+                operation: 'updateMany',
                 filter,
                 projection: {}
             },
@@ -128,6 +132,7 @@ export class DocumentDatabase extends Database {
         return {
             query: {
                 collection: params.tableName,
+                operation: 'deleteMany',
                 filter,
                 projection: {}
             },
@@ -138,14 +143,7 @@ export class DocumentDatabase extends Database {
      * 构建修改集合查询
      */
     buildAlterQuery(params) {
-        return {
-            query: {
-                collection: params.tableName,
-                filter: {},
-                projection: {}
-            },
-            params: [params.alterations]
-        };
+        throw new TypeError(`Document schema alteration is not supported for collection ${String(params.tableName)}`);
     }
     /**
      * 构建删除集合查询
@@ -154,6 +152,7 @@ export class DocumentDatabase extends Database {
         return {
             query: {
                 collection: params.tableName,
+                operation: 'dropCollection',
                 filter: {},
                 projection: {}
             },
@@ -167,6 +166,7 @@ export class DocumentDatabase extends Database {
         return {
             query: {
                 collection: params.tableName,
+                operation: 'dropIndex',
                 filter: {},
                 projection: {}
             },

package/lib/type/document/model.js

@@ -36,7 +36,7 @@ export class DocumentModel extends Model {
      * 根据ID查找文档
      */
     async selectById(id) {
-        return this.select('_id').where({
+        return this.select().where({
             _id: id,
         }).limit(1).then((results) => results[0] || null);
     }

package/lib/type/keyvalue/model.js

@@ -31,13 +31,7 @@ export class KeyValueModel extends Model {
         if (results.length === 0) {
             return null;
         }
-        const row = results[0];
-        // 检查是否过期
-        if (row.expires_at && Date.now() > row.expires_at) {
-            await this.deleteByKey(key);
-            return null;
-        }
-        return JSON.parse(row.value);
+        return results[0];
     }
     /**
      * 删除键
@@ -48,7 +42,7 @@ export class KeyValueModel extends Model {
             bucket: this.name,
             key,
         }, [key]);
-        return result.affectedRows > 0;
+        return result[0]?.deleted === true;
     }
     /**
      * 检查键是否存在
@@ -59,7 +53,7 @@ export class KeyValueModel extends Model {
             bucket: this.name,
             key,
         }, [key, Date.now()]);
-        return results.length > 0;
+        return results[0] === true;
     }
     /**
      * 获取所有键
@@ -69,7 +63,7 @@ export class KeyValueModel extends Model {
             operation: 'keys',
             bucket: this.name,
         }, [Date.now()]);
-        return results.map((row) => row.key);
+        return results;
     }
     /**
      * 获取所有值
@@ -79,7 +73,7 @@ export class KeyValueModel extends Model {
             operation: 'values',
             bucket: this.name,
         }, [Date.now()]);
-        return results.map((row) => JSON.parse(row.value));
+        return results;
     }
     /**
      * 获取所有键值对
@@ -89,7 +83,7 @@ export class KeyValueModel extends Model {
             operation: 'entries',
             bucket: this.name,
         }, [Date.now()]);
-        return results.map((row) => [row.key, JSON.parse(row.value)]);
+        return results;
     }
     /**
      * 清空桶
@@ -108,35 +102,27 @@ export class KeyValueModel extends Model {
             operation: 'size',
             bucket: this.name,
         }, [Date.now()]);
-        return results[0]?.count || 0;
+        return results[0] ?? 0;
     }
     /**
      * 批量设置
      */
     async setMany(entries, ttl) {
-        const expiresAt = ttl ? Date.now() + ttl * 1000 : null;
         for (const [key, value] of entries) {
-            await this.dialect.query({
-                operation: 'set',
-                bucket: this.name,
-                key,
-                value,
-                ttl,
-            }, [key, JSON.stringify(value), expiresAt]);
+            await this.set(key, value, ttl);
         }
     }
     /**
      * 设置过期时间
      */
     async expire(key, ttl) {
-        const expiresAt = Date.now() + ttl * 1000;
         const result = await this.dialect.query({
             operation: 'expire',
             bucket: this.name,
             key,
             ttl,
-        }, [expiresAt, key]);
-        return result.affectedRows > 0;
+        }, []);
+        return Boolean(result[0]?.result);
     }
     /**
      * 获取剩余过期时间（秒）
@@ -150,12 +136,7 @@ export class KeyValueModel extends Model {
         if (results.length === 0) {
             return null;
         }
-        const expiresAt = results[0].expires_at;
-        if (!expiresAt) {
-            return -1; // 永不过期
-        }
-        const remaining = Math.ceil((expiresAt - Date.now()) / 1000);
-        return remaining > 0 ? remaining : 0;
+        return results[0];
     }
     /**
      * 移除过期时间
@@ -166,7 +147,7 @@ export class KeyValueModel extends Model {
             bucket: this.name,
             key,
         }, [key]);
-        return result.affectedRows > 0;
+        return Boolean(result[0]?.result);
     }
     /**
      * 清理过期键
@@ -176,20 +157,18 @@ export class KeyValueModel extends Model {
             operation: 'cleanup',
             bucket: this.name,
         }, [Date.now()]);
-        return result.affectedRows;
+        return result[0]?.cleaned ?? 0;
     }
     /**
      * 获取键的模式匹配
      */
     async keysByPattern(pattern) {
-        // 简单的通配符匹配，将 * 转换为 SQL 的 %
-        const sqlPattern = pattern.replace(/\*/g, '%');
         const results = await this.dialect.query({
             operation: 'keysByPattern',
             bucket: this.name,
-            pattern: sqlPattern,
-        }, [sqlPattern, Date.now()]);
-        return results.map((row) => row.key);
+            pattern,
+        }, []);
+        return results;
     }
     /**
      * 原子操作：如果不存在则设置

package/lib/type/related/database.d.ts

@@ -48,7 +48,7 @@ export declare class RelatedDatabase<D = any, S extends Record<string, object> =
      * @param condition 条件对象
      * @param tablePrefix 表名前缀（用于 JOIN 查询）
      */
-    protected parseCondition<T extends object>(condition: Condition<T>, tablePrefix?: string): [string, any[]];
+    protected parseCondition<T extends object>(condition: Condition<T>, tablePrefix?: string, parameterOffset?: number): [string, any[]];
     /**
      * 获取模型
      * @param name 模型名称

package/lib/type/related/database.js

@@ -40,12 +40,14 @@ export class RelatedDatabase extends Database {
         return this;
     }
     async initialize() {
-        // 并行创建所有表以提高性能
+        // 单连接方言（PostgreSQL Client 等）不允许同一连接并发 query。
+        // 初始化只发生在启动阶段，按定义顺序建表也让失败位置保持确定。
         const tableEntries = Array.from(this.definitions.entries());
-        await Promise.all(tableEntries.map(async ([tableName, definition]) => {
+        for (const [tableName, definition] of tableEntries) {
             await this.create(tableName, definition);
-        }));
-        // 创建完成后，统一设置 models（避免并发竞争）
+        }
+        await this.dialect.reconcileDefinitions(this.definitions);
+        // 创建完成后，统一设置 models。
         for (const [tableName, definition] of tableEntries) {
             this.models.set(tableName, new RelatedModel(this, tableName, definition));
         }
@@ -215,7 +217,7 @@ export class RelatedDatabase extends Database {
         const queryParams = [...Object.values(params.update)];
         // WHERE clause
         if (params.conditions) {
-            const [condition, conditionParams] = this.parseCondition(params.conditions);
+            const [condition, conditionParams] = this.parseCondition(params.conditions, undefined, queryParams.length);
             if (condition) {
                 query += ` WHERE ${condition}`;
                 queryParams.push(...conditionParams);
@@ -297,7 +299,7 @@ export class RelatedDatabase extends Database {
         }
         // HAVING clause
         if (params.havingConditions && Object.keys(params.havingConditions).length) {
-            const [havingCondition, havingParams] = this.parseCondition(params.havingConditions);
+            const [havingCondition, havingParams] = this.parseCondition(params.havingConditions, undefined, queryParams.length);
             if (havingCondition) {
                 query += ` HAVING ${havingCondition}`;
                 queryParams.push(...havingParams);
@@ -309,16 +311,7 @@ export class RelatedDatabase extends Database {
     // Helper Methods
     // ========================================================================
     formatColumnDefinition(field, column) {
-        const name = this.dialect.quoteIdentifier(String(field));
-        const type = this.dialect.mapColumnType(column.type);
-        const length = column.length ? `(${column.length})` : '';
-        const nullable = column.nullable === false ? ' NOT NULL' : '';
-        const primary = column.primary ? ' PRIMARY KEY' : '';
-        const unique = column.unique ? ' UNIQUE' : '';
-        const defaultVal = column.default !== undefined
-            ? ` DEFAULT ${this.dialect.formatDefaultValue(column.default)}`
-            : '';
-        return `${name} ${type}${length}${primary}${unique}${nullable}${defaultVal}`;
+        return this.dialect.formatColumnDefinition(field, column);
     }
     formatAlteration(field, alteration) {
         const name = this.dialect.quoteIdentifier(field);
@@ -354,7 +347,7 @@ export class RelatedDatabase extends Database {
      * @param condition 条件对象
      * @param tablePrefix 表名前缀（用于 JOIN 查询）
      */
-    parseCondition(condition, tablePrefix) {
+    parseCondition(condition, tablePrefix, parameterOffset = 0) {
         const clauses = [];
         const params = [];
         // 辅助函数：生成带前缀的字段名
@@ -368,7 +361,7 @@ export class RelatedDatabase extends Database {
             if (key === '$and' && Array.isArray(condition.$and)) {
                 const subClauses = [];
                 for (const subCondition of condition.$and) {
-                    const [subClause, subParams] = this.parseCondition(subCondition, tablePrefix);
+                    const [subClause, subParams] = this.parseCondition(subCondition, tablePrefix, parameterOffset + params.length);
                     if (subClause) {
                         subClauses.push(`(${subClause})`);
                         params.push(...subParams);
@@ -381,7 +374,7 @@ export class RelatedDatabase extends Database {
             else if (key === '$or' && Array.isArray(condition.$or)) {
                 const subClauses = [];
                 for (const subCondition of condition.$or) {
-                    const [subClause, subParams] = this.parseCondition(subCondition, tablePrefix);
+                    const [subClause, subParams] = this.parseCondition(subCondition, tablePrefix, parameterOffset + params.length);
                     if (subClause) {
                         subClauses.push(`(${subClause})`);
                         params.push(...subParams);
@@ -392,7 +385,7 @@ export class RelatedDatabase extends Database {
                 }
             }
             else if (key === '$not' && condition.$not) {
-                const [subClause, subParams] = this.parseCondition(condition.$not, tablePrefix);
+                const [subClause, subParams] = this.parseCondition(condition.$not, tablePrefix, parameterOffset + params.length);
                 if (subClause) {
                     clauses.push(`NOT (${subClause})`);
                     params.push(...subParams);
@@ -409,7 +402,7 @@ export class RelatedDatabase extends Database {
                 if (isPlainObject) {
                     for (const op in value) {
                         const quotedKey = formatField(key);
-                        const placeholder = this.dialect.getParameterPlaceholder(params.length);
+                        const placeholder = this.dialect.getParameterPlaceholder(parameterOffset + params.length);
                         switch (op) {
                             case '$eq':
                                 if (value[op] === null) {
@@ -453,7 +446,7 @@ export class RelatedDatabase extends Database {
                                     params.push(...subquery.params);
                                 }
                                 else if (Array.isArray(value[op]) && value[op].length) {
-                                    const placeholders = value[op].map((_, i) => this.dialect.getParameterPlaceholder(params.length + i));
+                                    const placeholders = value[op].map((_, i) => this.dialect.getParameterPlaceholder(parameterOffset + params.length + i));
                                     clauses.push(`${quotedKey} IN (${placeholders.join(', ')})`);
                                     params.push(...value[op]);
                                 }
@@ -469,7 +462,7 @@ export class RelatedDatabase extends Database {
                                     params.push(...subquery.params);
                                 }
                                 else if (Array.isArray(value[op]) && value[op].length) {
-                                    const placeholders = value[op].map((_, i) => this.dialect.getParameterPlaceholder(params.length + i));
+                                    const placeholders = value[op].map((_, i) => this.dialect.getParameterPlaceholder(parameterOffset + params.length + i));
                                     clauses.push(`${quotedKey} NOT IN (${placeholders.join(', ')})`);
                                     params.push(...value[op]);
                                 }
@@ -494,7 +487,7 @@ export class RelatedDatabase extends Database {
                         clauses.push(`${quotedKey} IS NULL`);
                     }
                     else {
-                        const placeholder = this.dialect.getParameterPlaceholder(params.length);
+                        const placeholder = this.dialect.getParameterPlaceholder(parameterOffset + params.length);
                         clauses.push(`${quotedKey} = ${placeholder}`);
                         params.push(value);
                     }

package/lib/types.d.ts

@@ -5,7 +5,7 @@ export interface AggregateField<T extends object> {
     field: keyof T | '*';
     alias?: string;
 }
-export type ColumnType = "text" | "integer" | "float" | "boolean" | "date" | "json";
+export type ColumnType = "text" | "integer" | "bigint" | "float" | "boolean" | "date" | "json";
 export interface Column<T = any> {
     type: ColumnType;
     nullable?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/database",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "Universal database abstraction layer for Zhin.js - supports SQLite, MySQL, PostgreSQL, MongoDB, Redis",
   "type": "module",
   "main": "./lib/index.js",
@@ -47,7 +47,7 @@
     "mongodb": "^7.5.0",
     "mysql2": "^3.23.2",
     "pg": "^8.22.0",
-    "redis": "latest",
+    "redis": "^6.1.0",
     "typescript": "^6.0.3"
   },
   "repository": {