@tursodatabase/serverless
TypeScript icon, indicating that this package has built-in type declarations

1.2.3 • Public • Published

Turso Serverless Driver for JavaScript

npm

Chat with other users of Turso on Discord


About

A serverless database driver for Turso Cloud, using only fetch(). Connect to your database from serverless and edge functions, such as Cloudflare Workers and Vercel.

Installation

npm install @tursodatabase/serverless

Getting Started

Basic Usage

import { connect } from "@tursodatabase/serverless";

const conn = connect({
  url: process.env.TURSO_DATABASE_URL,
  authToken: process.env.TURSO_AUTH_TOKEN,
});

// Prepare a statement
const stmt = conn.prepare("SELECT * FROM users WHERE id = ?");

// Get first row
const row = await stmt.get([123]);
console.log(row);

// Get all rows
const rows = await stmt.all([123]);
console.log(rows);

// Iterate through rows (streaming)
for await (const row of stmt.iterate([123])) {
  console.log(row);
}

Batch Operations

// Execute multiple statements in a batch
await conn.batch([
  "CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, email TEXT)",
  "INSERT INTO users (email) VALUES ('user@example.com')",
  "INSERT INTO users (email) VALUES ('admin@example.com')",
]);

// Parameterized batch statements also work
await conn.transaction(async () => {
  await conn.batch([
    { sql: "INSERT INTO users (email) VALUES (?)", args: ["alice@example.com"] },
    { sql: "INSERT INTO users (email) VALUES (?)", args: ["bob@example.com"] },
  ]);
}).concurrent();

Custom Headers

Requests can carry extra HTTP headers, e.g. for routing through a gateway:

const conn = connect({
  url: process.env.TURSO_DATABASE_URL,
  authToken: process.env.TURSO_AUTH_TOKEN,
  // Extra headers attached to every request. Applied after the standard
  // headers, so they can override e.g. `Authorization`. Setting the `Host`
  // key throws — fetch forbids it.
  requestHeaders: { "x-custom-header": "value" },
});

libSQL Compatibility Layer

For existing libSQL applications, use the compatibility layer:

import { createClient } from "@tursodatabase/serverless/compat";

const client = createClient({
  url: process.env.TURSO_DATABASE_URL,
  authToken: process.env.TURSO_AUTH_TOKEN,
});

// Execute a single SQL statement
const result = await client.execute("SELECT * FROM users WHERE id = ?", [123]);
console.log(result.rows);

// Execute multiple statements in a batch
await client.batch([
  "CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, email TEXT)",
  "INSERT INTO users (email) VALUES ('user@example.com')",
  "INSERT INTO users (email) VALUES ('admin@example.com')",
]);

Examples

Check out the examples/ directory for complete usage examples.

API Reference

For complete API documentation, see JavaScript API Reference.

Related Packages

License

This project is licensed under the MIT license.

Support

Readme

Keywords

none