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

AI Skills

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

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

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

npm install workers-qb --save

Usage Examples

Cloudflare D1

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<Response> {
    const qb = new D1QB<Schema>(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

import { DOQB } from 'workers-qb'

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

export class MyDurableObject extends DurableObject {
  #qb: DOQB<Schema>

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env)
    this.#qb = new DOQB<Schema>(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:

npm install pg --save

Enable Node compatibility in wrangler.toml:

node_compat = true

Example usage:

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<Response> {
    const qb = new PGQB<Schema>(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.