https://github.com/g4brym/workers-qb
Zero dependencies Query Builder for Cloudflare Workers
https://github.com/g4brym/workers-qb
cloudflare cloudflare-d1 cloudflare-workers d1sql javascript nodejs query-builder sql-builder typescript worker workers
Last synced: 17 days ago
JSON representation
Zero dependencies Query Builder for Cloudflare Workers
- Host: GitHub
- URL: https://github.com/g4brym/workers-qb
- Owner: G4brym
- License: mit
- Created: 2022-07-30T17:50:45.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-11-08T19:44:00.000Z (3 months ago)
- Last Synced: 2025-11-08T21:15:44.735Z (3 months ago)
- Topics: cloudflare, cloudflare-d1, cloudflare-workers, d1sql, javascript, nodejs, query-builder, sql-builder, typescript, worker, workers
- Language: TypeScript
- Homepage: https://workers-qb.massadas.com
- Size: 1.65 MB
- Stars: 373
- Watchers: 3
- Forks: 25
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
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](https://workers-qb.massadas.com/)
### Key Differences from ORMs
- 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](https://www.npmjs.com/package/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](https://workers-qb.massadas.com/databases/d1/)
- 💾 [Cloudflare Durable Objects](https://workers-qb.massadas.com/databases/do/)
- 🐘 [PostgreSQL (via node-postgres)](https://workers-qb.massadas.com/databases/postgresql/)
- 🔌 [Bring Your Own Database](https://workers-qb.massadas.com/databases/byodb/)
## Features
### Core Features
- Zero dependencies
- Full TypeScript support
- Schema-aware type inference with autocomplete
- Database schema migrations
- Lazy row loading
### Query Operations
- Table operations (create/drop)
- CRUD operations (insert/update/select/delete)
- Bulk inserts
- JOIN queries
- Subqueries
- Modular SELECT queries
- ON CONFLICT handling
- UPSERT support
## Installation
```bash
npm install workers-qb --save
```
## Usage Examples
### Cloudflare D1
```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,
})
},
}
```
### Cloudflare Durable Objects
```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
}
}
```
### PostgreSQL Integration
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](https://workers-qb.massadas.com/) for detailed information about:
- [Basic Queries](https://workers-qb.massadas.com/basic-queries/)
- [Advanced Queries](https://workers-qb.massadas.com/advanced-queries/)
- [Migrations](https://workers-qb.massadas.com/migrations/)
- [Type Checking](https://workers-qb.massadas.com/type-check/)
- [Database-specific guides](https://workers-qb.massadas.com/databases/d1)
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.