Meet Waddler
Get started

Get Started with Waddler and Vercel Postgres

This guide assumes familiarity with:

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 package

npm
yarn
pnpm
bun 
npm i waddler @vercel/postgres dotenv
npm i -D tsx

Step 2 - Setup connection variables

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

POSTGRES_URL=
warning

It’s important to name the variable POSTGRES_URL for Vercel Postgres.

In the Vercel Postgres storage tab, you can find the .env.local tab and copy the POSTGRES_URL variable

Step 3 - Connect Waddler to the database

import 'dotenv/config';
import { waddler } from 'waddler/vercel-postgres';

const sql = waddler();

If you need to provide your existing driver:

import 'dotenv/config';
import { sql as vercelSql } from '@vercel/postgres';
import { waddler } from 'waddler/vercel-postgres';

const sql = waddler({ client: vercelSql })

Or, if you prefer, provide the connection string yourself.

client connection
pool connection
import 'dotenv/config';
import { createClient } from '@vercel/postgres';
import { waddler } from 'waddler/vercel-postgres';

const client = createClient({ connectionString: process.env['VERCEL_CLIENT_CONNECTION_STRING']! });
await client.connect();

const sql = waddler({ client });

Step 4 - Create a table


(async () => {
  await sql.unsafe(`create table users (
    id integer primary key generated always as identity,
    name varchar(255) not null,
    age integer not null,
    email varchar(255) not null unique
);
  `);
})()

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/vercel-postgres';
  
const sql = waddler();

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

  await sql`insert into ${sql.identifier('users')} values ${sql.values([[sql.default, ...user]])};`;
  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: number;
    name: string;
    age: number;
    email: 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();

Streaming

src/index.ts
import 'dotenv/config';
import { createPool } from '@vercel/postgres';
import { waddler } from 'waddler/vercel-postgres';
import { queryStream } from 'waddler/extensions/pg-query-stream';


async function main() {
  const pool = createPool({ connectionString: process.env['VERCEL_POOL_CONNECTION_STRING']! });

	const sql = waddler({ client: pool, extensions: [queryStream()] });
	
  const stream = sql`select * from users;`.stream();

	console.log('Streaming users one at a time from the database.')
  for await (const user of stream) {
    console.log(user)
    /*
    const user: {
      id: number;
      name: string;
      age: number;
      email: string;
    }
    */		
	}

	await pool.end();
}

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