kysely-planetscale

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:

# 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:

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,
  }),
})

Type Conversion

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, expect 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,
  }),
})

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:

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)
}

License

MIT License, see LICENSE.