database-js

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']]