Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.turso.tech/llms.txt

Use this file to discover all available pages before exploring further.

In this TypeScript quickstart we will learn how to:
  • Install the Turso package
  • Connect to a local or remote database
  • Execute a query using SQL
  • Sync changes to the cloud
@tursodatabase/database is the recommended package for local and embedded use cases (Node.js, Electron, mobile, IoT). It is built on the Turso Database engine — a ground-up rewrite of SQLite with concurrent writes (MVCC) and async I/O.
1

Install

npm install @tursodatabase/database
2

Connect

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

const db = await connect("app.db");
3

Execute

const createTable = db.prepare(`
  CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    username TEXT NOT NULL
  )
`);
await createTable.run();

const insertUser = db.prepare("INSERT INTO users (username) VALUES (?)");
await insertUser.run("alice");

const stmt = db.prepare("SELECT * FROM users");
const users = await stmt.all();
console.log(users);
4

Sync (push and pull)

If you need to sync your local database with Turso Cloud, use @tursodatabase/sync:
npm install @tursodatabase/sync

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

const db = await connect({
  path: "./app.db",
  url: process.env.TURSO_DATABASE_URL,
  authToken: process.env.TURSO_AUTH_TOKEN,
});

await db.exec("INSERT INTO users (username) VALUES ('bob')");

// Push local writes to Turso Cloud
await db.push();

// Pull remote changes to local database
const changed = await db.pull();
All reads and writes happen against the local database file — fast, offline-capable. push() sends your changes to the cloud. pull() brings remote changes down. See Turso Sync for details on conflict resolution, checkpointing, and more.
@tursodatabase/serverless is the recommended package for any application that connects to a remote Turso Cloud database over the network — including Node.js servers, Docker containers, serverless functions, and edge runtimes (Cloudflare Workers, Vercel Edge, Deno Deploy). It uses only fetch — zero native dependencies, works everywhere.
1

Retrieve database credentials

You will need an existing database to continue. If you don’t have one, create one.Get the database URL:
turso db show --url <database-name>
Get the database authentication token:
turso db tokens create <database-name>
Assign credentials to the environment variables inside .env.
TURSO_DATABASE_URL=
TURSO_AUTH_TOKEN=
You will want to store these as environment variables.
2

Install

npm install @tursodatabase/serverless
3

Connect to your database

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

const conn = connect({
  url: process.env.TURSO_DATABASE_URL,
  authToken: process.env.TURSO_AUTH_TOKEN,
});
For compatibility with the @libsql/client API, use the compat module:
import { createClient } from "@tursodatabase/serverless/compat";

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

Execute a query using SQL

const stmt = await conn.prepare("SELECT * FROM users");
const rows = await stmt.all();
If you need to use placeholders for values, you can do that:
const stmt = await conn.prepare("SELECT * FROM users WHERE id = ?");
const row = await stmt.get([1]);

​
@libsql/client (ORM & Legacy)

Use @libsql/client for ORM integration (Drizzle, Prisma) or if you have an existing codebase built on it. See the reference for full documentation.
1

Install

Begin by installing the @libsql/client dependency in your project:
npm install @libsql/client
2

Connect

import { createClient } from "@libsql/client";

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

Execute

await turso.execute("SELECT * FROM users");
4

Sync

If you need to sync your local database with a remote Turso Cloud database (local reads and writes with push/pull to the cloud), use Turso Sync. Turso Sync is built on the Turso Database engine and provides true local-first sync with explicit push() and pull() operations.