PlanetScale JavaScript 无服务器驱动程序
这是一个兼容 Fetch API 的 PlanetScale 数据库驱动程序,适用于需要 HTTP 外部连接的无服务器和边缘计算平台,如 Cloudflare Workers 或 Vercel Edge Functions。
安装
npm install @planetscale/database
使用方法
import { connect } from '@planetscale/database'
const config = {
host: '<主机>',
username: '<用户名>',
password: '<密码>'
}
const conn = connect(config)
const results = await conn.execute('select 1 from dual where 1=?', [1])
console.log(results)
数据库 URL
可以使用单个数据库 URL 值来配置 host
、username
和 password
值。
import { connect } from '@planetscale/database'
const config = {
url: process.env['DATABASE_URL'] || 'mysql://user:pass@host'
}
const conn = connect(config)
连接工厂
使用 Client
连接工厂类为每个事务或网络请求处理程序创建新的连接。
import { Client } from '@planetscale/database'
const client = new Client({
host: '<主机>',
username: '<用户名>',
password: '<密码>'
})
const conn = client.connection()
const results = await conn.execute('select 1 from dual')
console.log(results)
事务
使用 transaction
函数安全地执行数据库事务。如果在执行事务期间抛出任何未处理的错误,事务将被回滚。
以下示例基于分槽计数器模式。
import { connect } from '@planetscale/database'
const config = {
host: '<主机>',
username: '<用户名>',
password: '<密码>'
}
const conn = connect(config)
const results = await conn.transaction(async (tx) => {
const whenBranch = await tx.execute('INSERT INTO branches (database_id, name) VALUES (?, ?)', [42, "planetscale"])
const whenCounter = await tx.execute('INSERT INTO slotted_counters(record_type, record_id, slot, count) VALUES (?, ?, RAND() * 100, 1) ON DUPLICATE KEY UPDATE count = count + 1', ['branch_count', 42])
return [whenBranch, whenCounter]
})
console.log(results)
与 PlanetScale Boost 一起使用
要启用 PlanetScale Boost,请运行一次 SET @@boost_cached_queries = true
。在同一连接上运行的所有后续查询将使用 Boost(如果该查询模式已启用)。不匹配的查询将正常运行。
要了解更多信息,请访问:使用 PlanetScale Boost 进行查询缓存
const conn = client.connection()
// 为连接启用 Boost
await conn.execute('SET @@boost_cached_queries = true')
const results = await conn.execute('...')
// 可选地,您可以通过设置为 false 来禁用连接的 Boost
await conn.execute('SET @@boost_cached_queries = false')
自定义 fetch 函数
Node.js 18 版本包含内置的全局 fetch
函数。在使用较旧版本的 Node.js 时,您可以提供自定义的 fetch 函数实现。我们推荐使用 undici
包,Node 的内置 fetch 就是基于它的。
import { connect } from '@planetscale/database'
import { fetch } from 'undici'
const config = {
fetch,
host: '<主机>',
username: '<用户名>',
password: '<密码>'
}
const conn = connect(config)
const results = await conn.execute('select 1 from dual')
console.log(results)
要利用 HTTP/2,您可以使用 fetch-h2
垫片。fetch-h2
还支持 Node.js 12+。
import { connect } from '@planetscale/database'
import { context } from 'fetch-h2'
const { fetch, disconnectAll } = context()
const config = {
fetch,
host: '<主机>',
username: '<用户名>',
password: '<密码>'
}
const conn = connect(config)
const results = await conn.execute('select 1 from dual')
console.log(results)
await disconnectAll()
自定义查询参数格式化函数
用 ?
标识的查询替换参数会被转义后的值替换。支持使用冒号前缀的命名替换参数。
const results1 = await conn.execute('select 1 from dual where 1=?', [42])
const results2 = await conn.execute('select 1 from dual where 1=:id', { id: 42 })
提供自定义格式化函数可以使用外部库(如 sqlstring
)覆盖内置的转义功能。
import { connect } from '@planetscale/database'
import SqlString from 'sqlstring'
const config = {
format: SqlString.format,
host: '<主机>',
username: '<用户名>',
password: '<密码>'
}
const conn = connect(config)
const results = await conn.execute('select 1 from dual where 1=?', [42])
console.log(results)
自定义类型转换函数
列值会被转换为相应的 JavaScript 数据类型。可以通过提供 cast
函数来自定义这个过程。
import { connect, cast } from '@planetscale/database'
function inflate(field, value) {
if (field.type === 'INT64' || field.type === 'UINT64') {
return BigInt(value)
}
return cast(field, value)
}
const config = {
cast: inflate,
host: '<主机>',
username: '<用户名>',
password: '<密码>'
}
const conn = connect(config)
您还可以将自定义 cast
函数传递给 execute
。如果存在,这将覆盖由连接设置的 cast
函数:
const result = await conn.execute(
'SELECT userId, SUM(balance) AS balance FROM UserBalanceItem GROUP BY userId',
{},
{
cast: (field, value) => {
if (field.name === 'balance') {
return BigInt(value)
}
return cast(field, value)
}
}
)
行返回值
通过向 execute
传递 as
选项,可以将行作为对象或列值数组返回。
const query = 'select 1 as one, 2 as two where 1=?'
const objects = conn.execute(query, [1], { as: 'object' })
// objects.rows => [{one: '1', two: '2'}]
const arrays = conn.execute(query, [1], { as: 'array' })
// arrays.rows => [['1', '2']]
开发
npm install
npm test
需要帮助?
从 PlanetScale 支持团队 获取帮助,或加入我们的 Discord 社区 或 GitHub 讨论板,看看其他人是如何使用 PlanetScale 的。
许可证
根据 Apache 2.0 许可证分发。详情请参阅 LICENSE 文件。