Meet Waddler
Get started

Get Started with Waddler and D1

This guide assumes familiarity with:
  • dotenv - package for managing environment variables - read here
  • tsx - package for running TypeScript files - read here
  • Cloudflare D1 - Serverless SQL database to query from your Workers and Pages projects - read here
  • wrangler - Cloudflare Developer Platform command-line interface - read here

Basic file structure

This is the basic file structure of the project.

📦 <project root>
 ├ 📂 src
 │   └ 📜 index.ts
 ├ 📜 .env
 ├ 📜 package.json
 └ 📜 tsconfig.json

Step 1 - Install required packages

npm
yarn
pnpm
bun 
npm i waddler  dotenv
npm i -D tsx

Step 2 - Setup wrangler.toml

You would need to have a wrangler.toml file for D1 database and will look something like this:

name = "YOUR PROJECT NAME"
main = "src/index.ts"
compatibility_date = "2022-11-07"
node_compat = true

[[ d1_databases ]]
binding = "DB"
database_name = "YOUR DB NAME"
database_id = "YOUR DB ID"

Step 3 - Connect Waddler to the database

import { waddler } from 'waddler/d1';

export interface Env {
  <BINDING_NAME>: D1Database;
}
export default {
  async fetch(request: Request, env: Env) {
    const sql = waddler({ client: env.<BINDING_NAME> });
  },
};

Step 4 - Create a table

(async () => {
  await sql.unsafe(`create table if not exists users (
    id    integer primary key autoincrement,
    name  text    not null,
    age   integer not null,
    email text    not null unique
    );
  `).run();
})()

Step 5 - Seed and Query the database

import { waddler } from 'waddler/d1';

export interface Env {
  <BINDING_NAME>: D1Database;
}
export default {
  async fetch(request: Request, env: Env) {
    const sql = waddler({ client: env.<BINDING_NAME> });
    const user = [
      'John',
      30,
      '[email protected]',
    ];

    await sql`insert into ${sql.identifier('users')}(${sql.identifier(['name', 'age', 'email'])}) values ${sql.values([user])};`;
    console.log('New user created!')

    const users = await sql`select * from ${sql.identifier('users')};`;
    return Response.json(users);
  },
};

Step 6 - Run index.ts file

To run any TypeScript files, you have several options, but let’s stick with one: using tsx

You’ve already installed tsx, so we can run our queries now

Run index.ts script

npm
yarn
pnpm
bun 
npx tsx src/index.ts
tips

We suggest using bun to run TypeScript files. With bun, such scripts can be executed without issues or additional settings, regardless of whether your project is configured with CommonJS (CJS), ECMAScript Modules (ESM), or any other module format. To run a script with bun, use the following command:

bun src/index.ts

If you don’t have bun installed, check the Bun installation docs