Examples

This section showcases complete, runnable examples demonstrating Drizzle DuckDB in real-world scenarios. All examples live in /example and run with Bun.

Available Examples

Analytics Dashboard

A comprehensive 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 (auto-pooling in-memory):

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

Best for: Getting started with MotherDuck and cloud analytics.

Run with auto-pooling (default 4 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 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 '@leonardovida-md/drizzle-neo-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: Leverage Drizzle’s type-safe query builder
Error Handling: Wrap operations in try/finally for cleanup