Meet Waddler
Get started

Get Started with Waddler and Gel

This guide assumes familiarity with:
  • tsx - package for running TypeScript files - read here
  • gel-js - package for querying your Gel database - read here

Waddler has native support for Gel connections with the gel client.

This is the basic file structure of the project.

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

Step 1 - Install and init Gel project

npm
yarn
pnpm
bun 
npx gel project init

Step 2 - Define basic Gel schema

In dbschema/default.esdl file add a basic Gel schema

module default {
    type users {
        name: str;
        required email: str;
        age: int16;
    }
}

There’s no need to manually declare a primary key on your object types.

All object types automatically contain a property id of type UUID that’s required, globally unique, readonly, and has an index on it.

The id is assigned upon creation and cannot be changed.

Step 3 - Push Gel schema to the database

Generate Gel migration file:

gel migration create

Apply Gel migrations to the database

gel migration apply

Now you should have this file structure

📦 <project root>
 ├ 📂 dbschema
 │ ├ 📂 migrations
 │ ├ 📜 default.esdl
 │ └ 📜 scoping.esdl
 ├ 📂 src
 │ └ 📜 index.ts
 ├ 📜 edgedb.toml
 ├ 📜 package.json
 └ 📜 tsconfig.json

Step 4 - Install required packages

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

Step 5 - Setup connection variables

Create a .env file in the root of your project and add your database connection variable:

DATABASE_URL=

Step 6 - Connect Waddler to the database

gel with config
your gel driver
import 'dotenv/config';
import { waddler } from 'waddler/gel';

// You can specify any property from the gel connection options
const sql = waddler({ connection: { dsn: process.env.DATABASE_URL!, tlsSecurity: 'insecure' } });

Step 7 - Query the database

Let’s update the src/index.ts file with queries to create, read, update, and delete users

src/index.ts
import 'dotenv/config';
import { waddler } from 'waddler/undefined';
import { createClient } from 'gel';

const client = createClient({ dsn: process.env.DATABASE_URL!, tlsSecurity: 'insecure' });
const sql = waddler({ client });

async function main() {
    const user = [
      'John',
      30,
      '[email protected]',
    ];

    await sql`
      insert into ${sql.identifier('users')}(${sql.identifier(['name', 'age', 'email'])}) 
      values ${sql.values([user])};
    `;
    //   query: 'insert into "users"("name", "age", "email") values ($1, $2, $3);',
    //   params: [ 'John', 30, '[email protected]' ]
    console.log('New user created!')

    const users = await sql`select * from ${sql.identifier('users')};`;
    console.log('Getting all users from the database:', users)
    /*
    const users: {
      id: string;
      __type__: string;
      age: number;
      email: string;
      name: string;
    }[]
    */

    await sql`update ${sql.identifier('users')} set age = ${31} where email = ${user[2]};`;
    console.log('User info updated!')

    await sql`delete from ${sql.identifier('users')} where email = ${user[2]};`;
    console.log('User deleted!')
}

main();

Step 8 - 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