PlanetScale是一个构建在Vitess之上的无服务器数据库平台，兼容MySQL协议，最大特色是支持数据库分支、非阻塞的schema变更以及自动的水平分片扩展。对于Node.js项目来说，接入PlanetScale的方式和连普通MySQL有不少细节差异，比如强制TLS、连接方式更偏向HTTP或者长连接池的取舍等。这篇文章就把Node.js连接和操作PlanetScale的完整流程讲清楚，包括驱动选型、代码封装、分支策略以及常见的坑。
一、PlanetScale的连接原理与凭据准备
PlanetScale对外暴露的是标准MySQL协议端口3306，同时要求所有连接必须走TLS加密。这一点意味着你在Node.js里用原生mysql库直接裸连是行不通的，要么用官方的@planetscale/database驱动，要么在mysql2里显式配置SSL参数。
接入前需要先创建凭据。在PlanetScale控制台中对某个分支执行Connect操作，会生成一组用户名和密码，形如xxxxxxxxxxxx.aws-ps.io的主机地址。凭据默认有过期时间，也可以设置为长期有效，建议在生产环境使用长期凭据并存入环境变量，绝不能硬编码到代码仓库里。
另一个需要理解的概念是分支。PlanetScale的每个database可以派生出多个branch，比如main分支对应生产，dev分支用于开发调试。每个分支有独立的连接地址，所以Node.js应用里切换分支本质上是切换连接配置，这为灰度测试schema变更提供了极大便利。
二、两种驱动方案对比与代码实现
官方推荐的首选方案是@planetscale/database，它底层基于MySQL协议封装，接口是Promise风格，用起来非常轻量。安装命令如下：
npm install @planetscale/database
接着写一个基础的连接与查询封装。把配置抽到独立模块里，方便多环境复用：
// db.js
const { connect } = require('@planetscale/database');
const config = {
host: process.env.PSCALE_HOST,
username: process.env.PSCALE_USERNAME,
password: process.env.PSCALE_PASSWORD,
};
const conn = connect(config);
// 查询多条记录
async function queryUsers(limit = 10) {
const result = await conn.execute(
'SELECT id, name, email FROM users LIMIT ?',
[limit]
);
return result.rows;
}
// 插入记录
async function createUser(name, email) {
const result = await conn.execute(
'INSERT INTO users (name, email) VALUES (?, ?)',
[name, email]
);
return result.insertId;
}
module.exports = { queryUsers, createUser };如果你项目里已经大量使用mysql2的连接池，也可以继续用它接入，只需补上SSL配置。对比来看，@planetscale/database的优势是API简洁、自动处理TLS，适合Serverless函数这种短生命周期场景；mysql2的连接池则更适合常驻的Express服务。两种方式的取舍标准很简单：Serverless部署选前者，传统长驻服务选后者。
// 使用 mysql2 接入 PlanetScale
const mysql = require('mysql2/promise');
const pool = mysql.createPool({
host: process.env.PSCALE_HOST,
user: process.env.PSCALE_USERNAME,
password: process.env.PSCALE_PASSWORD,
database: process.env.PSCALE_DATABASE,
ssl: {
rejectUnauthorized: true,
},
connectionLimit: 10,
});
async function getUserById(id) {
const [rows] = await pool.query(
'SELECT id, name, email FROM users WHERE id = ?',
[id]
);
return rows[0] || null;
}三、错误处理、事务与实战注意事项
PlanetScale不支持传统的SAVEPOINT回滚方式的事务，它的设计哲学是通过schema变更的可逆性来保障安全，DML操作的事务能力取决于是否开启了相关配置。因此不要把强依赖回滚的业务逻辑直接搬过来，涉及多表一致性的场景建议在应用层做补偿处理。
错误处理方面，连接失败最常见的原因是凭据过期和TLS配置缺失。建议对查询函数统一加一层错误捕获，区分连接错误和SQL语法错误：
async function safeQuery(fn, ...args) {
try {
return await fn(...args);
} catch (err) {
if (err.code === 'ETLS' || err.message.includes('TLS')) {
console.error('TLS握手失败，请检查SSL配置');
} else if (err.message.includes('Access denied')) {
console.error('凭据无效或已过期');
}
throw err;
}
}环境变量管理推荐配合dotenv，在.env文件中维护不同分支的凭据，切换开发分支和生产分支时只改配置不改代码。另外要注意，Serverless环境下每次冷启动都会新建连接，如果QPS较高，可以开启PlanetScale的连接池功能来缓解连接风暴。最后，上线前记得用pscale命令行工具演练一次从开发分支到main分支的合并流程，确保schema变更脚本经过pscale diff审查，这样整套流程才算真正落地。
Node.jsPlanetScale数据库连接修改时间：2026-09-17 00:52:32