LibSQL driver

LibSQL is a fork of SQLite that is both Open Source, and Open Contributions. It fully compatible with SQLite (either file-based or in-process), but also supports remote LibSQL servers (like Turso) for remote and distributed SQLite access.

Installation

The LibSQL driver can be installed with the @cadence-mq/driver-libsql package, and the @libsql/client package is required to connect to the database.

pnpm

pnpm add @cadence-mq/core @cadence-mq/driver-libsql @libsql/client

npm

npm install @cadence-mq/core @cadence-mq/driver-libsql @libsql/client

bun

bun add @cadence-mq/core @cadence-mq/driver-libsql @libsql/client

yarn

yarn add @cadence-mq/core @cadence-mq/driver-libsql @libsql/client

Setup the schema

In order to use the LibSQL driver, you need to setup the schema for the database. This can be done once at startup, and is done by calling the setupSchema function, this function is exported from the @cadence-mq/driver-libsql package and will create the necessary tables and indexes for the driver to work, it can be executed just once, and is safe to execute multiple times.

You can also use the getSchema function to get the schema as a string, and execute it manually.

Programmatically

index.ts

import { setupSchema } from '@cadence-mq/driver-libsql';
import { createClient } from '@libsql/client';

const client = createClient({ /**/ });

// Setup the schema
await setupSchema({ client });

Manually

schema.sql

PRAGMA journal_mode = WAL;
PRAGMA synchronous = 1;
PRAGMA busy_timeout = 5000;

CREATE TABLE IF NOT EXISTS jobs (
  id TEXT PRIMARY KEY,
  task_name TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'pending',
  created_at DATETIME NOT NULL,
  started_at DATETIME,
  completed_at DATETIME,
  max_retries INTEGER,
  error TEXT,
  data TEXT,
  result TEXT,
  scheduled_at DATETIME NOT NULL,
  cron TEXT
);

CREATE INDEX IF NOT EXISTS jobs_status_scheduled_at_started_at_idx ON jobs (status, scheduled_at, started_at);

Local SQLite file example

Here is a simple example of how to use the LibSQL driver to store jobs in a local SQLite file.

index.ts

import { createCadence } from '@cadence-mq/core';
import { createLibSqlDriver, setupSchema } from '@cadence-mq/driver-libsql';
import { createClient } from '@libsql/client';

const fileUrl = 'file:./cadence-mq.db';

const client = createClient({ url: fileUrl });
const driver = createLibSqlDriver({ client });
const cadence = createCadence({ driver });

// Setup the schema for the database, can be done once at startup
await setupSchema({ client });

// Register a task to be executed
cadence.registerTask({
  taskName: 'send-welcome-email',
  handler: async ({ data }) => {
    console.log(`Sending welcome email to ${data.email}`);
  },
});

// Create a worker to execute the jobs
const worker = cadence.createWorker({ workerId: '1' });
worker.start();

// Schedule a job to be executed as soon as possible
await cadence.scheduleJob({
  taskName: 'send-welcome-email',
  data: { email: 'test@test.com' },
});

Remote LibSQL server example

Here is a simple example of how to use the LibSQL driver to store jobs in a remote LibSQL server.

index.ts

import { createCadence } from '@cadence-mq/core';
import { createLibSqlDriver, setupSchema } from '@cadence-mq/driver-libsql';
import { createClient } from '@libsql/client';

// It is highly recommended to store your DB credentials in env variables
const client = createClient({
  url: process.env.DATABASE_URL,
  authToken: process.env.AUTH_TOKEN,
});

const driver = createLibSqlDriver({ client });
const cadence = createCadence({ driver });

// Setup the schema for the database, can be done once at startup
await setupSchema({ client });

// Register a task to be executed
cadence.registerTask({
  taskName: 'send-welcome-email',
  handler: async ({ data }) => {
    console.log(`Sending welcome email to ${data.email}`);
  },
});

// Create a worker to execute the jobs
const worker = cadence.createWorker({ workerId: '1' });
worker.start();

// Schedule a job to be executed as soon as possible
await cadence.scheduleJob({
  taskName: 'send-welcome-email',
  data: { email: 'test@test.com' },
});

In-process example

Here is a simple example of how to use the LibSQL driver to store jobs in-process, this is useful for testing and development. For a lower overhead, you can use the in-memory driver instead.

index.ts

import { createCadence } from '@cadence-mq/core';
import { createLibSqlDriver, setupSchema } from '@cadence-mq/driver-libsql';
import { createClient } from '@libsql/client';

const client = createClient({ url: ':memory:' });
const driver = createLibSqlDriver({ client });
const cadence = createCadence({ driver });

// Setup the schema for the database, can be done once at startup
await setupSchema({ client });

// Register a task to be executed
cadence.registerTask({
  taskName: 'send-welcome-email',
  handler: async ({ data }) => {
    console.log(`Sending welcome email to ${data.email}`);
  },
});

// Create a worker to execute the jobs
const worker = cadence.createWorker({ workerId: '1' });
worker.start();

// Schedule a job to be executed as soon as possible
await cadence.scheduleJob({
  taskName: 'send-welcome-email',
  data: { email: 'test@test.com' },
});

Note

As for the in-memory driver, using the LibSQL driver with an :memory: comes with some limitations: no persistence, no distributed support, and memory consumption, more details in the in-memory driver documentation.