Package Exports

libsqlproxy
libsqlproxy/package.json
libsqlproxy/src
libsqlproxy/src/durable-object-executor
libsqlproxy/src/executor
libsqlproxy/src/handler
libsqlproxy/src/handler.test
libsqlproxy/src/index
libsqlproxy/src/libsql-executor
libsqlproxy/src/node-handler
libsqlproxy/src/protocol
libsqlproxy/src/protocol.test
libsqlproxy/src/proxy
libsqlproxy/src/types
libsqlproxy/src/values
libsqlproxy/src/values.test

Readme

libsqlproxy

Runtime-agnostic Hrana v2 HTTP server for SQLite. Expose any SQLite database via the libSQL remote protocol.

Expose your Cloudflare Durable Object data to data explorers like Drizzle Studio and TablePlus so you can browse, edit, and manage your DO storage from a GUI. Also works with Node.js libsql, better-sqlite3, or any custom SQL driver.

Connect with @libsql/client, Drizzle Studio, TablePlus, or any tool that speaks the libSQL remote protocol.

Install

npm install libsqlproxy

Cloudflare Workers + Durable Objects

Expose a Durable Object's embedded SQLite over the libSQL protocol.

wrangler.json:

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-03-20",
  "routes": [
    { "pattern": "libsql.example.com", "custom_domain": true },
    { "pattern": "example.com", "custom_domain": true }
  ],
  "durable_objects": {
    "bindings": [
      { "name": "MY_DO", "class_name": "MyDO" }
    ]
  }
}

Durable Object (src/my-do.ts):

import { DurableObject } from 'cloudflare:workers'
import { createLibsqlHandler, durableObjectExecutor } from 'libsqlproxy'

export class MyDO extends DurableObject {
  hranaHandler = createLibsqlHandler(durableObjectExecutor(this.ctx.storage))
}

Worker (src/index.ts):

import { createLibsqlProxy } from 'libsqlproxy'

export default {
  async fetch(request: Request, env: Env) {
    const url = new URL(request.url)

    // Only handle libsql proxy on the dedicated hostname
    if (url.hostname.startsWith('libsql.')) {
      const proxy = createLibsqlProxy({
        secret: env.LIBSQL_SECRET,
        getStub: ({ namespace, env }) => {
          const id = env.MY_DO.idFromString(namespace)
          return env.MY_DO.get(id)
        },
      })
      return proxy(request, env)
    }

    // Normal Worker logic
    return new Response('Hello')
  },
}

Connect from anywhere:

import { createClient } from '@libsql/client'

const client = createClient({
  url: 'https://libsql.example.com',
  authToken: 'my-durable-object-id:my-shared-secret',
  //          ^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
  //          namespace (DO ID)       shared secret
})

await client.execute('SELECT * FROM users')

The authToken format is namespace:secret where:

namespace identifies which Durable Object to route to
secret is validated against the shared secret configured in the Worker

This works with TablePlus, Drizzle Studio, and any tool that accepts a libSQL URL + auth token.

Node.js

import http from 'node:http'
import Database from 'libsql'
import {
  createLibsqlHandler,
  createLibsqlNodeHandler,
  libsqlExecutor,
} from 'libsqlproxy'

const database = new Database('my.db')
const handler = createLibsqlHandler(libsqlExecutor(database))
const nodeHandler = createLibsqlNodeHandler(handler, {
  auth: { bearer: 'my-secret-token' },
})

http.createServer(nodeHandler).listen(8080)
// Connect with: libsql://localhost:8080, authToken: 'my-secret-token'

Custom SQL Driver

Implement the LibsqlExecutor interface for any database:

import { createLibsqlHandler } from 'libsqlproxy'

const handler = createLibsqlHandler({
  executeSql(sql, params) {
    // Return { cols, rows, affected_row_count, last_insert_rowid }
    return myDriver.query(sql, params)
  },
  execRaw(sql) {
    // Execute raw SQL (multiple statements, no results)
    myDriver.exec(sql)
  },
})

// handler is (Request) => Promise<Response>

Both sync and async executors are supported.

API

Export	Description
`createLibsqlHandler(executor)`	Core handler. Takes a `LibsqlExecutor`, returns `(Request) => Promise<Response>`
`createLibsqlNodeHandler(handler, opts?)`	Node.js adapter. Wraps the fetch handler for `http.createServer()`
`createLibsqlProxy(opts)`	Cloudflare Worker proxy. Parses `namespace:secret` from Bearer token, routes to DO
`libsqlExecutor(database)`	Adapter for `libsql` / `better-sqlite3`
`durableObjectExecutor(storage)`	Adapter for CF Durable Object `ctx.storage`

Protocol Support

Implements the Hrana v2 HTTP protocol:

execute - single statement with positional/named params
batch - multi-step conditional execution (ok/not/and/or)
sequence - raw SQL semicolon-separated execution
describe - column/parameter info without executing
store_sql / close_sql - stream-scoped SQL caching
close - stream teardown
Baton-based stateful streams for interactive transactions

License

MIT