Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/depot/kysely-planetscale
A Kysely dialect for PlanetScale Serverless
https://github.com/depot/kysely-planetscale
kysely kysely-dialect mysql planetscale vitess
Last synced: 12 days ago
JSON representation
A Kysely dialect for PlanetScale Serverless
- Host: GitHub
- URL: https://github.com/depot/kysely-planetscale
- Owner: depot
- License: mit
- Created: 2022-08-31T23:42:43.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-08-15T15:35:58.000Z (3 months ago)
- Last Synced: 2024-10-25T10:20:52.370Z (16 days ago)
- Topics: kysely, kysely-dialect, mysql, planetscale, vitess
- Language: TypeScript
- Homepage: https://depot.dev/blog/kysely-dialect-planetscale
- Size: 1.64 MB
- Stars: 351
- Watchers: 6
- Forks: 15
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Support: support/banner.jpg
Awesome Lists containing this project
README
# kysely-planetscale
[](https://github.com/depot/kysely-planetscale/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/kysely-planetscale)
A [Kysely](https://github.com/koskimas/kysely) dialect for [PlanetScale](https://planetscale.com/), using the [PlanetScale serverless driver for JavaScript](https://planetscale.com/blog/introducing-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,
}),
})
```
### 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, except for JavaScript Dates, which are converted to MySQL strings. If you [set a `format` function](https://github.com/planetscale/database-js#custom-query-parameter-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](https://github.com/planetscale/database-js#custom-type-casting-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`.