# pardnio/node-mysql-pool

> Node.js MySQL connection pool by Pardn Chiu (邱敬幃) with read-write splitting, a chainable query builder, and slow query logging.

Maintained by 邱敬幃 Pardn Chiu (pardnchiu), Pardn Co., Ltd, Taiwan · Infrastructure Engineering. Source: https://github.com/pardnio/node-mysql-pool

Full text in one file: [English](https://node-mysql-pool.pardn.io/llms-full.txt) · [中文](https://node-mysql-pool.pardn.io/zh/llms-full.txt)

## Overview

- [Home](https://node-mysql-pool.pardn.io/index.md): Node.js MySQL connection pool by Pardn Chiu (邱敬幃) with read-write splitting, a chainable query builder, and slow query logging.
- [Getting Started](https://node-mysql-pool.pardn.io/getting-started.md): Install @pardnchiu/mysql-pool, set DB_READ_* and DB_WRITE_* variables, call init(), run a first query, and close the pools.

## Concepts

- [Architecture](https://node-mysql-pool.pardn.io/architecture.md): How MySQLPool layers config resolution, the static query builder, the query() executor, and the read and write mysql2 pools.
- [Read-Write Pools](https://node-mysql-pool.pardn.io/read-write-pools.md): Which pool each method uses, how table() target routes SELECT queries, and what happens when one side has no database set.
- [Builder State](https://node-mysql-pool.pardn.io/builder-state.md): Builder state lives in static fields: why every chain starts with table(), what persists after execution, and concurrent use.

## Querying

- [Select and Where](https://node-mysql-pool.pardn.io/select-and-where.md): Pick columns with select() and filter rows with where(): equality, comparison, LIKE wildcards, IN arrays, and quoting rules.
- [Joins](https://node-mysql-pool.pardn.io/joins.md): Join tables with innerJoin(), leftJoin(), and rightJoin(): the three-argument and four-argument forms and column quoting.
- [Sorting and Pagination](https://node-mysql-pool.pardn.io/sorting-and-pagination.md): Sort with orderBy(), page with limit() and offset(), and return the total row count in the same query with total().

## Writing

- [Insert and Update](https://node-mysql-pool.pardn.io/insert-and-update.md): Insert rows with insert(), update them with update() and increase(), and inline MySQL functions such as NOW() and UUID().
- [Upsert](https://node-mysql-pool.pardn.io/upsert.md): Insert or update on duplicate key with upsert(): default VALUES() update, explicit update data, and raw update clauses.
- [Raw SQL](https://node-mysql-pool.pardn.io/raw-sql.md): Run hand-written SQL with read(), write(), or query() and bind parameters with ? placeholders on the chosen pool.

## Operations

- [Slow Query Log](https://node-mysql-pool.pardn.io/slow-query-log.md): Every query over 20ms prints its duration and SQL to stdout; what is measured, what is logged, and what is not.
- [Lifecycle and Shutdown](https://node-mysql-pool.pardn.io/shutdown.md): How init() verifies connections, how close() ends both pools, and the SIGINT and SIGTERM handlers installed on import.

## Reference

- [Configuration](https://node-mysql-pool.pardn.io/configuration.md): All DB_READ_* and DB_WRITE_* environment variables, the MySQLConfig object, default values, and source priority in init().
- [API Reference](https://node-mysql-pool.pardn.io/api-reference.md): Signatures and return values of every public MySQLPool static method, grouped by lifecycle, building, and execution.
- [Known Limitations](https://node-mysql-pool.pardn.io/known-limitations.md): Behaviors to plan around: no transactions, NULL conditions, unquoted SQL fragments, shared static state, and process exit.

## Symbols

Exported symbol -> page that documents it.

- `MySQLPool` (src): [API Reference](https://node-mysql-pool.pardn.io/api-reference.md), [Architecture](https://node-mysql-pool.pardn.io/architecture.md)

## 中文文件

- [首頁](https://node-mysql-pool.pardn.io/zh/index.md): 邱敬幃 Pardn Chiu 開發的 Node.js MySQL 連線池，具備讀寫分離、鏈式查詢建構器與慢查詢記錄。
- [快速開始](https://node-mysql-pool.pardn.io/zh/getting-started.md): 安裝 @pardnchiu/mysql-pool、設定 DB_READ_*／DB_WRITE_* 環境變數、呼叫 init() 執行第一筆查詢並關閉連線池。
- [架構](https://node-mysql-pool.pardn.io/zh/architecture.md): MySQLPool 的分層：設定解析、static 查詢建構器、query() 執行器，以及讀寫兩個 mysql2 連線池。
- [讀寫連線池](https://node-mysql-pool.pardn.io/zh/read-write-pools.md): 每個方法使用哪個連線池、table() 的 target 如何決定 SELECT 路由，以及單側未設定資料庫時的行為。
- [建構器狀態](https://node-mysql-pool.pardn.io/zh/builder-state.md): 建構器狀態存於 static 欄位：為何每條鏈都要從 table() 開始、執行後哪些狀態殘留，以及並行使用的條件。
- [欄位與條件](https://node-mysql-pool.pardn.io/zh/select-and-where.md): 以 select() 指定欄位、where() 篩選資料：等值、比較運算子、LIKE 萬用字元、IN 陣列與反引號規則。
- [資料表關聯](https://node-mysql-pool.pardn.io/zh/joins.md): 以 innerJoin()、leftJoin()、rightJoin() 關聯資料表：三參數與四參數寫法，以及欄位反引號規則。
- [排序與分頁](https://node-mysql-pool.pardn.io/zh/sorting-and-pagination.md): 以 orderBy() 排序、limit()／offset() 分頁，並用 total() 在同一筆查詢取得總筆數。
- [新增與更新](https://node-mysql-pool.pardn.io/zh/insert-and-update.md): 以 insert() 新增資料、update() 與 increase() 更新資料，並以白名單嵌入 NOW()、UUID() 等 MySQL 函式。
- [Upsert](https://node-mysql-pool.pardn.io/zh/upsert.md): 以 upsert() 執行 INSERT ... ON DUPLICATE KEY UPDATE：預設 VALUES() 更新、指定更新資料與原生子句。
- [原生 SQL](https://node-mysql-pool.pardn.io/zh/raw-sql.md): 以 read()、write() 或 query() 在指定連線池執行手寫 SQL，並以 ? 佔位符綁定參數。
- [慢查詢記錄](https://node-mysql-pool.pardn.io/zh/slow-query-log.md): 超過 20ms 的查詢會輸出耗時與 SQL：計時範圍、記錄內容與未記錄的資訊。
- [生命週期與關閉](https://node-mysql-pool.pardn.io/zh/shutdown.md): init() 如何驗證連線、close() 如何關閉兩個連線池，以及匯入時註冊的 SIGINT／SIGTERM 處理器。
- [設定](https://node-mysql-pool.pardn.io/zh/configuration.md): 所有 DB_READ_*／DB_WRITE_* 環境變數、MySQLConfig 物件欄位、預設值與 init() 的設定來源優先序。
- [API 參考](https://node-mysql-pool.pardn.io/zh/api-reference.md): MySQLPool 所有公開 static 方法的簽章與回傳值，依生命週期、建構與執行分組。
- [已知限制](https://node-mysql-pool.pardn.io/zh/known-limitations.md): 使用前需留意的行為：不支援交易、NULL 條件、未跳脫的 SQL 片段、共用 static 狀態與行程結束。