详细介绍在Node.js环境中使用MySQL驱动库通过createConnection直接连接MySQL数据库的完整步骤,包含环境准备、连接建立、SQL查询执行、异常捕获与连接释放等实用操作。
Node.js环境中怎么使用MySQL库直接连接数据库
时间:2026-11-22
浏览:543
文章目录
createConnection() 方法传入连接配置,显式触发网络握手后即可执行 SQL 查询。本文将从项目环境准备、直接连接配置、参数化数据读写、时序交互机制到常见连接异常的排查,完整介绍单连接直连的具体操作与核心要点。
一、环境准备与驱动库安装
在 Node.js 中操作 MySQL,本身无需依赖额外的全局服务插件,只需在应用工程中引入符合 MySQL 协议的纯 JavaScript 驱动客户端。目前社区中最主流且推荐的选择是 mysql2 库。相比早期的原版 mysql 库,mysql2 完全向后兼容其 API,支持 MySQL 8+ 默认的 caching_sha2_password 认证方式,并具备更高的执行性能与内置 Promise 支持。
1.1 初始化工程并安装依赖
打开终端,进入你的 Node.js 项目根目录。若尚未初始化 package.json,可先执行初始化命令,随后安装驱动包:
# 初始化 Node.js 工程(若已存在 package.json 可跳过)
npm init -y
# 安装 MySQL 驱动包
npm install mysql2
执行完毕后,驱动包将自动存放于当前目录的 node_modules 中,并在 package.json 的 dependencies 中登记。
1.2 确认 MySQL 服务端就绪状态
在编写代码前,请确保目标 MySQL 实例处于正常运行状态,并具备以下基础连接要素:
- 主机地址(Host):本地通常为
localhost或127.0.0.1,远程则为服务器 IP 或域名。 - 服务端口(Port):MySQL 默认端口为
3306。 - 认证凭据:拥有目标数据库读写权限的用户名(如
root或业务专用账号)和密码。 - 目标数据库(Database):需连接的具体数据库名称,确保该库已预先执行
CREATE DATABASE创建。
二、核心操作:创建直接连接与执行查询
所谓“直接连接”,是指在 Node.js 应用进程与 MySQL 实例之间建立一条独立、专属的 TCP Socket 通信通道。该连接具有明确的生命周期:由应用主动发起握手建立,按序执行收发报文,并在使用完毕后显式断开。
2.1 编写基础直连脚本
在项目根目录下新建一个名为 direct-connect.js 的文件,写入以下完整代码:
// 引入 mysql2 驱动库
const mysql = require('mysql2');
// 1. 创建直接连接实例并指定配置选项
const connection = mysql.createConnection({
host: 'localhost', // 数据库服务器地址
port: 3306, // 数据库服务端口,默认 3306
user: 'root', // 数据库登录用户名
password: 'your_password', // 数据库登录密码
database: 'test_db', // 需直连的目标数据库
connectTimeout: 10000 // 连接超时时间(毫秒)
});
// 2. 显式发起网络握手连接
connection.connect((err) => {
if (err) {
console.error('[连接失败] 无法与 MySQL 建立 Socket:', err.message);
return;
}
console.log(`[连接成功] 已接入 MySQL 服务端,当前分配线程 ID: ${connection.threadId}`);
// 3. 执行数据查询测试
const testSql = 'SELECT NOW() AS currentTime, VERSION() AS dbVersion';
connection.query(testSql, (queryErr, results) => {
if (queryErr) {
console.error('[查询失败] SQL 执行异常:', queryErr.message);
} else {
console.log('[查询结果] 服务端时间与版本:', results[0]);
}
// 4. 查询完毕后优雅释放连接
connection.end((closeErr) => {
if (closeErr) {
console.error('[关闭失败] 连接释放异常:', closeErr.message);
} else {
console.log('[连接关闭] TCP 链路已安全释放,会话正常退出。');
}
});
});
});
connection.query() 时,驱动内部会在尚未建立连接时自动执行隐式连接,但推荐初学者显式调用 connection.connect()。这样可以在业务 SQL 触发之前,尽早捕获网络拒绝、认证错误或防火墙阻断等基础设施层面的问题。
2.2 运行并验证输出
在终端中执行该脚本:
node direct-connect.js
连接成功后的控制台预期输出示例:
[连接成功] 已接入 MySQL 服务端,当前分配线程 ID: 18
[查询结果] 服务端时间与版本: { currentTime: 2026-11-12T00:03:15.000Z, dbVersion: '8.0.36' }
[连接关闭] TCP 链路已安全释放,会话正常退出。
三、报文流转:直连模式底层通信时序与原理
当执行上述 JavaScript 代码时,底层驱动与 MySQL 服务端之间经历了完整的网络协议交互流程。理解该协议时序有助于在排查偶发超时或丢包问题时准确锁定阶段。
通信过程主要分为四个阶段:
- 物理传输层握手:Node.js 底层
net.Socket向目标主机和端口发送 TCP SYN 包,完成三次握手。 - MySQL 协议鉴权:MySQL 服务端首先主动下发握手初始化报文(包含协议号、服务器版本及鉴权所用的随机加盐 Salt);客户端根据指定的密码学算法计算哈希值,打包用户名和数据库名回传响应;服务端校验通过后回传
OkPacket。 - SQL 指令投递与结果返回:调用
connection.query()时,驱动将 SQL 语句封装为COM_QUERY协议报文发送。服务端解析执行后,先传输字段元数据包(Column Definition),随后连续回传数据行包(Row Data Packet),最后返回结束标志。 - 会话退出:调用
connection.end()发送COM_QUIT报文,服务端随即清理其内部对应线程上下文,双方经过 TCP FIN 四次挥手释放套接字。
四、数据操作与安全防护规范
在直接连接中执行真实的增删改查业务时,必须严格遵守参数化查询规范,杜绝一切由于字符拼接产生的安全隐患。
4.1 使用占位符执行参数化操作
直接在 SQL 字符串中通过 + 或 ES6 模板字符串拼接外部变量(如表单输入或 URL 参数)极易诱发 SQL 注入攻击。MySQL 驱动支持使用问号 ? 作为占位符,由底层驱动对传入参数做转义和类型编码:
// 插入数据:使用问号占位符
const insertSql = 'INSERT INTO users (username, email, age) VALUES (?, ?, ?)';
const userParams = ['张三', 'zhangsan@example.com', 26];
connection.query(insertSql, userParams, (err, result) => {
if (err) throw err;
console.log('新增成功,自动生成的自增 ID 为:', result.insertId);
});
// 条件查询:参数数组必须与占位符数量及顺序严格对应
const selectSql = 'SELECT id, username, email FROM users WHERE age >= ? AND status = ?';
connection.query(selectSql, [18, 'active'], (err, rows) => {
if (err) throw err;
console.log('查询到的活跃成年用户列表:', rows);
});
`SELECT * FROM users WHERE name = '${userName}'` 的代码!即使在本地单次脚本中,也应养成使用占位符 ? 的工程习惯。
五、直接连接与连接池的适用场景对比
在实际项目中,开发者经常在 createConnection()(直接单连接)与 createPool()(连接池)之间抉择。直接连接机制轻巧,但其能力模型受限于单一 Socket 链路。
| 对比维度 | 直接连接 (createConnection) | 连接池模式 (createPool) |
|---|---|---|
| 连接数特征 | 严格 1:1 物理 TCP Socket | 管理一组可配置上限的连接集合 (如 10 条) |
| 并发吞吐 | 单连接内查询串行排队,无法同时处理多条请求 | 多个请求由不同闲置连接并行处理,支持积压排队 |
| 生命周期管理 | 需开发者手动调用 connect() 与 end() |
自动创建、闲置保活,借出后自动收回 |
| 断线恢复 | 网络抖动或服务端断开后即失效,不具备自动重连 | 自动剔除异常连接,遇到新请求按需重新建立 |
| 最佳实践场景 | 离线数据脚本、数据库迁移工具、自动化命令行 (CLI) | Express / Koa / Nest 等高并发 Web 接口与持续运行服务 |
六、常见连接异常排查与稳健性保障
使用直接连接时,由于缺乏连接池的容错包装,各类网络或权限错误会直接暴露在业务层。掌握常见错误码能快速定位故障根因。
6.1 常见错误诊断与解决方案
-
ECONNREFUSED(连接被拒绝):
通常表示目标主机上没有程序在监听指定的端口。首先排查 MySQL 服务是否处于运行状态;其次确认
port是否误填;若连接远程服务器,需检查 MySQL 的配置文件(my.cnf)中bind-address是否限制为127.0.0.1,以及服务器云防火墙安全组是否放行 3306 端口。 -
ER_ACCESS_DENIED_ERROR(访问被拒绝):
表示网络连通但身份核验失败。请核查用户名、密码是否包含特殊字符被转义,并确认 MySQL 中该用户的
Host白名单。若客户端在另一台机器,以root@localhost授权的用户将无法远程登入,必须在数据库执行CREATE USER 'user'@'%' IDENTIFIED BY '...';赋予远程访问权。 -
PROTOCOL_CONNECTION_LOST(连接意外丢失):
直接连接若长时间保持空闲,一旦超过 MySQL 的
wait_timeout(默认通常为 28800 秒,但在很多云数据库或测试环境中可能仅设置为数十秒),服务端会主动切断 Socket。对于长时间常驻运行的进程,应监听connection.on('error', ...)事件并在断线时进行重连处理,或改用连接池管理。
6.2 正确释放连接:end() 与 destroy() 的差异
在直连模式中,任务完成后必须显式关闭连接。关闭方法有两种:
connection.end():推荐使用。这属于优雅退出(Graceful Shutdown),驱动会等待当前正在排队执行的所有查询全部完毕并接收到响应后,才向服务端发送COM_QUIT终止会话。connection.destroy():立即掐断底层 TCP Socket,丢弃所有尚未完成的回调。仅在遇到进程退出信号、致命异常或超时需要紧急中止时调用。
七、总结
在 Node.js 中使用 MySQL 驱动直接连接数据库,核心在于理清连接配置、掌握 createConnection() 的生命周期,并在执行 SQL 时贯彻使用 ? 占位符的安全标准。对于单次执行的脚本、数据导入导出程序或工具链任务,直接连接以其简单直观、开销低廉的特点成为首选;而在面对并发请求的 Web 服务时,则建议基于相同的配置思想无缝切换到连接池架构。
实用工具推荐
绿化、压缩、噪点和虚拟水印,自由调节做旧程度。
选择画质和输出格式,预览压缩前后的大小。