API Reference

DuckDbModule

Method	Description
forRoot(options?, isGlobal?)	Synchronous config, e.g. DuckDbModule.forRoot({ database: './my.db' })
forRootAsync(options)	Async config via useFactory, useClass, or useExisting

DuckDbService

Method	Description
query<T>(sql, ...params)	Run a query, get rows back as T[]
run(sql, ...params)	Run a statement with no return rows (CREATE TABLE, INSERT, etc.)
getConnection()	Access the raw duckdb.Connection
getDatabase()	Access the raw duckdb.Database

Parameterized queries

query() and run() accept ? placeholders in the SQL string, with the matching values passed as additional arguments:

await duckDb.query('SELECT * FROM users WHERE id = ?', userId);
await duckDb.run('INSERT INTO people (id, name) VALUES (?, ?)', id, name);

Use this form for any value that isn't a fixed, hardcoded string in your own source - request params, form input, config pulled from elsewhere, etc. Do not build SQL with template literals or string concatenation for such values:

// Unsafe - do not do this with untrusted input
await duckDb.query(`SELECT * FROM users WHERE id = ${userId}`);

query() and run() execute the SQL string exactly as given; the library itself has no query builder or sanitization layer, so injection safety depends entirely on using bound parameters at the call site.

@InjectDuckDB()

Inject the raw duckdb.Database connection directly, if you don't want to go through DuckDbService.

import { Injectable } from '@nestjs/common';
import { InjectDuckDB } from 'nestjs-duckdb';
import * as duckdb from 'duckdb';

@Injectable()
export class RawService {
  constructor(@InjectDuckDB() private readonly db: duckdb.Database) {}
}