!Banner Image

kysely-planetscale

!Powered by TypeScript

A Kysely dialect for PlanetScale, using the PlanetScale serverless driver for JavaScript.

Installation

You should install both kysely and @planetscale/database with kysely-planetscale, as they are both required peer dependencies. You can install them with your favorite package manager:

``bash


with pnpm

pnpm add kysely-planetscale kysely @planetscale/database

with yarn

yarn add kysely-planetscale kysely @planetscale/database

with npm

npm install kysely-planetscale kysely @planetscale/database
`

Usage

You can pass a new instance of PlanetScaleDialect as the dialect option when creating a new Kysely instance:

`typescript
import {Kysely} from 'kysely'
import {PlanetScaleDialect} from 'kysely-planetscale'

const db = new Kysely({
dialect: new PlanetScaleDialect({
host: '',
username: '',
password: '',
}),
})
`

PlanetScaleDialect accepts the same options as connect({...}) from @planetscale/database, so for instance if you are using Node.js and need to provide a fetch implementation:

`typescript
import {Kysely} from 'kysely'
import {PlanetScaleDialect} from 'kysely-planetscale'
import {fetch} from 'undici'

// Connect using a DATABASE_URL, provide a fetch implementation
const db = new Kysely({
dialect: new PlanetScaleDialect({
url: process.env.DATABASE_URL,
fetch,
}),
})
`

$3

PlanetScaleDialect provides built-in support for converting JavaScript Dates to and from DATETIME and TIMESTAMP columns, as Kysely's generated types expect. However, you can override or extend this behavior by providing a custom format or cast function to override the defaults.

#### Custom format function

PlanetScaleDialect passes all parameters to @planetscale/database unmodified, except for JavaScript Dates, which are converted to MySQL strings. If you set a format function, you can override this behavior:

`typescript
import {Kysely} from 'kysely'
import {PlanetScaleDialect} from 'kysely-planetscale'
import SqlString from 'sqlstring'

const db = new Kysely({
dialect: new PlanetScaleDialect({
url: process.env.DATABASE_URL,
format: SqlString.format,
}),
})
`

#### Custom cast function

PlanetScaleDialect automatically type-casts DATETIME and TIMESTAMP to JavaScript Dates. If you'd prefer to customize this behavior, you can pass a custom cast function:

`typescript
import {cast} from '@planetscale/database'
import {Kysely} from 'kysely'
import {PlanetScaleDialect} from 'kysely-planetscale'
import SqlString from 'sqlstring'

const db = new Kysely({
dialect: new PlanetScaleDialect({
url: process.env.DATABASE_URL,
cast: inflate,
}),
})

function inflate(field, value) {
if (field.type === 'INT64' || field.type === 'UINT64') {
return BigInt(value)
}
return cast(field, value)
}
`

#### Experimental: useSharedConnection

As of version 1.3.0, PlanetScaleDialect supports using a shared @planetscale/database connection for all non-transaction queries, to improve query performance. This option is not enabled by default, but can be enabled by setting the useSharedConnection option to true. Transaction queries will always run using their own connection.

This is an experimental feature, and may be removed in a future version.

`typescript
import {Kysely} from 'kysely'
import {PlanetScaleDialect} from 'kysely-planetscale'

const db = new Kysely({
dialect: new PlanetScaleDialect({
url: process.env.DATABASE_URL,
useSharedConnection: true,
}),
})
`

License

MIT License, see LICENSE`.