workers-qb

Zero-dependency Query Builder for Cloudflare Workers

Overview

workers-qb is a lightweight query builder designed specifically for Cloudflare Workers. It provides a simple, standardized interface while maintaining the performance benefits of raw queries over traditional ORMs.

📚 Read the full documentation

$3

- Focused on direct SQL access with convenient wrapper methods
- Maintains raw query performance
- Zero dependencies
- Lightweight and Worker-optimized

AI Skills

workers-qb provides AI coding assistant skills to help you write queries faster. Install them using npx skills:

``bash
npx skills install G4brym/workers-qb
`

Available skills:
- write-sql-queries - Comprehensive guide for writing SELECT, INSERT, UPDATE, DELETE queries

Supported Databases

- ☁️ Cloudflare D1
- 💾 Cloudflare Durable Objects
- 🐘 PostgreSQL (via node-postgres)
- 🔌 Bring Your Own Database

Features

$3

`bash
npm install workers-qb --save
`

Usage Examples

$3

`typescript
import { D1QB } from 'workers-qb'

// Define your database schema for full type safety
type Schema = {
employees: {
id: number
name: string
role: string
level: number
active: boolean
}
}

export interface Env {
DB: D1Database
}

export default {
async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise {
const qb = new D1QB(env.DB)

// Using object syntax - table names and fields autocomplete!
const employeeList = await qb
.fetchAll({
tableName: 'employees', // ✓ Autocomplete
fields: ['name', 'role', 'level'], // ✓ Autocomplete
where: {
conditions: 'active = ?1',
params: [true],
},
})
.execute()

// Using method chaining
const employeeListModular = await qb
.select('employees')
.where('active = ?', true)
.all()

// Result type is automatically inferred!
return Response.json({
activeEmployees: employeeList.results?.length || 0,
})
},
}
`

$3

`typescript
import { DOQB } from 'workers-qb'

type Schema = {
employees: {
id: number
name: string
role: string
}
}

export class MyDurableObject extends DurableObject {
#qb: DOQB

constructor(ctx: DurableObjectState, env: Env) {
super(ctx, env)
this.#qb = new DOQB(ctx.storage.sql)
}

getEmployees() {
// DOQB operations are synchronous - no await needed!
return this.#qb
.fetchAll({
tableName: 'employees', // ✓ Autocomplete
})
.execute()
.results
}
}
`

$3

First, install the required PostgreSQL client:
`bash
npm install pg --save
`

Enable Node compatibility in wrangler.toml:
`toml
node_compat = true
`

Example usage:
`typescript
import { PGQB } from 'workers-qb'
import { Client } from 'pg'

type Schema = {
employees: {
id: number
name: string
active: boolean
}
}

export interface Env {
DB_URL: string
}

export default {
async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise {
const qb = new PGQB(new Client(env.DB_URL))
await qb.connect()

const fetched = await qb
.fetchOne({
tableName: 'employees', // ✓ Autocomplete
fields: 'count(*) as count',
where: {
conditions: 'active = ?1',
params: [true],
},
})
.execute()

// Important: Close the connection
ctx.waitUntil(qb.close())

return Response.json({
activeEmployees: fetched.results?.count || 0,
})
},
}
``

Documentation

Visit our comprehensive documentation for detailed information about:

- Basic Queries
- Advanced Queries
- Migrations
- Type Checking
- Database-specific guides

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.