原生 SQL

最後更新 2026-10-07

本頁說明如何以 read()、write()、query() 直接執行手寫 SQL。

三個入口

方法	連線池	未建立連線池時
`read<T>(sql, params?)`	讀取池	拋出 `Read pool connection is not available.`
`write<T>(sql, params?)`	寫入池	拋出 `Write pool connection is not available.`
`query<T>(sql, params?, target?)`	`target`；省略時沿用最近一次 `table()` 的目標	拋出 `read connection is not available.` 或 `write connection is not available.`

三者都經過 query() 執行，因此同樣有慢查詢記錄與連線自動釋放。

參數綁定

以 ? 佔位符傳入值，交給 mysql2 跳脫：

import MySQLPool from "@pardnchiu/mysql-pool";
import type { ResultSetHeader, RowDataPacket } from "mysql2/promise";

try {
  const rows = await MySQLPool.read<RowDataPacket[]>(
    "SELECT id, name FROM users WHERE deleted_at IS NULL AND (role = ? OR role = ?)",
    ["admin", "editor"]
  );

  const header = await MySQLPool.write<ResultSetHeader>(
    "UPDATE users SET last_login = NOW() WHERE id = ?",
    [rows[0].id]
  );

  console.log(header.affectedRows);
} catch (err) {
  console.error("raw query failed:", err);
}

泛型 T 只是型別斷言，回傳值就是 mysql2 query() 結果陣列的第一個元素：SELECT 為資料列陣列，INSERT／UPDATE／DELETE 為 ResultSetHeader。

原生 SQL

三個入口

參數綁定

相關頁面