Turso Quickstart (TypeScript)

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

Recommended: @tursodatabase/database (Local / Embedded)

@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.

Install

npm install @tursodatabase/database

Connect

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

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

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);

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.

Recommended: @tursodatabase/serverless (Remote / Over-the-Wire)

@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.

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.

Install

npm install @tursodatabase/serverless

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,
});

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

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

Install

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

npm install @libsql/client

pnpm install @libsql/client

yarn add @libsql/client

deno add npm:@libsql/client

Connect

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

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

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

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

import { createClient } from "https://esm.sh/@libsql/client@0.6.0/web";

export const turso = createClient({
  url: Deno.env.get("TURSO_DATABASE_URL"),
  authToken: Deno.env.get("TURSO_AUTH_TOKEN"),
});

Execute

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

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 local-first sync with explicit push() and pull() operations.

​Recommended: @tursodatabase/database (Local / Embedded)

​Recommended: @tursodatabase/serverless (Remote / Over-the-Wire)

​@libsql/client

Recommended: @tursodatabase/database (Local / Embedded)

Recommended: @tursodatabase/serverless (Remote / Over-the-Wire)

@libsql/client