Node.js mysql 驅動中文文檔精華：連接、查詢、轉義、流控與錯誤處理

Node.js mysql 驅動中文文檔精華：連接、查詢、轉義、流控與錯誤處理

安裝

npm install mysql           # 穩定版
npm install felixge/node-mysql  # 最新版

建立連接（推薦顯式 connect）

const mysql = require('mysql');
const conn = mysql.createConnection({
  host: 'example.org',
  user: 'bob',
  password: 'secret',
  database: 'mydb'
});
conn.connect(err => {
  if (err) return console.error('連接失敗:', err.stack);
  console.log('已連接，threadId:', conn.threadId);
});

連接選項速查

關閉連接

• conn.end(cb)：等待進行中查詢完成後優雅關閉。
• conn.destroy()：立即強制斷開，無回調。

查詢三種形式

// 1. 簡單 SQL + 回調
conn.query('SELECT * FROM books WHERE author = "David"', (err, rows, fields) => { ... });

// 2. 佔位符 ? 防注入
conn.query('SELECT * FROM books WHERE author = ?', ['David'], (err, rows, fields) => { ... });

// 3. 選項對象（超時、類型轉換等）
conn.query({ sql: 'SELECT * FROM books WHERE author = ?', timeout: 40000, values: ['David'] }, (err, rows, fields) => { ... });

值轉義（防 SQL 注入）

// 手動轉義
const sql = 'SELECT * FROM users WHERE id = ' + conn.escape(userId);

// 佔位符自動轉義（推薦）
conn.query('SELECT * FROM users WHERE id = ?', [userId], cb);

// 對象語法自動展開
const post = {id: 1, title: 'Hello MySQL'};
conn.query('INSERT INTO posts SET ?', post, cb);
// 生成: INSERT INTO posts SET `id`=1, `title`='Hello MySQL'

標識符轉義（表名/列名）

// 手動
const sql = 'SELECT * FROM posts ORDER BY ' + conn.escapeId(sorter);

// 佔位符 ??
conn.query('SELECT ?? FROM ?? WHERE id = ?', [['username','email'], 'users', userId], cb);
// 生成: SELECT `username`,`email` FROM `users` WHERE id = 1

自定義查詢格式化

conn.config.queryFormat = (query, values) => {
  if (!values) return query;
  return query.replace(/:(\w+)/g, (_, key) => values.hasOwnProperty(key) ? conn.escape(values[key]) : _);
};
conn.query("UPDATE posts SET title = :title", { title: "Hello MySQL" });

常用返回元數據

• result.insertId：自增主鍵 ID（大數啟用 supportBigNumbers 以字符串讀取）。
• result.affectedRows：影響行數（INSERT/UPDATE/DELETE）。
• result.changedRows：實際改變的行數（不含值未變的行）。
• conn.threadId：連接線程 ID。

多語句查詢（multipleStatements: true）

conn.query('SELECT 1; SELECT 2', (err, results) => {
  // results[0] → [{1:1}], results[1] → [{2:2}]
});
// 事件流模式
conn.query('SELECT 1; SELECT 2')
  .on('fields', (fields, index) => { ... })
  .on('result', (row, index) => { ... });

錯誤時 err.index 指示第幾條語句出錯，後續語句停止執行。

錯誤處理體系

• 所有錯誤均為 JS Error 實例，含 err.code（MySQL 錯誤碼/Node 錯誤碼/內部協議碼）與 err.fatal（是否終結連接）。
• 致命錯誤：掛起所有待定回調，觸發 connection.on('error')。
• 普通錯誤：僅傳遞給所屬回調，不影響後續查詢。
• 無監聽器的 error 事件：會拋出堆棧並殺死進程，**務必綁定 conn.on('error', ...)**。

// 統一錯誤監聽
conn.on('error', err => console.error('DB Error:', err.code));

最佳實踐清單

1. 生產環境使用連接池 mysql.createPool()，而非單連接。
2. 全量使用佔位符 ?/??，杜絕字符串拼接。
3. 啟用 supportBigNumbers + bigNumberStrings 處理 BIGINT/DECIMAL。
4. 綁定 error 事件防止進程意外退出。
5. 超時控制：查詢級 timeout 選項 + 連接級 connectTimeout。