Zero dependencies Query Builder for Cloudflare Workers
npm install workers-qb
Zero-dependency Query Builder for Cloudflare Workers
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
- Focused on direct SQL access with convenient wrapper methods
- Maintains raw query performance
- Zero dependencies
- Lightweight and Worker-optimized
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
- āļø Cloudflare D1
- š¾ Cloudflare Durable Objects
- š PostgreSQL (via node-postgres)
- š Bring Your Own Database
`bash`
npm install workers-qb --save
`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
// 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,
})
},
}
`
`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
}
getEmployees() {
// DOQB operations are synchronous - no await needed!
return this.#qb
.fetchAll({
tableName: 'employees', // ā Autocomplete
})
.execute()
.results
}
}
`
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
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,
})
},
}
``
Visit our comprehensive documentation for detailed information about:
- Basic Queries
- Advanced Queries
- Migrations
- Type Checking
- Database-specific guides
Contributions are welcome! Please feel free to submit a Pull Request.
This project is licensed under the MIT License - see the LICENSE file for details.