@oselvar/kysely-cloudflare

Kysely dialects for Cloudflare D1 in three flavors: the Workers binding, Durable Object SQLite storage, and the REST API.

Which dialect should I use?

| Where your code runs | Dialect | Import | Transactions | |---------------------------------------|--------------------|-------------------------------------------|-------------------------------------------| | Worker with a D1 binding | D1WorkersDialect | @oselvar/kysely-cloudflare/workers | db.transaction() (buffered batch) | | Durable Object with SQLite storage | DOSqliteDialect | @oselvar/kysely-cloudflare/do | withDoTransaction(...) (sync closure) | | Anywhere else (CI, Node scripts, dev) | D1ApiDialect | @oselvar/kysely-cloudflare/api | Not supported |

Install

pnpm add @oselvar/kysely-cloudflare kysely

Optional peer (only when using /workers or /do):

pnpm add -D @cloudflare/workers-types

Quick start

D1WorkersDialect — inside a Worker with a D1 binding

import { Kysely } from 'kysely'
import { D1WorkersDialect } from '@oselvar/kysely-cloudflare/workers'

export default {
  async fetch(req: Request, env: { DB: D1Database }) {
    const db = new Kysely<Database>({ dialect: new D1WorkersDialect({ database: env.DB }) })
    return Response.json(await db.selectFrom('pets').selectAll().execute())
  },
}

DOSqliteDialect — inside a Durable Object

import { DurableObject } from 'cloudflare:workers'
import { Kysely } from 'kysely'
import { DOSqliteDialect, withDoTransaction } from '@oselvar/kysely-cloudflare/do'

export class PetsDO extends DurableObject {
  private db: Kysely<Database>

  constructor(state: DurableObjectState, env: Env) {
    super(state, env)
    this.db = new Kysely<Database>({ dialect: new DOSqliteDialect({ sql: state.storage.sql }) })
  }

  async fetch() {
    return Response.json(await this.db.selectFrom('pets').selectAll().execute())
  }
}

D1ApiDialect — from anywhere (scripts, CI, Node)

import { Kysely } from 'kysely'
import { D1ApiDialect } from '@oselvar/kysely-cloudflare/api'

const db = new Kysely<Database>({
  dialect: new D1ApiDialect({
    clientOptions: { apiToken: process.env.CLOUDFLARE_API_TOKEN },
    accountId: process.env.CLOUDFLARE_ACCOUNT_ID!,
    databaseId: process.env.CLOUDFLARE_DATABASE_ID!,
  }),
})
console.table(await db.selectFrom('pets').selectAll().execute())

Transactions

D1WorkersDialect — buffered batch

D1's binding has no native BEGIN/COMMIT API. db.transaction().execute() buffers prepared statements and dispatches them as one atomic database.batch() on commit:

await db.transaction().execute(async (trx) => {
  await trx.insertInto('pets').values({ name: 'Rex', species: 'dog', birth_date: '2024-01-01' }).execute()
  await trx.insertInto('pets').values({ name: 'Spot', species: 'dog', birth_date: '2023-06-12' }).execute()
})

Caveat: SELECTs inside the transaction return empty rows until commit (nothing has been sent to D1 yet). Build your transaction body around writes only, or read first and write inside the transaction.

DOSqliteDialect — withDoTransaction

db.transaction() is intentionally not supported on Durable Objects, because Kysely's async/stepwise transaction model can't be safely bridged to DO's synchronous state.storage.transactionSync(closure) primitive — see kysely-durable-objects for the long version.

Use withDoTransaction instead. The closure is synchronous; throwing rolls back. Kysely query builders still work — they're compiled and executed on the fly inside the closure:

import { withDoTransaction } from '@oselvar/kysely-cloudflare/do'

withDoTransaction(state.storage, db, (txn) => {
  txn.run(db.insertInto('pets').values({ name: 'Rex', species: 'dog', birth_date: '2024-01-01' }))
  const dogs = txn.all<Pet>(db.selectFrom('pets').selectAll().where('species', '=', 'dog'))
  if (dogs.length > 5) {
    txn.run(db.deleteFrom('pets').where('species', '=', 'dog'))
  }
})

D1ApiDialect — not supported

The D1 REST API does not support transactions. db.transaction() throws.

Example app

A deployable Wrangler app under example/ exercises all three dialects:

• GET /pets — uses D1WorkersDialect against a D1 binding
• GET /pets-do — uses DOSqliteDialect and withDoTransaction inside a Durable Object
• pnpm --filter example query — uses D1ApiDialect from your terminal

See example/wrangler.toml for the deploy walkthrough.

Related libraries

• kysely-d1 — the original D1 binding dialect for Kysely; does not batch transactions.
• kysely-durable-objects — same DO transaction safety design (raw-SQL closure); we additionally provide a Kysely-aware DoTxn so query-builder type-safety survives inside the transaction.
• kysely-d1-api — original inspiration for D1ApiDialect.
• workers-qb — non-Kysely query builder; covers D1, DO SQLite, PostgreSQL, BYODB.
• drizzle-orm — alternative TypeScript ORM with first-class D1/DO support.

License

MIT