DOCSEARCHbyAlgolia
Submit Docs

libSQL TypeScript Client

repository·main·Indexed 20 days ago

https://github.com/tursodatabase/libsql-client-ts

A client library for multi-tenant TypeScript and JavaScript applications providing connectivity to Turso databases. It supports remote database connectivity, Embedded Replicas for offline capabilities, vector search, and encryption at rest. The library includes the @libsql/client driver and an experimental WASM client (@libsql/libsql-wasm-experimental) for WebAssembly environments.

Tokens
9.9K
Snippets
42
Records
53
Agent score
68%

What's inside libsql-client-ts

  1. Use @libsql/client vs @tursodatabase/serverless

    main

    When choosing a driver for your TypeScript/JS application, consider the following:

    • @libsql/client: A battle-tested driver suitable for most use cases, including those requiring ORM integration.
    • @tursodatabase/serverless: The lightest option with zero native dependencies. It is designed for serverless environments and will eventually support concurrent writes.

  2. Quickstart with Embedded Replicas

    main

    You can use Embedded Replicas to work with a local SQLite file that periodically synchronizes with a remote Turso database. This allows for offline capabilities and low-latency local reads.

    To set this up, use createClient with a url pointing to a local file, a syncUrl for the remote database, and an authToken. The syncInterval determines how often the local database syncs with the remote server (in milliseconds).

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

export const turso = createClient({
    url: "file:local.db",
    syncUrl: process.env.TURSO_DATABASE_URL,
    authToken: process.env.TURSO_AUTH_TOKEN,
    syncInterval: 60000,
});

// Execute a batch of operations
await turso.batch(
    [
        "CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT)",
        {
            sql: "INSERT INTO users(name) VALUES (?)",
            args: ["Iku"],
        },
    ],
    "write",
);

// Execute a single query
await turso.execute({
    sql: "SELECT * FROM users WHERE id = ?",
    args: [1],
});

  7. Run the Sync example

    main

    The Sync example demonstrates how to use libSQL with a synced database, where a local file is kept in sync with a remote database. To run this example, you must provide your remote database URL and authentication token as environment variables.

    This process connects to a remote SQLite database, performs data insertion, and then queries the results.

    TURSO_DATABASE_URL="..." TURSO_AUTH_TOKEN="..." node index.mjs

  8. Build the libSQL Wasm browser example

    main

    To build the browser example, you must first build the core WASM package and then bundle the example code using esbuild. This requires copying the sqlite3.wasm file from the core package into the example's dist directory.

    # 1. Build the core WASM package
cd packages/libsql-client-wasm
npm run build

# 2. Build the browser example
cd packages/libsql-client-wasm/examples/browser
npm i
./node_modules/.bin/esbuild --target=safari16 index.js --bundle --outfile=dist/out.js --format=esm
cp ../../../../node_modules/@libsql/libsql-wasm-experimental/sqlite-wasm/jswasm/sqlite3.wasm dist

  10. Run the local libSQL SQLite example

    main

    This example demonstrates how to use libsql-client-ts with a local SQLite file. The process involves setting up a local database, inserting data, and performing queries.

    To run the example, ensure you have installed the dependencies first.

    # Install dependencies
npm i

# Run the example
node index.mjs

  11. Run the Ollama + Vector Search Example

    main

    This example demonstrates how to integrate libSQL vector search with a local database and Ollama. The workflow involves setting up a local SQLite database, generating embeddings via Ollama, inserting data with those embeddings, and performing vector similarity searches.

    Prerequisites

    1. Install Dependencies: Run npm i in the example directory.
    2. Install Ollama: Download and install Ollama from ollama.com.
    3. Prepare Model: Ensure Ollama is running with the mistral model loaded.

    Execution Steps

    1. Start the required model:
      ollama run mistral
    2. Run the example script:
      node index.mjs
    npm i
ollama run mistral
node index.mjs