Meet Waddler
Get started

Get Started with Waddler and Turso

This guide assumes familiarity with:
  • dotenv - package for managing environment variables - read here
  • tsx - package for running TypeScript files - read here
  • turso - SQLite for Production - read here
  • libsql - a fork of SQLite optimized for low query latency, making it suitable for global applications - 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 @libsql/client dotenv
npm i -D tsx

Step 2 - Setup connection variables

Create a .env file in the root of your project and add you Turso database url and auth token:

TURSO_DATABASE_URL=
TURSO_AUTH_TOKEN=
important

If you don’t know your TURSO_DATABASE_URL and TURSO_AUTH_TOKEN values, you can refer to the LibSQL Driver SDK tutorial. Check it out here, then return with all the values generated and added to the .env file

Step 3 - Connect Waddler to the database

Waddler has native support for all @libsql/client driver variations:

@libsql/clientdefaults to node import, automatically changes to web if target or platform is set for bundler, e.g. esbuild --platform=browser
@libsql/client/nodenode compatible module, supports :memory:, file, wss, http and libsql connection protocols
@libsql/client/webmodule for fullstack web frameworks like next, nuxt, astro, etc.
@libsql/client/httpmodule for http and https connection protocols
@libsql/client/wsmodule for ws and wss connection protocols
@libsql/client/sqlite3module for :memory: and file connection protocols
@libsql/client-wasmSeparate experimental package for WASM

default
node
web
http
web sockets
wasm
import { waddler } from 'waddler/libsql';

const sql = waddler({ connection: {
  url: process.env.DATABASE_URL, 
  authToken: process.env.DATABASE_AUTH_TOKEN 
}});

Create a index.ts file in the src directory and initialize the connection:

import 'dotenv/config';
import { waddler } from 'waddler/libsql';

// You can specify any property from the libsql connection options
const sql = waddler({ 
  connection: { 
    url: process.env.TURSO_DATABASE_URL!, 
    authToken: process.env.TURSO_AUTH_TOKEN!
  }
});

If you need to provide your existing driver:

import 'dotenv/config';
import { waddler } from 'waddler/libsql';
import { createClient } from '@libsql/client';

const client = createClient({ 
  url: process.env.TURSO_DATABASE_URL!, 
  authToken: process.env.TURSO_AUTH_TOKEN!
});
const sql = waddler({ client });

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

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/libsql';
  
const sql = waddler({ 
  connection: { 
    url: process.env.TURSO_DATABASE_URL!, 
    authToken: process.env.TURSO_AUTH_TOKEN!
  }
});

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])};
  `.run();
  console.log('New user created!')

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

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

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

main();

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