Examples

This section describes runnable examples for Drizzle DuckDB. All examples live in /example and run with Bun.

Available Examples

Parquet Analytics

Query local Parquet exports directly with typed selections, schema union, Hive partitions, filters, and grouped measures. The example creates and removes its own fixtures and requires no cloud account.

bun example/parquet-analytics.ts

Analytics Dashboard

An example showing:

Multi-table schema with foreign keys
DuckDB-specific types (STRUCT, LIST, MAP, JSON)
Transactions for data integrity
Complex aggregations and window functions
Array operations with DuckDB helpers
Loading and querying Parquet files

Best for: Learning DuckDB-specific features and analytical patterns.

Run locally (single in-memory connection):

bun example/analytics-dashboard.ts

NYC Taxi (MotherDuck)

Cloud database example featuring:

MotherDuck connection and authentication
Querying sample data (NYC taxi trips)
Aggregations with GROUP BY
CTEs for multi-step transformations
Date/time operations
Percentile calculations
Parallel queries on a connection pool

Best for: Getting started with MotherDuck and cloud analytics.

Run with a standard connection pool (6 connections):

export MOTHERDUCK_TOKEN=your_token_here
bun example/motherduck-nyc-taxi.ts

DuckLake Local Catalog

Local DuckLake example featuring:

DuckLake catalog attach
Data path configuration
Basic table creation and inserts

Best for: Getting started with DuckLake on local storage.

Run locally:

bun example/ducklake-local.ts

DuckLake MotherDuck

DuckLake on MotherDuck example featuring:

DuckLake catalog attach using MotherDuck metadata
Basic table creation and inserts

Best for: DuckLake on MotherDuck catalogs.

Run with MotherDuck:

export MOTHERDUCK_TOKEN=your_token_here
export DUCKLAKE_MOTHERDUCK_DB=my_lake
bun example/ducklake-motherduck.ts

Running Examples

All examples are located in the /example directory of the repository.

Prerequisites

Clone the repository:

git clone https://github.com/leonardovida/drizzle-duckdb.git
cd drizzle-duckdb

Install dependencies:
```
bun install
```

Local Examples

# Run the analytics dashboard example
bun run example/analytics-dashboard.ts

# Run the Parquet analytics example
bun run example/parquet-analytics.ts

# Run the DuckLake local example
bun run example/ducklake-local.ts

MotherDuck Examples

# Set your MotherDuck token
export MOTHERDUCK_TOKEN=your_token_here

# Run the NYC taxi example
bun run example/motherduck-nyc-taxi.ts

# Run the DuckLake MotherDuck example
export DUCKLAKE_MOTHERDUCK_DB=my_lake
bun run example/ducklake-motherduck.ts

Example Structure

Each example follows a similar pattern:

import { DuckDBInstance } from '@duckdb/node-api';
import { drizzle } from '@duckdbfan/drizzle-duckdb';

// 1. Define schema
const users = pgTable('users', { ... });

// 2. Create connection
const instance = await DuckDBInstance.create(':memory:');
const connection = await instance.connect();
const db = drizzle(connection);

// 3. Run queries
const results = await db.select().from(users);

// 4. Clean up
connection.closeSync();

Building Your Own

Use these examples as starting points for your own projects. Key patterns to follow:

Schema Definition: Define your tables with proper types
Connection Management: Use singleton patterns for persistent connections
Query Patterns: Use Drizzle’s type-safe query builder
Error Handling: Wrap operations in try/finally for cleanup