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

Key Differences from ORMs

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

Supported Databases

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

Features

Core Features

• Zero dependencies
• Full TypeScript support
• Database schema migrations
• Type checking for data reads
• 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

npm install workers-qb --save

Usage Examples

Cloudflare D1

import { D1QB } from 'workers-qb'

export interface Env {
  DB: D1Database
}

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

    type Employee = {
      name: string
      role: string
      level: number
    }

    // Using object syntax
    const employeeList = await qb
      .fetchAll<Employee>({
        tableName: 'employees',
        where: {
          conditions: 'active = ?1',
          params: [true],
        },
      })
      .execute()

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

    return Response.json({
      activeEmployees: employeeList.results?.length || 0,
    })
  },
}

Cloudflare Durable Objects

import { DOQB } from 'workers-qb'

export class DOSRS extends DurableObject {
  getEmployees() {
    const qb = new DOQB(this.ctx.storage.sql)
    
    return qb
      .fetchAll({
        tableName: 'employees',
      })
      .execute()
      .results
  }
}

PostgreSQL Integration

First, install the required PostgreSQL client:

npm install pg --save

Enable Node compatibility in wrangler.toml:

node_compat = true

Example usage:

import { PGQB } from 'workers-qb'
import { Client } from 'pg'

export interface Env {
  DB_URL: string
}

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

    const fetched = await qb
      .fetchOne({
        tableName: 'employees',
        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.