Waddler Documentation

Waddler is a thin SQL client wrapper that provides a modern API inspired by postgresjs. It is based on ES6 Tagged Template Strings, allowing you to interact with databases using a unified sql template tag instead of learning a specific API for every database client.

Key characteristics:

• Dialect Agnostic: It unifies communication with any database dialect or driver supported by Drizzle (e.g., PostgreSQL, MySQL, LibSQL).
• No Mapping/Parsing: It does not perform complex query building or object-relational mapping; it simply facilitates communication via TCP or HTTP-based clients.
• Security: It prevents SQL injection by automatically converting template literals into parameterized queries (e.g., converting ${10} to $1 and [10]).

To use Waddler, import the driver-specific entry point and initialize it using the waddler function. You can provide a dbUrl via an options object or use default configuration.

Supported driver entry points include:

• waddler/node-postgres
• waddler/mysql2
• waddler/libsql

import { waddler } from "waddler/node-postgres";

const sql = waddler({ dbUrl: process.env.DB_URL });
// or
const sql = waddler();

Waddler provides a unified interface for various TypeScript-compatible database drivers. Instead of a single entry point, you import the waddler function from a driver-specific subpath. Supported drivers include node-postgres, mysql2, and libsql.

import { waddler } from "waddler/node-postgres";
import { waddler } from "waddler/mysql2";
import { waddler } from "waddler/libsql";

const sql = waddler({ dbUrl: process.env.DB_URL });

To use Waddler with a Cloudflare D1 database, use the waddler function. This function accepts a client (the D1 database instance) and an optional config object of type WaddlerConfig. It returns a D1SQL instance which provides the SQL template tag and helper functions for executing queries.

import { waddler } from 'waddler/sqlite/d1';

// Assuming 'env.DB' is your Cloudflare D1 database instance
const sql = waddler({ client: env.DB });

// Usage example:
const results = await sql`SELECT * FROM users WHERE id = ${1}`;

To use Waddler with a Durable Object storage client, call the waddler function. This returns a DurableSqliteSQL template function used to construct SQL queries. You can optionally provide a WaddlerConfig object to configure logging behavior.

Configuration

• config.logger:
  • true: Enables the DefaultLogger.
  • false: Disables logging.
  • Logger instance: Provides a custom logger implementation.

import { waddler } from 'waddler';

const sql = waddler({
  client: myDurableObjectStorage,
  config: { logger: true }
});

Waddler uses tagged template strings to execute queries. The API is promisified, allowing you to await the result of the sql tag directly.

Basic Query

const result = await sql`select * from users`;

Parameterized Queries (SQL Injection Protection)

Pass variables directly into the template string. Waddler handles the parameterization automatically.

await sql`select * from users where id = ${10}`;

Typed Queries

You can pass a generic type to the sql tag to define the shape of the returned rows.

await sql<{ id: number, name: string }>`select * from users`;

const result = await sql`select * from users`;

// with types
await sql<{ id: number, name: string }>`select * from users`;

Waddler supports asynchronous iteration over query results through .stream() and .chunked(size) methods. .stream() allows you to iterate over individual rows, while .chunked(n) allows you to iterate over batches of n rows.

// Streaming individual rows
const stream = sql`select * from users`.stream();
for await (const row of stream) {
  console.log(row);
}

// Chunking results into batches of 2
const chunked = sql`select * from users`.chunked(2);
for await (const chunk of chunked) {
  console.log(chunk);
}

Waddler provides built-in support for processing large result sets through streaming and chunking.

Streaming

Use .stream() to get an async iterator that yields rows one by one.

const stream = sql`select * from users`.stream();
for await (const row of stream) {
  console.log(row);
}

Chunking

Use .chunked(size) to get an async iterator that yields arrays of rows of a specified size.

const chunked = sql`select * from users`.chunked(2);
for await (const chunk of chunked) {
  console.log(chunk);
}

The sql.values() method allows you to prepare arrays of data for bulk operations or complex inserts, ensuring they are correctly formatted for the template tag.

const values = sql.values([["Dan", "dan@acme.com", 25]]);
await sql`insert into "users" ("name", "email", "age") values ${values}`;
// Resulting SQL: insert into "users" ("name", "email", "age") values ('Dan', 'dan@acme.com', 25);