libsqlproxy

library0.1.0jsnpmunverified

Runtime-agnostic Hrana v2 HTTP server for SQLite that exposes any SQLite database (Cloudflare Durable Objects, libsql, better-sqlite3) via the libSQL remote protocol. Current stable version 0.1.0. Designed for connecting data explorers like Drizzle Studio and TablePlus to Durable Object storage or Node.js SQLite databases. Key differentiators: supports multiple backends (Durable Objects, libsql, custom drivers), includes Cloudflare Workers proxy for DO routing via namespace:secret auth, and provides both fetch-style and Node.js http handler adapters.

database

npm install libsqlproxy

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LIBSQLPROXY

libsqlproxy

databasejavascriptv0.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createLibsqlHandler

✓ import { createLibsqlHandler } from 'libsqlproxy'

✗ const createLibsqlHandler = require('libsqlproxy').createLibsqlHandler

ESM-only package; no CommonJS support.

durableObjectExecutor

✓ import { durableObjectExecutor } from 'libsqlproxy'

✗ import { DurableObjectExecutor } from 'libsqlproxy'

The executor factory is a lowercase function, not a class.

libsqlExecutor

✓ import { libsqlExecutor } from 'libsqlproxy'

✗ import { createLibsqlExecutor } from 'libsqlproxy'

Function name is 'libsqlExecutor', not 'createLibsqlExecutor'.

createLibsqlNodeHandler

✓ import { createLibsqlNodeHandler } from 'libsqlproxy'

✗ import { createLibsqlHandler, createNodeHandler } from 'libsqlproxy'

The Node.js adapter has a distinct name: 'createLibsqlNodeHandler'.

Sets up a local libsqlproxy server with an in-memory SQLite database, wrapped for Node.js HTTP, requiring authentication via Bearer token.

import http from 'node:http'; import Database from 'libsql'; import { createLibsqlHandler, createLibsqlNodeHandler, libsqlExecutor } from 'libsqlproxy'; const database = new Database(':memory:'); database.exec("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)"); database.exec("INSERT INTO users VALUES (1, 'Alice')"); const handler = createLibsqlHandler(libsqlExecutor(database)); const nodeHandler = createLibsqlNodeHandler(handler, { auth: { bearer: process.env.LIBSQL_SECRET ?? 'my-secret-token' }, }); http.createServer(nodeHandler).listen(8080, () => { console.log('libsqlproxy listening on http://localhost:8080'); });

Debug

Known issues

gotchaauthToken for Cloudflare proxy expects 'namespace:secret' format, not just a bearer token.

fix

Use format 'my-durable-object-id:my-shared-secret' as the authToken when connecting via @libsql/client.

affects: >=0.1.0

gotchaThe `createLibsqlProxy` function requires a `getStub` callback that returns a Durable Object stub; the stub must have a `hranaHandler` property (from `createLibsqlHandler`).

fix

Ensure your Durable Object class stores the handler as `this.hranaHandler = createLibsqlHandler(durableObjectExecutor(this.ctx.storage))`.

affects: >=0.1.0

gotchaExecutors can be sync or async; if your custom executor is sync but the handler expects async, wrap it with `Promise.resolve()`.

fix

If using a sync executor, ensure `executeSql` returns an object (not a Promise) and `execRaw` returns void (undefined).

affects: >=0.1.0

Errors

Common errors & fixes

Error: No handler found for this request

The request URL does not match the configured namespace route; or the `getStub` callback returned undefined/null.

fix

Check that the `getStub` callback returns a valid Durable Object stub, and that the `namespace` extracted from authToken matches a valid DO ID.

TypeError: libsql is not a function

Misnamed import: `Database` from 'libsql' is not a default export in some versions; or using CJS require with ESM-only package.

fix

Use `import Database from 'libsql'` (ESM) and ensure 'libsql' is installed. If using CJS, use dynamic import: `const { default: Database } = await import('libsql')`.

Cannot find module 'libsqlproxy' or its corresponding type declarations.

TypeScript cannot resolve the module; likely missing `types` field or using an older TS version that doesn't read package.json exports.

fix

Ensure TypeScript is configured with `moduleResolution: "node16"` or `"bundler"` and `skipLibCheck: false`. Also check that the package is installed correctly.

Error: 401 Unauthorized

Missing or invalid Bearer token in the request headers.

fix

Pass an `auth.token` option to `createLibsqlNodeHandler` or `createLibsqlProxy` and ensure the client sends a valid `authToken` matching the expected secret.

Upgrade

Version history

0.1.0latest on npm

Audit

Dependencies

@libsql/clientoptionalUsed as the client to connect to the proxy; not a runtime dependency but the primary consumer

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/remorses/kimaki ↗

packagelibsqlproxy ↗

homepagehttps://github.com/remorses/kimaki/tree/main/libsqlproxy ↗