PlanetScale Serverless Driver for JavaScript
A Fetch API-compatible PlanetScale database driver for serverless and edge compute platforms that require HTTP external connections, such as Cloudflare Workers or Vercel Edge Functions
Installation
npm install @planetscale/database
Usage
import { connect } from '@planetscale/database'
const config = {
host: '<host>',
username: '<user>',
password: '<password>'
}
const conn = connect(config)
const results = await conn.execute('select 1 from dual where 1=?', [1])
console.log(results)
Database URL
A single database URL value can be used to configure the host, username, and password values.
import { connect } from '@planetscale/database'
const config = {
url: process.env['DATABASE_URL'] || 'mysql://user:pass@host'
}
const conn = connect(config)
Connection factory
Use the Client connection factory class to create fresh connections for each transaction or web request handler.
import { Client } from '@planetscale/database'
const client = new Client({
host: '<host>',
username: '<user>',
password: '<password>'
})
const conn = client.connection()
const results = await conn.execute('select 1 from dual')
console.log(results)
Transactions
Use the transaction function to safely perform database transactions. If any unhandled errors are thrown during execution of the transaction, the transaction will be rolled back.
The following example is based on the Slotted Counter Pattern.
import { connect } from '@planetscale/database'
const config = {
host: '<host>',
username: '<user>',
password: '<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)
Custom fetch function
Node.js version 18 includes a built-in global fetch function. When using an older version of Node.js, you can provide a custom fetch function implementation. We recommend the undici package on which Node's built-in fetch is based.
import { connect } from '@planetscale/database'
import { fetch } from 'undici'
const config = {
fetch,
host: '<host>',
username: '<user>',
password: '<password>'
}
const conn = connect(config)
const results = await conn.execute('select 1 from dual')
console.log(results)
Custom query parameter format function
Query replacement parameters identified with ? are replaced with escaped values. Named replacement parameters are supported with a colon prefix.
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 })
Providing a custom format function overrides the built-in escaping with an external library, like sqlstring.
import { connect } from '@planetscale/database'
import SqlString from 'sqlstring'
const config = {
format: SqlString.format,
host: '<host>',
username: '<user>',
password: '<password>'
}
const conn = connect(config)
const results = await conn.execute('select 1 from dual where 1=?', [42])
console.log(results)
Custom type casting function
Column values are converted to their corresponding JavaScript data types. This can be customized by providing a cast function.
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: '<host>',
username: '<user>',
password: '<password>'
}
const conn = connect(config)
Development
npm install
npm test
License
Distributed under the Apache 2.0 license. See LICENSE for details.
56 Dec 25, 2022
35 Aug 8, 2022
20 Nov 27, 2022
192 Jan 2, 2023
1.2k Jan 6, 2023
2 Mar 17, 2022
13 Nov 8, 2022
0 Oct 3, 2022
12 Apr 6, 2022
19 Mar 31, 2022
10 Dec 31, 2022
858 Jan 3, 2023
6 Jun 23, 2022
18 Oct 16, 2022
8 Oct 6, 2022
115 Dec 22, 2022
15 Aug 3, 2021
2 Feb 17, 2022
2 Jan 28, 2022