serverless/javascript/README.md
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.
npm install @tursodatabase/serverless
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);
}
// 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 ('[email protected]')",
"INSERT INTO users (email) VALUES ('[email protected]')",
]);
// Parameterized batch statements also work
await conn.transaction(async () => {
await conn.batch([
{ sql: "INSERT INTO users (email) VALUES (?)", args: ["[email protected]"] },
{ sql: "INSERT INTO users (email) VALUES (?)", args: ["[email protected]"] },
]);
}).concurrent();
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" },
});
Headers can also be set per query via the trailing query-options argument.
They apply to that call only and are merged over the connection-level
requestHeaders, so a query can override a header the connection sets:
await conn.all("SELECT * FROM users", {
requestHeaders: { "X-Turso-Request-Identity": "abc123" },
});
// Also accepted by run()/get()/iterate() and prepared statements:
await conn.run("INSERT INTO users (email) VALUES (?)", "[email protected]", {
requestHeaders: { "X-Turso-Request-Identity": "abc124" },
});
Per-query headers are attached to exactly the HTTP request(s) issued by that
call. Inside a conn.transaction(...) callback each statement still carries
only its own per-query headers — the BEGIN/COMMIT/ROLLBACK requests are
issued by the transaction wrapper itself and carry just the connection-level
headers. To stamp every request of a transaction (including BEGIN and
COMMIT), set the header at the connection level, or use an atomic batch,
which sends the whole transaction as a single HTTP request:
// One HTTP request: BEGIN, both inserts, and COMMIT all carry the header.
await conn.batch([
{ sql: "INSERT INTO users (email) VALUES (?)", args: ["[email protected]"] },
{ sql: "INSERT INTO users (email) VALUES (?)", args: ["[email protected]"] },
], "immediate", {
requestHeaders: { "X-Turso-Request-Identity": "abc125" },
});
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 ('[email protected]')",
"INSERT INTO users (email) VALUES ('[email protected]')",
]);
Check out the examples/ directory for complete usage examples.
For complete API documentation, see JavaScript API Reference.
This project is licensed under the MIT license.