SQLite adapter

The @healthzkit/sqlite package provides HealthAdapter helpers for better-sqlite3 (synchronous), sqlite3 (callback driver), and @libsql/client (libSQL / Turso). Successful checks run a lightweight SQL probe (default SELECT 1) and return ok with metadata.latencyMs plus any fields from an optional metadata hook; failures return fail with the caught error. Install the adapter package and one database client:

pnpm add @healthzkit/sqlite healthzkit
# plus one of:
pnpm add better-sqlite3
pnpm add sqlite3
pnpm add @libsql/client

All drivers are optional peers — install only the one you use.

Package entrypoints

@healthzkit/sqlite - betterSqlite3Adapter, sqlite3Adapter, libsqlAdapter, and their option types.
@healthzkit/sqlite/better-sqlite3 - betterSqlite3Adapter only.
@healthzkit/sqlite/sqlite3 - sqlite3Adapter only.
@healthzkit/sqlite/libsql - libsqlAdapter only.

Use subpath imports when you want to avoid pulling unused drivers into your bundle analysis path.

Shared options

Every factory accepts BaseSqliteOptions:

Option	Description
`query`	SQL executed for the probe. Default `SELECT 1`.
`metadata`	Optional `(client) => Record<string, unknown>` (sync or async) merged into metadata with `latencyMs`.

Pass either connection credentials or an existing client (not both). The shape depends on the adapter (see below).

`betterSqlite3Adapter` (`better-sqlite3`)

Peer: better-sqlite3 >= 12. Runs client.prepare(query).get() and records round-trip latency. Best for embedded SQLite in the same process.

Connection string

Pass connectionString. The adapter lazily imports better-sqlite3, opens the database once, and reuses it across checks.

import { createHealthKit } from "healthzkit";
import { betterSqlite3Adapter } from "@healthzkit/sqlite";

const kit = createHealthKit({
  checks: [
    {
      name: "sqlite",
      type: ["readiness"],
      adapter: betterSqlite3Adapter({
        connectionString: process.env.SQLITE_PATH ?? ":memory:",
        options: { readonly: true },
      }),
    },
  ],
});

connectionString is a file path (for example ./data/app.db) or :memory:.

Existing client

import Database from "better-sqlite3";
import { betterSqlite3Adapter } from "@healthzkit/sqlite/better-sqlite3";

const db = new Database("app.db");

const adapter = betterSqlite3Adapter({
  client: db,
  query: "SELECT sqlite_version()",
  metadata: (client) => ({ path: "app.db" }),
});

`sqlite3Adapter` (`sqlite3`)

Peer: sqlite3 >= 5 or >= 6. Uses the classic callback API: client.get(query, callback). Suitable when you already depend on node-sqlite3.

Connection string

Pass connectionString. The adapter opens the database via new sqlite3.Database(connectionString, mode, callback) and caches the handle. Default open mode is OPEN_READWRITE | OPEN_CREATE.

import { sqlite3Adapter } from "@healthzkit/sqlite/sqlite3";

const adapter = sqlite3Adapter({
  connectionString: "./data/app.db",
  mode: undefined, // optional; defaults to read/write + create
});

Existing client

import sqlite3 from "sqlite3";
import { sqlite3Adapter } from "@healthzkit/sqlite";

const db = new sqlite3.Database(":memory:");

const adapter = sqlite3Adapter({ client: db });

`libsqlAdapter` (`@libsql/client`)

Peer: @libsql/client >= 0.14. Runs await client.execute(query). Use for libSQL and Turso (libsql://, https://, file URLs, and so on).

URL and token

Pass url (and optional authToken). The adapter lazily imports @libsql/client, calls createClient once, and reuses the client across checks.

import { libsqlAdapter } from "@healthzkit/sqlite/libsql";

const adapter = libsqlAdapter({
  url: process.env.TURSO_DATABASE_URL!,
  authToken: process.env.TURSO_AUTH_TOKEN,
});

Existing client

import { createClient } from "@libsql/client";
import { libsqlAdapter } from "@healthzkit/sqlite";

const client = createClient({ url: "file:local.db" });

const adapter = libsqlAdapter({
  client,
  metadata: async () => ({ backend: "libsql" }),
});

Scheduling

For databases that should not be queried on every probe, pair these adapters with a schedule on the check so readiness reads cached results (see Scheduling).

Guide

Adapters

Package entrypoints

Shared options

`betterSqlite3Adapter` (`better-sqlite3`)

Connection string

Existing client

`sqlite3Adapter` (`sqlite3`)

Connection string

Existing client

`libsqlAdapter` (`@libsql/client`)

URL and token

Existing client

Scheduling

​Package entrypoints

​Shared options

​betterSqlite3Adapter (better-sqlite3)

​Connection string

​Existing client

​sqlite3Adapter (sqlite3)

​Connection string

​Existing client

​libsqlAdapter (@libsql/client)

​URL and token

​Existing client

​Scheduling

Package entrypoints

Shared options

`betterSqlite3Adapter` (`better-sqlite3`)

Connection string

Existing client

`sqlite3Adapter` (`sqlite3`)

Connection string

Existing client

`libsqlAdapter` (`@libsql/client`)

URL and token

Existing client

Scheduling