tspace-mysql 1.9.4-beta.2 → 1.9.4-beta.4

package/dist/lib/core/Builder.js

@@ -7,12 +7,11 @@ const DB_1 = require("./DB");
 const StateManager_1 = require("./StateManager");
 const Join_1 = require("./Join");
 const constants_1 = require("../constants");
-const config_1 = require("../config");
 const Pool_1 = require("./Pool");
 class Builder extends AbstractBuilder_1.AbstractBuilder {
     constructor() {
         super();
-        this._initialConnection();
+        this._initBuilder();
     }
     /**
      * The 'instance' method is used get instance.
@@ -44,6 +43,16 @@ class Builder extends AbstractBuilder_1.AbstractBuilder {
     database() {
         return this.$database;
     }
+    useNode(type, options = {}) {
+        if (!this.$cluster) {
+            throw new Error('.useNode() is only available in cluster mode');
+        }
+        if (type === 'primary' && options.node !== undefined) {
+            throw new Error('The primary node cannot be specified');
+        }
+        this.$state.set('NODE', { type, node: options.node });
+        return this;
+    }
     /**
      * The 'rowLock' method is used to row level locks (`FOR UPDATE` or `FOR SHARE`) to the query.
      *
@@ -2302,43 +2311,15 @@ class Builder extends AbstractBuilder_1.AbstractBuilder {
      * @returns {Promise<Array>}
      */
     async showSchema(table = String(this.$state.get("TABLE_NAME")), options = {}) {
-        const sql = this._queryBuilder().getSchema({
+        const qb = this._queryBuilder();
+        const sql = qb.getSchema({
             database: this.$database,
-            table,
+            table: this.$utils.escape(table),
         });
-        const raws = await this._queryStatement(sql);
+        const raws = await this.rawQuery(sql);
         if (options.raw)
             return raws;
-        const schema = raws.map((r) => {
-            const schema = [];
-            schema.push(`\`${r.Field}\``);
-            schema.push(`${r.Type}`);
-            if (r.Nullable === "YES") {
-                schema.push(`NULL`);
-            }
-            if (r.Nullable === "NO") {
-                schema.push(`NOT NULL`);
-            }
-            if (r.Key === "PRI") {
-                schema.push(`PRIMARY KEY`);
-            }
-            if (r.Key === "UNI") {
-                schema.push(`UNIQUE`);
-            }
-            if (r.Default) {
-                if (r.Default.includes("IS_CONST:")) {
-                    schema.push(`DEFAULT ${String(r.Default).replace("IS_CONST:", "")}`);
-                }
-                else {
-                    schema.push(`DEFAULT '${r.Default}'`);
-                }
-            }
-            if (r.Extra) {
-                schema.push(`${r.Extra.toUpperCase()}`);
-            }
-            return schema.join(" ");
-        });
-        return schema;
+        return qb.mapSchema(raws);
     }
     /**
      * The `getSchema` method is used to retrieve the column schema for the database
@@ -2356,11 +2337,15 @@ class Builder extends AbstractBuilder_1.AbstractBuilder {
      *
      */
     async getSchema() {
-        const tableName = this.$state.get("TABLE_NAME");
-        if (tableName == null) {
+        const table = this.$state.get("TABLE_NAME");
+        if (table == null) {
             throw new Error('Unknown table name');
         }
-        return await this.showSchema(tableName, { raw: true });
+        const sql = this._queryBuilder().getSchema({
+            database: this.$database,
+            table,
+        });
+        return await this.rawQuery(sql);
     }
     /**
      * The 'getFKs' method is used to get foreign key constraints for the database or a specific table.
@@ -2822,6 +2807,7 @@ class Builder extends AbstractBuilder_1.AbstractBuilder {
             password,
             ...others,
         });
+        this.$state.set('BIND', true);
         this.$pool.set(pool.connect());
         return this;
     }
@@ -2858,6 +2844,7 @@ class Builder extends AbstractBuilder_1.AbstractBuilder {
      * @returns {this} this
      */
     bind(connection) {
+        this.$state.set('BIND', true);
         this.$pool.set(connection);
         return this;
     }
@@ -2965,24 +2952,20 @@ class Builder extends AbstractBuilder_1.AbstractBuilder {
      * @property {boolean?} opts.distinct
      * @returns {promise<Pagination>}
      */
-    async pagination(opts) {
-        let limit = 15;
-        let page = 1;
+    async pagination(opts = {}) {
+        const limit = this.$utils.softNumber(opts.limit ?? 15);
+        const page = this.$utils.softNumber(opts.page ?? 1);
         if (opts?.distinct) {
             this.distinct();
         }
-        if (opts != null) {
-            limit = opts?.limit || limit;
-            page = opts?.page || page;
-        }
         const currentPage = page;
         const nextPage = currentPage + 1;
         const prevPage = currentPage - 1 === 0 ? 1 : currentPage - 1;
         const offset = (page - 1) * limit;
-        this.limit(limit);
-        this.offset(offset);
-        let sql = this._queryBuilder().select();
-        const result = await this._queryStatement(sql);
+        const result = await this
+            .limit(limit)
+            .offset(offset)
+            .get();
         if (!result.length)
             return {
                 meta: {
@@ -3040,9 +3023,82 @@ class Builder extends AbstractBuilder_1.AbstractBuilder {
      * @property {boolean?} opts.distinct
      * @returns {promise<Pagination>}
      */
-    async paginate(opts) {
+    async paginate(opts = {}) {
         return await this.pagination(opts);
     }
+    /**
+     * The 'cursorPagination' method is used to perform cursor-based pagination
+     * on a set of database query results obtained through the Query Builder.
+     *
+     * It uses cursor-based pagination instead of offset pagination, making it
+     * more efficient when navigating through large datasets.
+     *
+     * @param {Object?} opts query opts
+     * @param {number?} opts.limit number of records per page, default is 15
+     * @param {string?} opts.cursor cursor used to retrieve the next page
+     * @param {boolean?} opts.distinct whether to retrieve distinct records
+     * @returns {Promise<TCursorPagination>}
+     */
+    async cursorPagination(opts = {}) {
+        const limit = this.$utils.softNumber(opts.limit ?? 15);
+        if (opts.distinct) {
+            this.distinct();
+        }
+        let cursor = null;
+        if (opts.cursor) {
+            try {
+                cursor = JSON.parse(Buffer.from(opts.cursor, 'base64').toString('utf8'));
+            }
+            catch {
+                throw new Error('Invalid cursor');
+            }
+        }
+        ;
+        const primaryKey = this.$state.get('PRIMARY_KEY');
+        const results = await this
+            .when(cursor != null, q => q.where(primaryKey, '>', cursor[primaryKey]))
+            .orderBy(primaryKey, 'ASC')
+            .limit(limit + 1)
+            .get();
+        const hasNextPage = results.length > limit;
+        if (hasNextPage) {
+            results.pop();
+        }
+        const lastResult = results[results.length - 1];
+        const nextCursor = hasNextPage && lastResult
+            ? Buffer.from(JSON.stringify({
+                [primaryKey]: lastResult[primaryKey],
+                timestamp: +new Date()
+            })).toString('base64')
+            : null;
+        return {
+            meta: {
+                limit: limit,
+                count: results.length,
+                next: {
+                    cursor: nextCursor,
+                    has: hasNextPage,
+                }
+            },
+            data: results,
+        };
+    }
+    /**
+     * The 'cursorPaginate' method is used to perform cursor-based pagination
+     * on a set of database query results obtained through the Query Builder.
+     *
+     * It uses cursor-based pagination instead of offset pagination, making it
+     * more efficient when navigating through large datasets.
+     *
+     * @param {Object?} opts query opts
+     * @param {number?} opts.limit number of records per page, default is 15
+     * @param {string?} opts.cursor cursor used to retrieve the next page
+     * @param {boolean?} opts.distinct whether to retrieve distinct records
+     * @returns {Promise<TCursorPagination>}
+     */
+    async cursorPaginate(opts = {}) {
+        return await this.cursorPagination(opts);
+    }
     /**
      *
      * The 'first' method is used to retrieve the first record that matches the query conditions.
@@ -3152,19 +3208,222 @@ class Builder extends AbstractBuilder_1.AbstractBuilder {
         return await this.get(cb);
     }
     /**
-     * The 'toAsyncIterable' method is used to execute a database query and return the result set as an asynchronous iterable.
+     * The 'explain' method is used to analyze the query execution plan
+     * without executing the query itself.
      *
-     * It retrieves multiple records from a database table based on the criteria specified in the query.
-     * The optional callback function can be used to modify the generated SQL query before execution.
+     * It retrieves the execution plan from the database and analyzes it
+     * for potential performance issues such as full table scans, filesorts,
+     * and temporary tables.
+     * @param {string?} sql query for explain
+     * @returns {Promise<TExplain>} query execution plan and analysis
+     */
+    async explain(sql) {
+        if (!sql) {
+            sql = this.toSQL();
+        }
+        const LARGE_SCAN_ROWS = 10_000;
+        const qb = this._queryBuilder();
+        const plan = await this.rawQuery(qb.explain(sql)).catch(() => []);
+        const issues = [];
+        const recommendations = [];
+        for (const row of plan) {
+            const text = JSON.stringify(row).toLowerCase();
+            const textRow = Object.values(row)
+                .filter(value => typeof value === 'string')
+                .join(' ');
+            const type = String(row.type ?? '').toLowerCase();
+            const possibleKeys = row.possible_keys;
+            const key = row.key;
+            const rows = /^\d+(?:\.\d+)?$/.test(String(row.rows))
+                ? Number(row.rows)
+                : Number(textRow.match(/\brows=(\d+(?:\.\d+)?)/i)?.[1] ?? 0);
+            const hasPossibleIndex = possibleKeys != null &&
+                String(possibleKeys).trim() !== '';
+            const hasUsedIndex = key != null &&
+                String(key).trim() !== '';
+            const hasFullScan = type === 'all' &&
+                !hasPossibleIndex;
+            if (hasFullScan) {
+                issues.push({
+                    type: 'FULL_SCAN',
+                    severity: rows > LARGE_SCAN_ROWS ? 'warning' : 'info',
+                    message: `A full table scan was detected (${rows.toLocaleString()} rows).`,
+                });
+                recommendations.push('Consider adding an appropriate index for the query conditions.');
+            }
+            if (Number.isFinite(rows) && rows >= LARGE_SCAN_ROWS) {
+                issues.push({
+                    type: 'LARGE_SCAN',
+                    severity: 'warning',
+                    message: `The query is estimated to scan ${rows} rows.`,
+                });
+                recommendations.push('Consider optimizing the query or adding an appropriate index.');
+            }
+            if (text.includes('filesort') ||
+                text.includes('sort')) {
+                issues.push({
+                    type: 'FILE_SORT',
+                    severity: 'warning',
+                    message: 'A sort operation was detected.',
+                });
+                recommendations.push('Consider an index that supports the WHERE and ORDER BY conditions.');
+            }
+            if (text.includes('temporary') ||
+                text.includes('temp table')) {
+                issues.push({
+                    type: 'TEMPORARY_TABLE',
+                    severity: 'warning',
+                    message: 'A temporary table was used.',
+                });
+                recommendations.push('Review GROUP BY, ORDER BY, DISTINCT, and JOIN conditions.');
+            }
+            const hasNoIndex = type === 'all' &&
+                !hasPossibleIndex &&
+                !hasUsedIndex;
+            if (hasNoIndex) {
+                issues.push({
+                    type: 'NO_INDEX',
+                    severity: 'warning',
+                    message: 'No index was used for this operation.',
+                });
+                recommendations.push('Consider adding an index for the query conditions.');
+            }
+            if (hasFullScan &&
+                (text.includes('filter:') ||
+                    text.includes('using where'))) {
+                issues.push({
+                    type: 'FILTER_AFTER_SCAN',
+                    severity: 'warning',
+                    message: 'Rows are filtered after scanning the table.',
+                });
+                recommendations.push('Consider an index that can apply the filter earlier.');
+            }
+        }
+        const status = issues.some(issue => issue.severity === 'critical')
+            ? 'critical'
+            : issues.some(issue => issue.severity === 'warning')
+                ? 'warning'
+                : 'ok';
+        return {
+            sql,
+            plan,
+            analysis: {
+                status,
+                issues,
+                recommendations: [...new Set(recommendations)],
+            },
+        };
+    }
+    /**
+     * The 'lazy' method is used to retrieve and process records incrementally
+     * without loading the entire result set into memory at once.
      *
-     * @param {Function?} cb callback function return query sql
-     * @returns {AsyncIterable<any>}
+     * It retrieves records in batches based on the specified limit and invokes
+     * the callback for each record. The process continues until all records
+     * have been retrieved and processed.
+     *
+     * The optional delayMs can be used to add a delay between each batch query,
+     * which can help reduce database load when processing a large number of records.
+     *
+     * @param {Function} callback callback function that receives each retrieved record
+     * @param {Object?} opts query opts
+     * @param {number?} opts.limit number of records to retrieve per query
+     * @param {number?} opts.offset number of records to skip before processing
+     * @param {number?} opts.delayMs delay in milliseconds between each batch
+     * @returns {Promise<void>}
      */
-    async *toAsyncIterable(cb) {
-        if (this.$state.get("VOID"))
+    async lazy(callback, opts = {}) {
+        const limit = opts.limit ?? 100;
+        const delayMs = opts.delayMs ?? 0;
+        let offset = opts.offset ?? 0;
+        while (true) {
+            const results = await this
+                .limit(limit)
+                .offset(offset)
+                .get();
+            if (results.length === 0) {
+                break;
+            }
+            for (const result of results) {
+                await callback(result);
+            }
+            if (results.length < limit) {
+                break;
+            }
+            offset += results.length;
+            if (delayMs > 0) {
+                await new Promise(resolve => setTimeout(resolve, delayMs));
+            }
+        }
+    }
+    /**
+     * The 'chunk' method is used to retrieve records from the database in chunks
+     * and process each chunk through a callback function.
+     *
+     * It retrieves records in batches based on the specified limit and invokes
+     * the callback with each batch of records. The process continues until all
+     * records have been retrieved and processed.
+     *
+     * The optional delayMs can be used to add a delay between each batch query,
+     * which can help reduce database load when processing a large number of records.
+     *
+     * @param {Function} callback callback function that receives the retrieved records
+     * @param {Object?} opts query opts
+     * @param {number?} opts.limit number of records to retrieve per chunk
+     * @param {number?} opts.offset number of records to skip before processing
+     * @param {number?} opts.delayMs delay in milliseconds between each batch
+     * @returns {Promise<void>}
+     */
+    async chunk(callback, opts = {}) {
+        const limit = opts.limit ?? 100;
+        const delayMs = opts.delayMs ?? 0;
+        let offset = opts.offset ?? 0;
+        while (true) {
+            const results = await this
+                .limit(limit)
+                .offset(offset)
+                .get();
+            if (results.length === 0) {
+                break;
+            }
+            await callback(results);
+            if (results.length < limit) {
+                break;
+            }
+            offset += results.length;
+            if (delayMs > 0) {
+                await new Promise(resolve => setTimeout(resolve, delayMs));
+            }
+        }
+    }
+    /**
+     * The 'stream' method is used to executes a SQL statement and asynchronously yields result rows.
+     *
+     * @returns {AsyncGenerator<T>} An async generator that yields result rows.
+     *
+     * @example
+     * ```ts
+     * import { DB } from "tspace-mysql";
+     *
+     * for await (const row of new DB('users').stream()) {
+     *   console.log(row);
+     * }
+     * ```
+     */
+    async *stream() {
+        if (this.$state.get('VOID')) {
             return yield* [];
-        const results = await this.get(cb);
-        return yield* results;
+        }
+        const sql = this.toString();
+        if (this.$state.get("DEBUG")) {
+            const startTime = +new Date();
+            const results = await this.$pool.stream(sql);
+            const endTime = +new Date();
+            this.$utils.consoleDebug(sql, false, this.$state.get("NODE"));
+            this.$utils.consoleExec(startTime, endTime);
+            return yield* results;
+        }
+        return yield* await this.$pool.stream(sql);
     }
     /**
      * The 'toArray' method is used to execute a database query and retrieve the result set that matches the query conditions.
@@ -3842,14 +4101,14 @@ class Builder extends AbstractBuilder_1.AbstractBuilder {
             const result = await this.$pool.query(sql);
             const endTime = +new Date();
             if (this.$state.get("DEBUG")) {
-                this.$utils.consoleDebug(sql);
+                this.$utils.consoleDebug(sql, false, this.$state.get("NODE"));
                 this.$utils.consoleExec(startTime, endTime);
             }
             return result;
         }
         catch (err) {
             if (this.$state.get("DEBUG"))
-                this.$utils.consoleDebug(sql);
+                this.$utils.consoleDebug(sql, false, this.$state.get("NODE"));
             throw err;
         }
     }
@@ -3859,14 +4118,14 @@ class Builder extends AbstractBuilder_1.AbstractBuilder {
             const result = await this.$pool.query(sql);
             const endTime = +new Date();
             if (this.$state.get("DEBUG")) {
-                this.$utils.consoleDebug(sql);
+                this.$utils.consoleDebug(sql, false, this.$state.get("NODE"));
                 this.$utils.consoleExec(startTime, endTime);
             }
             return result;
         }
         catch (err) {
             if (this.$state.get("DEBUG"))
-                this.$utils.consoleDebug(sql);
+                this.$utils.consoleDebug(sql, false, this.$state.get("NODE"));
             throw err;
         }
     }
@@ -4130,95 +4389,192 @@ class Builder extends AbstractBuilder_1.AbstractBuilder {
         ]);
         return this;
     }
-    _initialConnection() {
-        this.$utils = utils_1.utils;
-        this.$pool = (() => {
-            if (config_1.Config.CLUSTER) {
-                let poolCluster = Pool_1.Pool.clusterConnect();
-                if (poolCluster == null) {
-                    throw new Error("Cluster connection has not been initialized. Please verify your confings");
+    _initClusterPool() {
+        let poolCluster = Pool_1.Pool.clusterConnect();
+        if (poolCluster == null) {
+            throw new Error("Cluster connection has not been initialized. Please verify your confings");
+        }
+        return {
+            query: async (sql) => {
+                // The .bind the cluster context to the query method, 
+                // Overriding only the local pool reference.
+                if (poolCluster.primary == null) {
+                    const pool = poolCluster;
+                    // Reset the node state when the primary node is unavailable,
+                    // since it may have been set by the client.
+                    this.$state.set('NODE', null);
+                    return pool.query(sql);
                 }
-                return {
-                    query: async (sql) => {
-                        const first = sql.trim().split(/\s+/)[0].toUpperCase();
-                        const isRowLock = Object.values(this.$constants("ROW_LEVEL_LOCK")).some(lock => sql.toUpperCase().includes(lock));
-                        // Row-level locked SELECTs (e.g. FOR UPDATE, FOR SHARE) acquire database locks,
-                        // so they are not considered read-only queries and should be handled as write/locking operations.
-                        const isReaded = [
-                            this.$constants("SELECT"),
-                            this.$constants("SHOW"),
-                            this.$constants("DESCRIBE")
-                        ].includes(first) && !isRowLock;
-                        if (isReaded) {
-                            const length = poolCluster?.slaves?.length ?? 0;
-                            const random = Math.floor(Math.random() * length);
-                            return poolCluster?.query != null
-                                ? poolCluster.query(sql)
-                                : poolCluster?.slaves[random].query(sql);
-                        }
-                        const length = poolCluster?.masters?.length ?? 0;
-                        const random = Math.floor(Math.random() * length);
-                        return poolCluster.query != null
-                            ? poolCluster.query(sql)
-                            : poolCluster?.masters[random].query(sql);
-                    },
-                    get: () => poolCluster,
-                    set: (conn) => {
-                        if (conn.database != null) {
-                            this.$database = conn.database();
-                        }
-                        poolCluster = conn;
-                        return;
-                    },
-                    queryBuilder: () => {
-                        /**
-                         *
-                         * queryBuilder can use every nodes
-                         */
-                        return poolCluster?.masters == null
-                            ? poolCluster?.queryBuilder
-                            : poolCluster?.masters[0]?.queryBuilder;
-                    },
-                    transaction: async () => {
-                        return await poolCluster.masters[0].connection();
-                    },
-                    stream: async (sql) => {
-                        return await poolCluster.masters[0].stream(sql);
-                    },
-                };
-            }
-            let pool = Pool_1.Pool.connect();
-            return {
-                stream: async (sql) => {
-                    return await pool.stream(sql);
-                },
-                transaction: async () => {
-                    return await pool.connection();
-                },
-                query: async (sql) => {
+                const node = this.$state.get('NODE');
+                if (node?.type === 'primary') {
+                    this.useNode('primary');
+                    return poolCluster.primary.query(sql);
+                }
+                if (node?.type === 'replica') {
+                    const length = poolCluster.replicas.length;
+                    const nodeIndex = node.node
+                        ? node.node - 1
+                        : Math.floor(Math.random() * length);
+                    const pool = poolCluster
+                        .replicas[nodeIndex];
+                    if (pool == null) {
+                        throw new Error(`Replica node '${nodeIndex + 1}' not found`);
+                    }
+                    this.useNode('replica', { node: nodeIndex + 1 });
                     return pool.query(sql);
-                },
-                get: () => pool,
-                set: (conn) => {
-                    if (conn.database != null) {
-                        this.$database = conn.database();
+                }
+                const first = sql
+                    .trim()
+                    .split(/\s+/)[0].toUpperCase();
+                const isRowLock = Object.values(this.$constants("ROW_LEVEL_LOCK")).some(lock => sql.toUpperCase().includes(lock));
+                // Row-level locked SELECTs (e.g. FOR UPDATE, FOR SHARE) acquire database locks,
+                // so they are not considered read-only queries and should be handled as write/locking operations.
+                const isReaded = [
+                    this.$constants("SELECT"),
+                    this.$constants("SHOW"),
+                    this.$constants("DESCRIBE")
+                ].includes(first) && !isRowLock;
+                if (isReaded) {
+                    const length = poolCluster.replicas.length ?? 0;
+                    const nodeIndex = Math.floor(Math.random() * length);
+                    this.useNode('replica', { node: nodeIndex + 1 });
+                    return poolCluster.replicas[nodeIndex].query(sql);
+                }
+                this.useNode('primary');
+                return poolCluster.primary.query(sql);
+            },
+            get: () => poolCluster,
+            set: (conn) => {
+                if (conn.database != null) {
+                    this.$database = conn.database();
+                }
+                poolCluster = conn;
+                return;
+            },
+            queryBuilder: () => {
+                // The .bind the cluster context to the query method, 
+                // Overriding only the local pool reference.
+                if (poolCluster.primary == null) {
+                    const pool = poolCluster;
+                    return pool.queryBuilder;
+                }
+                return poolCluster.primary.queryBuilder;
+            },
+            transaction: async () => {
+                // The .bind the cluster context to the query method, 
+                // Overriding only the local pool reference.
+                if (poolCluster.primary == null) {
+                    const pool = poolCluster;
+                    return await pool.connection();
+                }
+                const node = this.$state.get('NODE');
+                if (node?.type === 'primary') {
+                    return await poolCluster.primary.connection();
+                }
+                if (node?.type === 'replica') {
+                    const length = poolCluster.replicas.length;
+                    const nodeIndex = node.node
+                        ? node.node - 1
+                        : Math.floor(Math.random() * length);
+                    const pool = poolCluster
+                        .replicas[nodeIndex];
+                    if (pool == null) {
+                        throw new Error(`Replica node '${nodeIndex + 1}' not found`);
                     }
-                    pool = conn;
-                    return;
-                },
-                queryBuilder: () => pool.queryBuilder,
-            };
-        })();
-        this.$state = new StateManager_1.StateManager("default");
-        this.$constants = ((name) => {
-            if (name == null)
+                    return await pool.connection();
+                }
+                return await poolCluster.primary.connection();
+            },
+            stream: async (sql) => {
+                // The .bind the cluster context to the query method, 
+                // Overriding only the local pool reference.
+                if (poolCluster.primary == null) {
+                    const pool = poolCluster;
+                    return pool.stream(sql);
+                }
+                const node = this.$state.get('NODE');
+                if (node?.type === 'primary') {
+                    return poolCluster.primary.stream(sql);
+                }
+                if (node?.type === 'replica') {
+                    const length = poolCluster.replicas.length;
+                    const nodeIndex = node.node
+                        ? node.node - 1
+                        : Math.floor(Math.random() * length);
+                    const pool = poolCluster
+                        .replicas[nodeIndex];
+                    if (pool == null) {
+                        throw new Error(`Replica node '${nodeIndex + 1}' not found`);
+                    }
+                    return pool.stream(sql);
+                }
+                const first = sql
+                    .trim()
+                    .split(/\s+/)[0].toUpperCase();
+                const isRowLock = Object.values(this.$constants("ROW_LEVEL_LOCK")).some(lock => sql.toUpperCase().includes(lock));
+                // Row-level locked SELECTs (e.g. FOR UPDATE, FOR SHARE) acquire database locks,
+                // so they are not considered read-only queries and should be handled as write/locking operations.
+                const isReaded = [
+                    this.$constants("SELECT"),
+                    this.$constants("SHOW"),
+                    this.$constants("DESCRIBE")
+                ].includes(first) && !isRowLock;
+                if (isReaded) {
+                    const length = poolCluster.replicas.length ?? 0;
+                    const nodeIndex = Math.floor(Math.random() * length);
+                    this.useNode('replica', { node: nodeIndex + 1 });
+                    return poolCluster.replicas[nodeIndex].stream(sql);
+                }
+                this.useNode('primary');
+                return poolCluster.primary.stream(sql);
+            },
+        };
+    }
+    _initSinglePool() {
+        let pool = Pool_1.Pool.connect();
+        return {
+            transaction: async () => {
+                return await pool.connection();
+            },
+            query: async (sql) => {
+                return pool.query(sql);
+            },
+            get: () => pool,
+            set: (conn) => {
+                if (conn.database != null) {
+                    this.$database = conn.database();
+                }
+                pool = conn;
+                return;
+            },
+            queryBuilder: () => pool.queryBuilder,
+            stream: async (sql) => {
+                return await pool.stream(sql);
+            },
+        };
+    }
+    _initPool() {
+        return this.$cluster
+            ? this._initClusterPool()
+            : this._initSinglePool();
+    }
+    _initConstants() {
+        return ((name) => {
+            if (name == null) {
                 return constants_1.CONSTANTS;
+            }
             if (!Object.prototype.hasOwnProperty.call(constants_1.CONSTANTS, name)) {
-                throw new Error(`Not found that constant : '${String(name)}'`);
+                throw new Error(`Constant not found: '${String(name)}'`);
             }
             return constants_1.CONSTANTS[name];
         });
     }
+    _initBuilder() {
+        this.$utils = utils_1.utils;
+        this.$pool = this._initPool();
+        this.$state = new StateManager_1.StateManager("default");
+        this.$constants = this._initConstants();
+    }
 }
 exports.Builder = Builder;
 exports.default = Builder;