Terminal.skills
Skills/turso
>

turso

You are an expert in Turso, the SQLite-based database platform for production workloads. You help developers use libSQL (Turso's SQLite fork) as a primary database with features like embedded replicas (SQLite file synced from cloud), multi-region replication, vector search, branching, and edge deployment — providing sub-millisecond reads with the simplicity of SQLite and the durability of a cloud database.

#database#sqlite#edge#serverless#libsql#embedded#sync
terminal-skillsv1.0.0
Works with:claude-codeopenai-codexgemini-clicursor
Source

Usage

$
✓ Installed turso v1.0.0

Getting Started

  1. Install the skill using the command above
  2. Open your AI coding agent (Claude Code, Codex, Gemini CLI, or Cursor)
  3. Reference the skill in your prompt
  4. The AI will use the skill's capabilities automatically

Example Prompts

  • "Review the open pull requests and summarize what needs attention"
  • "Generate a changelog from the last 20 commits on the main branch"

Information

Version
1.0.0
Author
terminal-skills
Category
Backend Development
License
Apache-2.0

Use Cases

→Build a SaaS App with SvelteKit and Turso
→Build a Globally Distributed API with Hono + Turso on Cloudflare Workers

Documentation

You are an expert in Turso, the SQLite-based database platform for production workloads. You help developers use libSQL (Turso's SQLite fork) as a primary database with features like embedded replicas (SQLite file synced from cloud), multi-region replication, vector search, branching, and edge deployment — providing sub-millisecond reads with the simplicity of SQLite and the durability of a cloud database.

Core Capabilities

Client Setup

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

// Remote database
const db = createClient({
  url: process.env.TURSO_DATABASE_URL!,    // libsql://my-db-org.turso.io
  authToken: process.env.TURSO_AUTH_TOKEN!,
});

// Embedded replica (local SQLite file synced from cloud)
const db = createClient({
  url: "file:local-replica.db",            // Local file for reads
  syncUrl: process.env.TURSO_DATABASE_URL!, // Cloud for writes + sync
  authToken: process.env.TURSO_AUTH_TOKEN!,
  syncInterval: 60,                        // Sync every 60 seconds
});
await db.sync();                           // Manual sync

// Queries
const users = await db.execute("SELECT * FROM users WHERE active = 1");
console.log(users.rows);                   // [{id: 1, name: "Alice", ...}]

// Parameterized queries (safe from SQL injection)
const user = await db.execute({
  sql: "SELECT * FROM users WHERE id = ?",
  args: [userId],
});

// Insert
await db.execute({
  sql: "INSERT INTO users (name, email, created_at) VALUES (?, ?, datetime('now'))",
  args: ["Bob", "bob@example.com"],
});

// Transactions
await db.batch([
  { sql: "UPDATE accounts SET balance = balance - ? WHERE id = ?", args: [100, fromAccount] },
  { sql: "UPDATE accounts SET balance = balance + ? WHERE id = ?", args: [100, toAccount] },
  { sql: "INSERT INTO transfers (from_id, to_id, amount) VALUES (?, ?, ?)", args: [fromAccount, toAccount, 100] },
], "write");

Vector Search

typescript
// Create table with vector column
await db.execute(`
  CREATE TABLE IF NOT EXISTS documents (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    content TEXT NOT NULL,
    embedding F32_BLOB(1536)
  )
`);

// Insert with embedding
await db.execute({
  sql: "INSERT INTO documents (content, embedding) VALUES (?, vector32(?))",
  args: [text, JSON.stringify(embedding)],  // 1536-dim float array
});

// Vector similarity search
const similar = await db.execute({
  sql: `SELECT content, vector_distance_cos(embedding, vector32(?)) AS distance
        FROM documents
        ORDER BY distance ASC
        LIMIT 10`,
  args: [JSON.stringify(queryEmbedding)],
});

Drizzle ORM Integration

typescript
import { drizzle } from "drizzle-orm/libsql";
import { sqliteTable, text, integer, real } from "drizzle-orm/sqlite-core";

const products = sqliteTable("products", {
  id: integer("id").primaryKey({ autoIncrement: true }),
  name: text("name").notNull(),
  price: real("price").notNull(),
  category: text("category"),
});

const orm = drizzle(db);

const cheapProducts = await orm.select()
  .from(products)
  .where(lt(products.price, 50))
  .orderBy(asc(products.price));

Installation

bash
npm install @libsql/client

# CLI
brew install tursodatabase/tap/turso       # macOS
curl -sSfL https://get.tur.so/install.sh | bash  # Linux

turso db create my-app
turso db tokens create my-app              # Get auth token

Best Practices

  1. Embedded replicas — Use local SQLite file for reads (<1ms); sync from cloud; best for read-heavy apps
  2. Edge deployment — Create replicas in multiple regions; reads are local, writes route to primary
  3. Batch transactions — Use db.batch() for multi-statement transactions; atomic execution
  4. Vector search — Use F32_BLOB type for embeddings; built-in cosine distance without extensions
  5. Parameterized queries — Always use args for user input; never string interpolation
  6. Sync interval — Tune syncInterval based on freshness needs; lower = more current, higher = less bandwidth
  7. Branching — Use turso db create --from-db for dev/staging copies; test migrations safely
  8. Drizzle integration — Use Drizzle ORM for type-safe queries; drizzle-orm/libsql driver available