Waddler

Built by drizzle team

Waddler - is a thin SQL client on top of official DuckDB NodeJS driver with modern API inspired by postgresjs and based on ES6 Tagged Template Strings.

npm
yarn
pnpm
bun 
npm i waddler duckdb
import { waddler } from "waddler";

const sql = waddler({ dbUrl: ":memory:" });

await sql`select 1`;

Waddler has a baked in database pooling which unlocks full potential of hosted DuckDB services like MotherDuck. It does create multiple database instances under the hood and lets you concurrently fetch data from the remote MotherDuck database.

import { waddler } from "waddler";

const sql = waddler({ dbUrl: "md:?…", min: 1, max: 8 }); // MotherDuck connection URL

// fetches concurrently
const res = await Promise.all([
	sql`select 1`,
	sql`select 2`,
]);

Waddler API consists of sql template, sql.identifier, sql.values and sql.raw operators:

SQL template protects you from SQL injections:

await sql`select * from users where id = ${10}`;
select * from users where id = $1;
-- 10 will be passed as a param [10]

SQL identifier lets you conveniently provide schema, table and column names to the query. Those will be automatically properly escaped:

await sql`select * from ${sql.identifier("users")}`;
await sql`select * from ${sql.identifier({ schema: "public", table: "users" })}`;

const userIdColumn = sql.identifier({ schema: "public", table: "users", column: "id", as: "userId"});
await sql`select ${userIdColumn} from "users"`;
select * from "users";
select * from "public"."users";
select * from "public"."users"."id" as "userId" from "users";

SQL values API is designed to help you with insert statements:

const tuples = [["Dan", 27], ["Oleksii", 25]];
await sql`insert into "users" ("name", "age") values ${sql.values(tuples)}`;
insert into "users" ("name", "age") values ('Dan', 27), ('Oleksii', 25);

SQL raw lets you dynamically build SQL by embedding raw strings:

const listUsers = async (filter: string | undefined) => {
  const whereClause = filter ? sql.raw(` where ${filter}`) : sql.raw("");
  return sql`select * from "users"${whereClause}`;
}

await listUsers(`"id" = 10`);
await listUsers(`"name" = 'Dan'`);
await listUsers();
select * from "users" where "id" = 10;
select * from "users" where "name" = 'Dan';
select * from "users";