Turso

Turso is a remote SQLite service. The @flaky-tests/store-turso package uses the @libsql/client driver and runs the same SQL schema as the local SQLite store.

Free tier: 500 databases, 1 GB storage, 1 billion row reads/month.

Installation

bun add -D @flaky-tests/store-turso
# or: npm install -D @flaky-tests/store-turso

Setup

1. Create a Turso account and database

   # Install the Turso CLI
   curl -sSfL https://get.tur.so/install.sh | bash
   
   # Log in
   turso auth login
   
   # Create a database
   turso db create flaky-tests

2. Get the connection URL and auth token

   turso db show flaky-tests --url
   # → libsql://flaky-tests-yourname.turso.io
   
   turso db tokens create flaky-tests
   # → eyJhbGci...

3. Add to your environment

   # .env.local (or GitHub Actions secrets)
   TURSO_URL=libsql://flaky-tests-yourname.turso.io
   TURSO_AUTH_TOKEN=eyJhbGci...

Usage

import { TursoStore } from '@flaky-tests/store-turso'

const store = new TursoStore({
  url: process.env.TURSO_URL!,
  authToken: process.env.TURSO_AUTH_TOKEN,
})
await store.migrate() // creates tables if they don't exist

Note

Unlike SqliteStore, TursoStore requires an explicit await store.migrate() call because the libSQL client is async. Migrations are versioned/idempotent (tracked in a schema_version table) and safe to call on every startup. The CLI auto-runs migrate() before every query.

Constructor options

interface TursoStoreOptions {
  /** libsql:// URL for your Turso database */
  url: string
  /** Auth token (not required for local file:// URLs) */
  authToken?: string
  /** Retry tuning for read methods. Defaults: 3 attempts, 100ms base delay. */
  retry?: { attempts?: number; baseMs?: number }
}

Error handling, retries, and cancellation

Driver errors are wrapped in StoreError with cause preserved. Read methods auto-retry transient failures (network transport errors, HTTP 5xx) with exponential backoff and jitter; writes are not retried because they lack an idempotency key. Read methods accept an optional signal?: AbortSignal. libSQL has no native abort support, so the adapter uses caller-side raceAbort — the caller observes an AbortError immediately while the in-flight request completes in the background and is discarded.

CLI usage

FLAKY_TESTS_STORE=turso \
  TURSO_URL=libsql://flaky-tests-yourname.turso.io \
  TURSO_AUTH_TOKEN=eyJhbGci... \
  bunx @flaky-tests/core

Plugin configuration (Bun)

Create a custom preload:

preload.ts

import { createPreload } from '@flaky-tests/plugin-bun'
import { TursoStore } from '@flaky-tests/store-turso'

const store = new TursoStore({
  url: process.env.TURSO_URL!,
  authToken: process.env.TURSO_AUTH_TOKEN,
})
await store.migrate()

createPreload(store)

bunfig.toml

[test]
preload = ["./preload.ts"]

Plugin configuration (Vitest)

vitest.config.ts

import { defineConfig } from 'vitest/config'
import { FlakyTestsReporter } from '@flaky-tests/plugin-vitest'
import { TursoStore } from '@flaky-tests/store-turso'

const store = new TursoStore({
  url: process.env.TURSO_URL!,
  authToken: process.env.TURSO_AUTH_TOKEN,
})
await store.migrate()

export default defineConfig({
  test: {
    reporters: ['default', new FlakyTestsReporter({ store })],
  },
})