---
title: "@flowblade/source-duckdb"
description: "Duckdb datasource adapter based on @duckdb/node-api."
sidebar:
    label: "source-duckdb"
---

[![npm](https://img.shields.io/npm/v/@flowblade/source-duckdb?style=for-the-badge&label=Npm&labelColor=444&color=informational)](https://www.npmjs.com/package/@flowblade/source-duckdb)
[![changelog](https://img.shields.io/static/v1?label=&message=changelog&logo=github&style=for-the-badge&labelColor=444&color=informational)](https://github.com/belgattitude/flowblade/blob/main/packages/source-duckdb/CHANGELOG.md)
[![bundles](https://img.shields.io/static/v1?label=&message=esm&logo=rolldown&style=for-the-badge&labelColor=444&color=informational)](https://github.com/belgattitude/flowblade/blob/main/packages/source-duckdb/.size-limit.ts)
[![node](https://img.shields.io/static/v1?label=Node&message=22.18%2b&logo=node.js&style=for-the-badge&labelColor=444&color=informational)](#compatibility)
[![downloads](https://img.shields.io/npm/dm/@flowblade/source-duckdb?style=for-the-badge&labelColor=444)](https://www.npmjs.com/package/@flowblade/source-duckdb)
[![license](https://img.shields.io/npm/l/@flowblade/source-duckdb?style=for-the-badge&labelColor=444)](https://github.com/belgattitude/flowblade/blob/main/LICENSE)

Duckdb datasource adapter based on
[@duckdb/node-api](https://github.com/duckdb/duckdb-node-neo)

## Install

```package-install
npm i @flowblade/source-duckdb @duckdb/node-api
```

## Quick start

### Create a duckdb instance

```typescript
import os from "node:os";

import { type DuckDBConnection, DuckDBInstance } from "@duckdb/node-api";
import { DuckdbDatasource } from "@flowblade/source-duckdb";

// Create a connection to a DuckDB instance
const createConnection = async (maxThreads = 4): Promise<DuckDBConnection> => {
    const availableThreads = os.availableParallelism();
    const maxParallelism = Math.min(maxThreads, availableThreads - 1);
    const threads = availableThreads > 1 ? maxParallelism : undefined;

    const instance = await DuckDBInstance.create(":memory:", {
        // Choose between READ_ONLY or READ_WRITE
        // Note that in READ_WRITE mode concurrency is limited to 1
        // See: https://duckdb.org/docs/connect/concurrency.html
        access_mode: "READ_WRITE",
        max_memory: "64MB",
        // Using more threads may require additional memory
        ...(threads ? { threads: threads.toString(10) } : {}),
    });
    return await instance.connect();
};

const duckdb = await createConnection();

// Create a duckdb datasource
export const ds = new DuckdbDatasource({ connection: duckdb });
```

### Query the database

```typescript
import { DuckdbDatasource, sql } from "@flowblade/source-duckdb";

import { ds } from "./config.ts";

const params = {
    min: 10,
    max: 99,
    name: "test",
    createdAt: new Date().toISOString(),
};

type Row = { id: number; name: "test"; createdAt: Date };

const rawSql = sql<Row>`

      WITH products(productId, createdAt)
          AS MATERIALIZED (
               FROM RANGE(1,100) SELECT
               range::INT,
               TIMESTAMPTZ '2025-01-01 12:30:00.123456789+01:00'
          )

      SELECT productId,
             ${params.name} as name,
             createdAt

      FROM products
      WHERE productId BETWEEN ${params.min}::INTEGER AND ${params.max}::INTEGER
      AND createdAt < ${params.createdAt}::TIMESTAMPTZ
    `;

const result = await ds.query(rawSql);

// Option 1: The QResult object contains the data, metadata and error
//  - data:  the result rows (TData or undefined if error)
//  - error: the error (QError or undefined if success)
//  - meta:  the metadata (always present)

const { data, meta, error } = result;

// Option 2: You operate over the result, ie: mapping the data

const { data: data2 } = result.map((row) => {
    return {
        id: row.productId,
        key: `key-${row.productId}`,
    };
});

if (data) {
    console.log(data);
}
```

## Compatibility

| Level        | CI  | Description                                                                                                                                                                                                                                                                                                                                                            |
| ------------ | --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Node         | ✅  | Requires 22.18+, CI for 22.x, 24.x & 26.x                                                                                                                                                                                                                                                                                                                              |
| Bun          | ✅  | Bun 1.4+, unit tests run on CI with the latest Bun                                                                                                                                                                                                                                                                                                                     |
| Deno         | ✅  | Deno LTS, unit tests run on CI with Deno 2                                                                                                                                                                                                                                                                                                                             |
| Typescript   | ✅  | TS 5.0 + / [are-the-type-wrong](https://github.com/arethetypeswrong/arethetypeswrong.github.io) checks on CI.                                                                                                                                                                                                                                                          |
| ES2022       | ✅  | Dist files checked with [es-check](https://github.com/yowainwright/es-check)                                                                                                                                                                                                                                                                                           |