> [!NOTE]
> 此 README 由 [SKILL](https://github.com/agenvoy/skill-readme-generate) 生成，英文版請參閱 [這裡](https://github.com/pardnio/node-mysql-pool/blob/main/README.md)。

***

<p align="center">
<strong>CHAIN YOUR MYSQL QUERIES ACROSS READ AND WRITE POOLS!</strong>
</p>

<p align="center">
<a href="https://www.npmjs.com/package/@pardnchiu/mysql-pool"><img src="https://img.shields.io/npm/v/@pardnchiu/mysql-pool?include_prereleases&style=for-the-badge" alt="npm"></a>
<a href="https://www.jsdelivr.com/package/npm/@pardnchiu/mysql-pool"><img src="https://img.shields.io/jsdelivr/npm/hm/@pardnchiu/mysql-pool?include_prereleases&style=for-the-badge" alt="Downloads"></a>
<a href="https://www.npmjs.com/package/@pardnchiu/mysql-pool"><img src="https://img.shields.io/npm/l/@pardnchiu/mysql-pool?include_prereleases&style=for-the-badge" alt="License"></a>
</p>

***

> Node.js MySQL 連線池，具備讀寫分離、鏈式查詢建構器與慢查詢記錄

## 目錄

- [功能特點](#功能特點)
- [架構](#架構)
- [授權](#授權)
- [Author](#author)

## 功能特點

> `npm install @pardnchiu/mysql-pool` · [完整文件](https://github.com/pardnio/node-mysql-pool/blob/main/doc/doc.zh.md)

- **讀寫分離雙連線池** — 讀取與寫入各自維護獨立連線池，可由設定物件或 `DB_READ_*`／`DB_WRITE_*` 環境變數初始化，未設定寫入端時自動沿用讀取端設定。
- **鏈式查詢建構器** — 從 `table()` 起串接 select、where、join、orderBy、limit 直到 `get()`，所有值皆以佔位符綁定而非字串拼接。
- **單次查詢取得分頁總數** — `total()` 以 `COUNT(*) OVER()` 視窗函式在同一筆查詢中附帶總筆數，分頁不需再發第二次 COUNT。
- **UPSERT 與 MySQL 函式白名單** — 寫入值命中 `NOW()`、`UUID()` 等白名單函式時原樣嵌入 SQL，其餘一律綁定參數，兼顧便利與安全。
- **慢查詢記錄與優雅關閉** — 超過 20ms 的查詢自動輸出耗時與 SQL，並在 `SIGINT`／`SIGTERM` 時自動釋放連線池。

## 架構

> [完整架構](https://github.com/pardnio/node-mysql-pool/blob/main/doc/architecture.zh.md)

```mermaid
graph TB
    App[應用程式] --> Init["init()"]
    Init --> Cfg[設定解析<br/>設定物件 / 環境變數]
    Cfg --> RP[(讀取連線池)]
    Cfg --> WP[(寫入連線池)]
    App --> QB[鏈式查詢建構器]
    App --> Raw["read() / write()"]
    QB --> Exec["query() 執行器<br/>慢查詢記錄"]
    Raw --> Exec
    Exec --> RP
    Exec --> WP
```

## 授權

本專案採用 [MIT LICENSE](https://github.com/pardnio/node-mysql-pool/blob/main/LICENSE)。

## Author

Just [open an issue](https://github.com/pardnio/node-mysql-pool/issues/new) to share an idea.

<a href="https://github.com/pardnio/node-mysql-pool/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=pardnio/node-mysql-pool&cache_bust=2026-10-07" alt="node-mysql-pool contributors" />
</a>

***

©️ 2025 [邱敬幃 Pardn Chiu](https://www.linkedin.com/in/pardnchiu)