Limits on automatic type conversion for custom objects in Bun.SQLite prepared statements

Bun.SQLite does not automatically serialize custom JavaScript objects, such as Date instances or custom classes, when binding parameters to prepared statements. Developers must manually convert these values to SQLite-compatible primitives (strings, numbers, blobs, or nulls) before passing them to the run or get methods. Unlike high-level ORMs that perform deep serialization, the bun:sqlite module is designed for performance and maps values directly to SQLite's storage classes. This means it does not look for JavaScript-specific serialization methods during the bind phase.

Key Behavioral Constraints

• No Automatic toJSON/valueOf: The binder does not invoke toJSON() or valueOf() on objects passed as parameters. If you pass a custom object, the runtime will not resolve it to a string automatically.
• Error on Unsupported: If an unsupported object (like a plain class instance) is bound, the operation typically throws an error rather than storing [object Object] or NULL.
• Primitive Mapping: Bun.SQLite handles standard primitives: number, string, null, boolean (converted to 0 or 1), and Uint8Array/Buffer (stored as BLOB).

Manual Conversion Strategy

Since there is no documented mechanism to register global custom type converters in Bun.SQLite, you should handle serialization in your data access layer.

import { SQLite } from "bun";

const db = new SQLite(":memory:");
db.run("CREATE TABLE events (id INTEGER, created_at TEXT, data TEXT)");

const insert = db.prepare("INSERT INTO events (created_at, data) VALUES (?, ?)");

// Manual conversion is required
const eventDate = new Date();
const customData = { action: "login", priority: 10 };

insert.run(eventDate.toISOString(), JSON.stringify(customData));

Verification

To verify the behavior in your specific Bun version, run this test script:

try {
  const db = new SQLite(":memory:");
  db.run("CREATE TABLE test (val TEXT)");
  const stmt = db.prepare("INSERT INTO test VALUES (?)");
  // This is expected to throw an error in current versions
  stmt.run({ custom: "object" });
} catch (e) {
  console.log("Caught expected error:", e.message);
}