@the-forgebase/knex-libsql

A Knex dialect for using LibSQL / Turso.

This allows you to use the power of Knex.js query builder with LibSQL databases.

Installation

npm install knex @the-forgebase/knex-libsql libsql

or

pnpm add knex @the-forgebase/knex-libsql libsql

or

yarn add knex @the-forgebase/knex-libsql libsql

Usage

To use this dialect, you need to configure Knex to use @the-forgebase/knex-libsql as the client.

import { knex } from 'knex';
import { LibSqlKnexClient } from '@the-forgebase/knex-libsql';

const db = knex({
  client: LibSqlKnexClient,
  connection: {
    // For local file database
    filename: 'file:my.db', 
    
    // For remote database with Turso
    // url: process.env.TURSO_DATABASE_URL,
    // authToken: process.env.TURSO_AUTH_TOKEN,
  },
  useNullAsDefault: true,
});

// Now you can use `db` to build queries
async function example() {
  await db.schema.createTable('users', (table) => {
    table.increments('id');
    table.string('name');
  });

  await db('users').insert({ name: 'ForgeBase' });

  const users = await db('users').select('*');
  console.log(users);

  await db.destroy();
}

example();

The client property should be the LibSqlKnexClient class imported from this package. The connection object is passed to the LibSQL driver.

For local development, you can use a filename for a local SQLite file.

For remote databases, like Turso, you can provide a url and authToken.

Why @the-forgebase/knex-libsql?

The official knex-libsql package (@libsql/knex-libsql) is a great lightweight option. However, it is based on the sqlite3 package, whereas this package uses better-sqlite3.

This package takes a different approach by extending Knex's built-in better-sqlite3 dialect. This allows us to leverage the existing, mature, and feature-rich functionalities of the better-sqlite3 dialect while adapting it to work with libsql. This can provide a more stable and full-featured experience for developers already familiar with Knex's SQLite integrations.

Credits

This package is heavily based on the SQLite dialect implementation from MikroORM.

Specifically, the following files were adapted:

• SqliteTableCompiler.ts: from mikro-orm/packages/knex/src/dialects/sqlite/SqliteTableCompiler.ts
• LibSqlKnexDialect.ts: from mikro-orm/packages/knex/src/dialects/sqlite/LibSqlKnexDialect.ts

We are grateful for the excellent work done by the MikroORM team.