Bunny Database Client

@bunny.net/database-client is a small SQL client for Bunny Database. It has no dependencies, and fetch is the only runtime API it touches, so the same code runs on Bunny Edge Scripting (Deno), Bun, and Node.

Bunny Database is currently in Public Preview. Features and APIs may evolve during this period.

Server-side only. Never ship this to a browser or any other untrusted client.An auth token grants access to the whole database, and this client sends raw SQL. Put either one in client-side code and every visitor can read and write every table, whatever your UI happens to offer them. Why not the browser has the details.

Install

npm install @bunny.net/database-client

pnpm add @bunny.net/database-client

yarn add @bunny.net/database-client

bun add @bunny.net/database-client

Quickstart

connect() reads BUNNY_DATABASE_URL and BUNNY_DATABASE_AUTH_TOKEN from the environment. Edge Scripting already sets both, bunny db quickstart --lang typescript prints them for you, and bunny db create --token --save-env writes them straight to .env:

import { connect } from "@bunny.net/database-client";

const db = connect();

const user = await db.prepare("SELECT * FROM users WHERE id = ?").bind(1).first();

Pass them explicitly when you need to:

const db = connect({
  url: "libsql://your-db.lite.bunnydb.net",
  authToken: "your-token",
});

Runnable examples for Edge Scripting, Bun, Node, Hono, Next.js, Astro, and SvelteKit live in packages/database-client/examples.

API

`connect(config?)`

Returns a Database. Every option is optional.

Option	Type	Default	Description
`url`	`string`	`BUNNY_DATABASE_URL`	`libsql://`, `https://`, or `http://` connection URL.
`authToken`	`string`	`BUNNY_DATABASE_AUTH_TOKEN`	Sent as `Authorization: Bearer <token>`.
`fetch`	`typeof fetch`	global `fetch`	Override for testing, tracing, or a custom agent.
`headers`	`Record<string, string>`	none	Extra headers on every request.
`signal`	`AbortSignal`	none	Applied to every request.
`timeout`	`number`	none	Milliseconds before a single request is aborted. A positive integer up to 2147483647.

The client rewrites a libsql:// URL to https://. It rejects credentials in the URL, both user:pass@ and an authToken query parameter, so pass authToken instead. Dropping a token silently would leave you debugging an unexplained 401. Every request carries User-Agent: bunny-database-client. The client matches header names case-insensitively, so your own User-Agent replaces that default and only one of the two goes out. Without timeout a request waits as long as the runtime allows, which on an edge function means a hung fetch can burn the whole invocation. timeout and signal compose: whichever fires first aborts the request.

`db.prepare(sql)`

Returns a Statement. Statements are immutable, so you can keep one around and bind it as often as you like.

const byId = db.prepare("SELECT * FROM users WHERE id = ?");

const alice = await byId.bind(1).first();
const bob = await byId.bind(2).first();

Pass a row type to have it flow through every execution of that statement. See Types.

db.sql`...`

A template literal that binds every interpolated value, so the shortest way to write a query is also the parameterized one:

const note = await db.sql`SELECT * FROM notes WHERE id = ${id}`.first();

Each ${...} becomes a ? placeholder, and the client binds the value without ever splicing it into the SQL string. It returns a Statement, so everything under Executing applies unchanged. Values follow the same rules as bind(), with one exception: an interpolated object throws. Inside a template it is nearly always a mistake, so named parameters go through bind(). Pass a row type the same way as prepare(), as db.sql<User>`...` . SQLite parameterizes values and nothing else, so a table or column name that has to vary belongs in the SQL string you build with prepare().

`statement.bind(...values)`

Binds parameters and returns a new statement. Accepts null, boolean, number, bigint, string, and Uint8Array. Pass values in order for ? placeholders:

await db.prepare("SELECT * FROM users WHERE id = ? AND active = ?").bind(1, true).all();

Pass a single object for SQLite’s named forms, :name, @name, and $name:

await db
  .prepare("SELECT * FROM users WHERE id = :id AND active = :active")
  .bind({ id: 1, active: true })
  .all();

Names may carry the sigil or leave it off, so { id: 1 } and { ":id": 1 } both bind :id. One statement uses one style, and mixing positional values with an object in the same bind() call throws. The client will not pick a winner for you. undefined throws. A mistyped property such as bind(user.nmae) surfaces at the call site, and nothing writes NULL on your behalf. Pass null when you mean NULL. Any other value throws, because SQLite has nowhere to put it. Date gets its own message pointing at .toISOString() and .getTime(). The client will not choose for you, since each one puts something different in the column. The client sends an integer number as INTEGER for as long as it fits exactly, up to 2^53. Past that every double is a whole number, so the client sends it as REAL and SQLite stores the value as is. Pass a bigint when you need an exact integer that large. Bigints must fit SQLite’s signed 64-bit range.

Executing

Four ways to run a statement:

const rows = await db.prepare("SELECT id, name FROM users").all();
// [{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }]

const row = await db.prepare("SELECT * FROM users WHERE id = ?").bind(1).first();
// { id: 1, name: "Alice" }  or  null

const name = await db.prepare("SELECT name FROM users WHERE id = ?").bind(1).first("name");
// "Alice"  or  null

const rawRows = await db.prepare("SELECT id, name FROM users").raw();
// [[1, "Alice"], [2, "Bob"]]

run() returns rows plus write metadata:

const result = await db
  .prepare("INSERT INTO users (name) VALUES (?) RETURNING id")
  .bind("Carol")
  .run();

// {
//   rows: [{ id: 3 }],
//   columns: ["id"],
//   rowsAffected: 1,
//   lastInsertRowid: 3,
// }

runRaw() returns the same metadata with rows as positional arrays. Reach for it when a result may contain two columns of the same name, since object rows keep only the last one:

const result = await db.prepare("SELECT a.id, b.id FROM a JOIN b").runRaw();
// { rows: [[1, 99]], columns: ["id", "id"], rowsAffected: 0, lastInsertRowid: null }

Statements do nothing until one of these is called, so prepare() and bind() are safe to pass around.

`db.batch(statements, options?)`

Runs every statement in one transaction and one round trip. All of them commit or none do.

const [inserted, count] = await db.batch([
  db.prepare("INSERT INTO users (name) VALUES (?)").bind("Dan"),
  db.prepare("SELECT COUNT(*) AS c FROM users"),
]);

You get one Result per statement you passed, in order. batchRaw() does the same with positional rows. If any statement fails the transaction rolls back and batch() throws that statement’s error, with error.batchIndex set to the position of the statement that failed. The batch is the transaction, so the client rejects a statement of your own that starts with BEGIN, COMMIT, END, or

Documentation

Connect

Tools

Reference

Install

Quickstart

API

`connect(config?)`

`db.prepare(sql)`

db.sql`...`

`statement.bind(...values)`

Executing

`db.batch(statements, options?)`

​Install

​Quickstart

​API

​connect(config?)

​db.prepare(sql)

​db.sql`...`

​statement.bind(...values)

​Executing

​db.batch(statements, options?)

Install

Quickstart

API

`connect(config?)`

`db.prepare(sql)`

db.sql`...`

`statement.bind(...values)`

Executing

`db.batch(statements, options?)`