Use sqlfu with Turso and libSQL databases

Turso and libSQL offer several deployment modes: a local embedded file, a remote Turso Cloud database, and a sync mode that keeps a local file in sync with Turso Cloud. sqlfu supports all of them through adapter factories that share the same typed client surface — your application code stays the same regardless of which mode you run in. Most Turso and libSQL drivers are asynchronous. Generated wrappers reflect that, returning promises at each call site.

Configuration

For a @libsql/client-based setup that works locally and in production with a URL swap:

sqlfu.config.ts

import {createClient} from '@libsql/client';
import {defineConfig, createLibsqlClient} from 'sqlfu';

export default defineConfig({
  db: () => {
    const raw = createClient({
      url: process.env.TURSO_DATABASE_URL || 'file:./db/app.sqlite',
      authToken: process.env.TURSO_AUTH_TOKEN,
    });

    return {
      client: createLibsqlClient(raw),
      async [Symbol.asyncDispose]() {
        await raw.close();
      },
    };
  },
  definitions: './definitions.sql',
  migrations: './migrations',
  queries: './sql',
});

With url: 'file:./db/app.sqlite' locally and libsql://... in production, sqlfu commands (migrate, check, the UI) always operate on the same database your app uses — no separate scratch file.

Set TURSO_DATABASE_URL and TURSO_AUTH_TOKEN in your environment for Turso Cloud access. Locally, omit both and the file: fallback keeps everything on disk.

Schema and queries

definitions.sql

create table organizations (
  id integer primary key,
  slug text not null unique,
  name text not null
);

sql/queries.sql

/** @name findOrganization */
select id, slug, name
from organizations
where slug = :slug
limit 1;

npx sqlfu draft
npx sqlfu migrate
npx sqlfu generate

Choosing a driver

@libsql/client
@tursodatabase/serverless
@tursodatabase/database
@tursodatabase/sync

The most versatile option. Use file: URLs locally and libsql:// in production with no code changes at the sqlfu boundary:

src/db.ts

import {createClient} from '@libsql/client';
import {createLibsqlClient} from 'sqlfu';

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

const raw = createClient({
  url: process.env.TURSO_DATABASE_URL!,
  authToken: process.env.TURSO_AUTH_TOKEN,
});
const client = createLibsqlClient(raw);

const organization = await findOrganization(client, {slug: 'acme'});

Install:

npm install sqlfu @libsql/client

No native bindings. Runs on any runtime with fetch() — Vercel Edge, Cloudflare Workers, Deno Deploy, AWS Lambda:

src/db.ts

import {connect} from '@tursodatabase/serverless';
import {createTursoServerlessClient} from 'sqlfu';

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

const connection = connect({
  url: process.env.TURSO_DATABASE_URL!,
  authToken: process.env.TURSO_AUTH_TOKEN,
});
const client = createTursoServerlessClient(connection);

const organization = await findOrganization(client, {slug: 'acme'});

Install:

npm install sqlfu @tursodatabase/serverless

Turso’s newer engine with native bindings. Fast local access and the same async interface as the sync variant:

src/db.ts

import {connect} from '@tursodatabase/database';
import {createTursoDatabaseClient} from 'sqlfu';

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

const db = await connect('app.db');
const client = createTursoDatabaseClient(db);

const organization = await findOrganization(client, {slug: 'acme'});

Install:

npm install sqlfu @tursodatabase/database

Keeps a local SQLite file in sync with Turso Cloud. Uses the same createTursoDatabaseClient adapter; the sync behavior is at the driver level:

src/db.ts

import {connect} from '@tursodatabase/sync';
import {createTursoDatabaseClient} from 'sqlfu';

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

const db = await connect({
  path: 'local.db',
  url: process.env.TURSO_DATABASE_URL,
  authToken: process.env.TURSO_AUTH_TOKEN,
});
await db.connect();
const client = createTursoDatabaseClient(db);

// sync at your own cadence; sqlfu doesn't own replication
await db.push();
await db.pull();

const organization = await findOrganization(client, {slug: 'acme'});

Install:

npm install sqlfu @tursodatabase/sync

Choosing between local and remote

A few rules of thumb:

Local dev, remote prod with no code changes: use @libsql/client. Set url: 'file:app.db' locally and libsql://... in production.
Edge runtimes or serverless without native deps: use @tursodatabase/serverless.
Embedded database that syncs to Turso Cloud: use @tursodatabase/sync.
Fastest pure-local experience on Node with native bindings: use @tursodatabase/database.

Adapters reference

Every Turso and libSQL adapter snippet with the full compatibility matrix.

Cloudflare D1 guide

Use sqlfu with D1 on Cloudflare Workers.

Runtimes

Cloudflare

Integrations

Use sqlfu with Turso and libSQL databases

Configuration

Schema and queries

Choosing a driver

Choosing between local and remote

Read next

Adapters reference

Cloudflare D1 guide

Build docs developers (and LLMs) love

Runtimes

Cloudflare

Integrations

Documentation Index

​Configuration

​Schema and queries

​Choosing a driver

​Choosing between local and remote

​Read next

Adapters reference

Cloudflare D1 guide

Build docs developers (and LLMs) love

Configuration

Schema and queries

Choosing a driver

Choosing between local and remote

Read next