Use sqlfu with Node.js SQLite drivers

Node.js offers two solid SQLite driver options for sqlfu: the built-in node:sqlite module (Node 22+) and the better-sqlite3 npm package. Both are synchronous, which means sqlfu’s generated query wrappers return rows directly — no await needed on the call site.

Install sqlfu

npm install sqlfu

Then install the driver you want to use. node:sqlite is built into Node 22+ and needs no install. For better-sqlite3:

npm install better-sqlite3

Configure sqlfu

Create sqlfu.config.ts in your project root. Point db at a local SQLite file and set generate.sync: true so generated wrappers match the synchronous driver:

sqlfu.config.ts

import {defineConfig} from 'sqlfu';

export default defineConfig({
  db: './db/app.sqlite',
  definitions: './definitions.sql',
  migrations: './migrations',
  queries: './sql',
  generate: {
    sync: true,
  },
});

generate.sync: true tells sqlfu that your driver is synchronous. Generated wrappers accept a SyncClient and return rows directly instead of promises.

Write schema and queries

Add your schema to definitions.sql:

definitions.sql

create table posts (
  id integer primary key,
  slug text not null unique,
  title text not null,
  published integer not null default 0
);

Add a query to sql/queries.sql:

sql/queries.sql

/** @name findPostBySlug */
select id, slug, title
from posts
where slug = :slug
limit 1;

Draft, migrate, and generate

Run the standard sqlfu commands to create the migration and generate TypeScript wrappers:

npx sqlfu draft
npx sqlfu migrate
npx sqlfu generate

Create the client and call your queries

Choose the driver that fits your project:

node:sqlite
better-sqlite3
libsql (native embedded)

node:sqlite is built into Node 22+ — no install required:

src/db.ts

import {DatabaseSync} from 'node:sqlite';
import {createNodeSqliteClient} from 'sqlfu';

import {findPostBySlug} from './sql/.generated/queries.sql.ts';

const db = new DatabaseSync('./db/app.sqlite');
const client = createNodeSqliteClient(db);

const post = findPostBySlug(client, {slug: 'hello-world'});

better-sqlite3 provides a mature, well-tested native driver:

src/db.ts

import Database from 'better-sqlite3';
import {createBetterSqlite3Client} from 'sqlfu';

import {findPostBySlug} from './sql/.generated/queries.sql.ts';

const db = new Database('./db/app.sqlite');
const client = createBetterSqlite3Client(db);

const post = findPostBySlug(client, {slug: 'hello-world'});

libsql gives you a local embedded libSQL database with sync support:

src/db.ts

import Database from 'libsql';
import {createLibsqlSyncClient} from 'sqlfu';

import {findPostBySlug} from './sql/.generated/queries.sql.ts';

const db = new Database('./db/app.sqlite');
const client = createLibsqlSyncClient(db);

const post = findPostBySlug(client, {slug: 'hello-world'});

Sync behavior

All three Node drivers in this guide are synchronous. sqlfu preserves that — a SyncClient built on node:sqlite, better-sqlite3, or native libsql returns rows directly from every call:

// No await needed
const post = findPostBySlug(client, {slug: 'hello-world'});
const rows = client.all({sql: 'select * from posts', params: []});

If you want to use a local SQLite file during development and a remote Turso Cloud database in production without changing any application code, use @libsql/client with url: 'file:app.db' locally and libsql://... in production. See the Turso and libSQL guide.

Adapters reference

Every adapter snippet and the full sync/async compatibility matrix.

Runtime client

The shared SyncClient interface and how sync stays sync.

Runtimes

Cloudflare

Integrations

Use sqlfu with Node.js SQLite drivers

Sync behavior

Read next

Adapters reference

Runtime client

Build docs developers (and LLMs) love

Runtimes

Cloudflare

Integrations

Documentation Index

​Sync behavior

​Read next

Adapters reference

Runtime client

Build docs developers (and LLMs) love

Sync behavior

Read next