feat: add support for libsql and cleanup clients to dialects mapping

Deprecates: connection.dialectName in favor of connection.clientName

package.json

@@ -35,6 +35,7 @@
   "scripts": {
     "pretest": "npm run lint",
     "test:better_sqlite": "cross-env DB=better_sqlite node --enable-source-maps --loader=ts-node/esm ./bin/test.js",
+    "test:libsql": "cross-env DB=libsql node --enable-source-maps --loader=ts-node/esm ./bin/test.js",
     "test:sqlite": "cross-env DB=sqlite node --enable-source-maps --loader=ts-node/esm ./bin/test.js",
     "test:mysql": "cross-env DB=mysql node --enable-source-maps --loader=ts-node/esm ./bin/test.js",
     "test:mysql_legacy": "cross-env DB=mysql_legacy node --enable-source-maps --loader=ts-node/esm ./bin/test.js",
@@ -68,6 +69,7 @@
     "@japa/assert": "^3.0.0",
     "@japa/file-system": "^2.3.0",
     "@japa/runner": "^3.1.4",
+    "@libsql/sqlite3": "^0.3.1",
     "@swc/core": "^1.6.1",
     "@types/chance": "^1.1.6",
     "@types/luxon": "^3.4.2",

src/clients/libsql.cjs

@@ -0,0 +1,14 @@
+const Sqlite3Client = require('knex/lib/dialects/sqlite3')
+
+class LibSQLClient extends Sqlite3Client {
+  _driver() {
+    return require('@libsql/sqlite3')
+  }
+}
+
+Object.assign(LibSQLClient.prototype, {
+  dialect: 'libsql',
+  driverName: 'libsql',
+})
+
+module.exports = LibSQLClient

src/connection/index.ts

@@ -14,10 +14,13 @@ import { patchKnex } from 'knex-dynamic-connection'
 import type { Logger } from '@adonisjs/core/logger'
 // @ts-expect-error
 import { resolveClientNameWithAliases } from 'knex/lib/util/helpers.js'
-import { ConnectionConfig, ConnectionContract } from '../types/database.js'
 
-import { Logger as ConnectionLogger } from './logger.js'
 import * as errors from '../errors.js'
+import { clientsNames } from '../dialects/index.js'
+// @ts-expect-error
+import LibSQLClient from '../clients/libsql.cjs'
+import { Logger as ConnectionLogger } from './logger.js'
+import type { ConnectionConfig, ConnectionContract } from '../types/database.js'
 
 /**
  * Connection class manages a given database connection. Internally it uses
@@ -38,10 +41,17 @@ export class Connection extends EventEmitter implements ConnectionContract {
   readClient?: Knex
 
   /**
-   * Connection dialect name
+   * Connection dialect name.
+   * @deprecated
+   * @see clientName
    */
   dialectName: ConnectionContract['dialectName']
 
+  /**
+   * Connection client name.
+   */
+  clientName: ConnectionContract['dialectName']
+
   /**
    * A boolean to know if connection operates on read/write
    * replicas
@@ -66,12 +76,18 @@ export class Connection extends EventEmitter implements ConnectionContract {
   ) {
     super()
     this.validateConfig()
-    this.dialectName = resolveClientNameWithAliases(this.config.client)
+    this.clientName = resolveClientNameWithAliases(this.config.client)
+    this.dialectName = this.clientName
+
     this.hasReadWriteReplicas = !!(
       this.config.replicas &&
       this.config.replicas.read &&
       this.config.replicas.write
     )
+
+    if (!clientsNames.includes(this.clientName)) {
+      throw new errors.E_UNSUPPORTED_CLIENT([this.clientName])
+    }
   }
 
   /**
@@ -133,6 +149,17 @@ export class Connection extends EventEmitter implements ConnectionContract {
    */
   private getWriteConfig(): Knex.Config {
     if (!this.config.replicas) {
+      /**
+       * Replacing string based libsql client with the
+       * actual implementation
+       */
+      if (this.config.client === 'libsql') {
+        return {
+          ...this.config,
+          client: LibSQLClient,
+        }
+      }
+
       return this.config
     }
 

src/dialects/base_sqlite.ts

@@ -10,7 +10,7 @@
 import type { DialectContract, QueryClientContract, SharedConfigNode } from '../types/database.js'
 
 export abstract class BaseSqliteDialect implements DialectContract {
-  abstract readonly name: 'sqlite3' | 'better-sqlite3'
+  abstract readonly name: 'sqlite3' | 'better-sqlite3' | 'libsql'
   readonly supportsAdvisoryLocks = false
   readonly supportsViews = true
   readonly supportsTypes = false

src/dialects/index.ts

@@ -10,14 +10,20 @@
 import { PgDialect } from './pg.js'
 import { MysqlDialect } from './mysql.js'
 import { MssqlDialect } from './mssql.js'
+import { LibSQLDialect } from './libsql.js'
 import { SqliteDialect } from './sqlite.js'
 import { OracleDialect } from './oracle.js'
 import { RedshiftDialect } from './red_shift.js'
 import { BetterSqliteDialect } from './better_sqlite.js'
-import { DialectContract, QueryClientContract, SharedConfigNode } from '../types/database.js'
+import {
+  DialectContract,
+  SharedConfigNode,
+  QueryClientContract,
+  ConnectionContract,
+} from '../types/database.js'
 
-export const dialects: {
-  [key: string]: {
+export const clientsToDialectsMapping: {
+  [K in ConnectionContract['clientName']]: {
     new (client: QueryClientContract, config: SharedConfigNode): DialectContract
   }
 } = {
@@ -28,5 +34,10 @@ export const dialects: {
   'postgres': PgDialect,
   'redshift': RedshiftDialect,
   'sqlite3': SqliteDialect,
+  'libsql': LibSQLDialect,
   'better-sqlite3': BetterSqliteDialect,
 }
+
+export const clientsNames = Object.keys(
+  clientsToDialectsMapping
+) as ConnectionContract['clientName'][]

src/dialects/libsql.ts

@@ -0,0 +1,15 @@
+/*
+ * @adonisjs/lucid
+ *
+ * (c) Harminder Virk <virk@adonisjs.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { DialectContract } from '../types/database.js'
+import { BaseSqliteDialect } from './base_sqlite.js'
+
+export class LibSQLDialect extends BaseSqliteDialect implements DialectContract {
+  readonly name = 'libsql'
+}

src/errors.ts

@@ -72,3 +72,12 @@ export const E_UNDEFINED_RELATIONSHIP = createError(
 )
 
 export const E_RUNTIME_EXCEPTION = createError('%s', 'E_RUNTIME_EXCEPTION', 500)
+
+/**
+ * The client is not supported by Lucid
+ */
+export const E_UNSUPPORTED_CLIENT = createError<[string]>(
+  'Unsupported client "%s"',
+  'E_UNSUPPORTED_CLIENT',
+  500
+)

src/query_client/index.ts

@@ -19,9 +19,9 @@ import {
   TransactionClientContract,
 } from '../types/database.js'
 
-import { dialects } from '../dialects/index.js'
-import { TransactionClient } from '../transaction_client/index.js'
 import { RawBuilder } from '../database/static_builder/raw.js'
+import { clientsToDialectsMapping } from '../dialects/index.js'
+import { TransactionClient } from '../transaction_client/index.js'
 import { RawQueryBuilder } from '../database/query_builder/raw.js'
 import { InsertQueryBuilder } from '../database/query_builder/insert.js'
 import { ReferenceBuilder } from '../database/static_builder/reference.js'
@@ -72,7 +72,10 @@ export class QueryClient implements QueryClientContract {
   ) {
     this.debug = !!this.connection.config.debug
     this.connectionName = this.connection.name
-    this.dialect = new dialects[this.connection.dialectName](this, this.connection.config)
+    this.dialect = new clientsToDialectsMapping[this.connection.clientName](
+      this,
+      this.connection.config
+    )
   }
 
   /**

src/query_runner/index.ts

@@ -33,7 +33,7 @@ export class QueryRunner {
    * Is query dialect using sqlite database or not
    */
   private isUsingSqlite() {
-    return this.client.dialect.name === 'sqlite3'
+    return ['sqlite3', 'better-sqlite3', 'libsql'].includes(this.client.dialect.name)
   }
 
   /**

src/types/database.ts

@@ -55,6 +55,7 @@ export interface DialectContract {
     | 'postgres'
     | 'redshift'
     | 'sqlite3'
+    | 'libsql'
     | 'better-sqlite3'
   readonly dateTimeFormat: string
 
@@ -371,6 +372,24 @@ export type SqliteConfig = SharedConfigNode & {
   replicas?: never
 }
 
+/**
+ * The LibSQL specific config options are taken directly from the
+ * driver. https://github.com/mapbox/node-sqlite3/wiki/API#new-sqlite3databasefilename-mode-callback
+ *
+ * LibSQL dialect is a drop-in replacement for SQLite and hence the config
+ * options are same
+ */
+export type LibSQLConfig = SharedConfigNode & {
+  client: 'libsql'
+  connection: {
+    filename: string
+    flags?: string[]
+    debug?: boolean
+    mode?: any
+  }
+  replicas?: never
+}
+
 /**
  * The MYSQL specific config options are taken directly from the
  * driver. https://www.npmjs.com/package/mysql#connection-options
@@ -543,6 +562,7 @@ export type MssqlConfig = SharedConfigNode & {
  */
 export type ConnectionConfig =
   | SqliteConfig
+  | LibSQLConfig
   | MysqlConfig
   | PostgreConfig
   | OracleConfig
@@ -638,6 +658,10 @@ export interface ConnectionContract extends EventEmitter {
   client?: Knex
   readClient?: Knex
 
+  /**
+   * @deprecated
+   * @see clientName
+   */
   readonly dialectName:
     | 'mssql'
     | 'mysql'
@@ -646,6 +670,19 @@ export interface ConnectionContract extends EventEmitter {
     | 'postgres'
     | 'redshift'
     | 'sqlite3'
+    | 'libsql'
+    | 'better-sqlite3'
+
+  readonly clientName:
+    | 'mssql'
+    | 'mysql'
+    | 'mysql2'
+    | 'oracledb'
+    | 'postgres'
+    | 'redshift'
+    | 'sqlite3'
+    | 'libsql'
+    | 'better-sqlite3'
 
   /**
    * Property to find if explicit read/write is enabled

test-helpers/index.ts

@@ -43,6 +43,9 @@ import { InsertQueryBuilder } from '../src/database/query_builder/insert.js'
 import { LucidRow, LucidModel, AdapterContract } from '../src/types/model.js'
 import { DatabaseQueryBuilder } from '../src/database/query_builder/database.js'
 
+// @ts-expect-error
+import LibSQLClient from '../src/clients/libsql.cjs'
+
 dotenv.config()
 export const APP_ROOT = new URL('./tmp', import.meta.url)
 export const SQLITE_BASE_PATH = fileURLToPath(APP_ROOT)
@@ -66,6 +69,15 @@ export function getConfig(): ConnectionConfig {
         useNullAsDefault: true,
         debug: !!process.env.DEBUG,
       }
+    case 'libsql':
+      return {
+        client: 'libsql',
+        connection: {
+          filename: `file:${join(SQLITE_BASE_PATH, 'libsql.db')}`,
+        },
+        useNullAsDefault: true,
+        debug: !!process.env.DEBUG,
+      }
     case 'better_sqlite':
       return {
         client: 'better-sqlite3',
@@ -138,11 +150,27 @@ export function getConfig(): ConnectionConfig {
   }
 }
 
+/**
+ * Returns an instance of knex for testing
+ */
+export function getKnex(config: knex.Knex.Config): knex.Knex {
+  return knex.knex(
+    Object.assign(
+      {},
+      {
+        ...config,
+        client: config.client === 'libsql' ? LibSQLClient : config.client,
+      },
+      { debug: false }
+    )
+  )
+}
+
 /**
  * Does base setup by creating databases
  */
 export async function setup(destroyDb: boolean = true) {
-  const db = knex.knex(Object.assign({}, getConfig(), { debug: false }))
+  const db = getKnex(Object.assign({}, getConfig(), { debug: false }))
 
   const hasUsersTable = await db.schema.hasTable('users')
   if (!hasUsersTable) {
@@ -292,7 +320,7 @@ export async function setup(destroyDb: boolean = true) {
  * Does cleanup removes database
  */
 export async function cleanup(customTables?: string[]) {
-  const db = knex.knex(Object.assign({}, getConfig(), { debug: false }))
+  const db = getKnex(Object.assign({}, getConfig(), { debug: false }))
 
   if (customTables) {
     for (let table of customTables) {
@@ -324,7 +352,7 @@ export async function cleanup(customTables?: string[]) {
  * Reset database tables
  */
 export async function resetTables() {
-  const db = knex.knex(Object.assign({}, getConfig(), { debug: false }))
+  const db = getKnex(Object.assign({}, getConfig(), { debug: false }))
   await db.table('users').truncate()
   await db.table('uuid_users').truncate()
   await db.table('follows').truncate()

test/connection/connection.spec.ts

@@ -13,7 +13,7 @@ import { MysqlConfig } from '../../src/types/database.js'
 import { Connection } from '../../src/connection/index.js'
 import { setup, cleanup, getConfig, resetTables, logger } from '../../test-helpers/index.js'
 
-if (process.env.DB !== 'sqlite') {
+if (!['sqlite', 'better_sqlite', 'libsql'].includes(process.env.DB!)) {
   test.group('Connection | config', (group) => {
     group.setup(async () => {
       await setup()
@@ -122,28 +122,6 @@ test.group('Connection | setup', (group) => {
 
     await connection.disconnect()
   }).waitForDone()
-
-  test('raise error when unable to make connection', ({ assert }, done) => {
-    assert.plan(2)
-
-    const connection = new Connection(
-      'primary',
-      Object.assign({}, getConfig(), { client: null }),
-      logger
-    )
-
-    connection.on('error', ({ message }) => {
-      try {
-        assert.equal(message, "knex: Required configuration option 'client' is missing.")
-        done()
-      } catch (error) {
-        done(error)
-      }
-    })
-
-    const fn = () => connection.connect()
-    assert.throws(fn, /knex: Required configuration option/)
-  }).waitForDone()
 })
 
 if (process.env.DB === 'mysql') {