A Kysely dialect for PlanetScale, using the PlanetScale serverless driver for JavaScript.
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:
# 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
You can pass a new instance of PlanetScaleDialect
as the dialect
option when creating a new Kysely
instance:
import {Kysely} from 'kysely'
import {PlanetScaleDialect} from 'kysely-planetscale'
const db = new Kysely<Database>({
dialect: new PlanetScaleDialect({
host: '<host>',
username: '<user>',
password: '<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:
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<Database>({
dialect: new PlanetScaleDialect({
url: process.env.DATABASE_URL,
fetch,
}),
})
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.
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:
import {Kysely} from 'kysely'
import {PlanetScaleDialect} from 'kysely-planetscale'
import SqlString from 'sqlstring'
const db = new Kysely<Database>({
dialect: new PlanetScaleDialect({
url: process.env.DATABASE_URL,
format: SqlString.format,
}),
})
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:
import {cast} from '@planetscale/database'
import {Kysely} from 'kysely'
import {PlanetScaleDialect} from 'kysely-planetscale'
import SqlString from 'sqlstring'
const db = new Kysely<Database>({
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)
}
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.
import {Kysely} from 'kysely'
import {PlanetScaleDialect} from 'kysely-planetscale'
const db = new Kysely<Database>({
dialect: new PlanetScaleDialect({
url: process.env.DATABASE_URL,
useSharedConnection: true,
}),
})
MIT License, see LICENSE
.