RonanCodes/turso

Turso (libSQL)

Wire Turso / libSQL into a TanStack Start + Cloudflare Workers app. libSQL is an open-source SQLite fork with native vector search (F32_BLOB, vector_top_k, libsql_vector_idx) that upstream SQLite and Cloudflare D1 do not have. Turso is the managed cloud that hosts it (edge-replicated, JWT-authed, reachable over HTTP).

The headline use case: keep embeddings next to relational rows in one SQLite database, so a single SQL query does the KNN and joins to titles/metadata, no separate vector service to sync against.

Souso note (ADR-0003 / decision #15): smart-cart deliberately chose one D1, no libSQL/Turso, no vector DB (matching is set-maths, and embedded libSQL can't run in a Worker). This skill is a reusable capability; adopting it in Souso contradicts that ADR. The ADR's "can't run in a Worker" point is about the embedded driver, @libsql/client/web reaches Turso over HTTP and DOES work in a Worker, at the cost of a network hop (vs D1's local binding). Decide with that nuance.

Usage

/ro:turso install        # CLI + env + Worker-safe client
/ro:turso add-vectors     # F32_BLOB column + ANN index + KNN query
/ro:turso add-drizzle     # drizzle-orm/libsql + customType vector column
/ro:turso ops             # CLI cheat-sheet (create db, tokens, shell)

Prerequisites

• A Turso account + the CLI (brew install tursodatabase/tap/turso or curl -sSfL https://get.tur.so/install.sh | bash).
• Token in ~/.claude/.env: TURSO_AUTH_TOKEN (a JWT). The megathon one is a group token (authorises every DB in the group), not a single-DB token, both are JWTs and go in the same slot.

The one rule that matters on Workers

Import @libsql/client/web, never @libsql/client.

| Import | Runtime | Transport | Worker? | | --- | --- | --- | --- | | @libsql/client | Node | native + WS + HTTP, supports file: | ❌ pulls native deps, won't bundle | | @libsql/client/web | edge | HTTP only (fetch) | ✅ the Worker import |

The plain import silently works in vite dev/Node then fails to bundle on Workers. Make /web non-negotiable. (Newer forward path: @tursodatabase/serverless — pure fetch, edge-first, with a /compat shim; @libsql/client/web is the battle-tested, Drizzle-proven default this skill uses.)

Install flow

1. CLI / create a DB (ops cheat-sheet)

turso db create smart-cart                 # create
turso db show smart-cart --url             # -> TURSO_DATABASE_URL (libsql://<db>-<org>.turso.io)
turso db tokens create smart-cart          # DB-scoped JWT
turso group tokens create <group>          # GROUP JWT (all DBs in the group) — what the megathon token is
turso db shell smart-cart                  # interactive SQL against the remote DB

2. Env

# .dev.vars (gitignored)
TURSO_DATABASE_URL=libsql://<db>-<org>.turso.io
TURSO_AUTH_TOKEN=<jwt>

wrangler secret put TURSO_DATABASE_URL
wrangler secret put TURSO_AUTH_TOKEN

There is no wrangler.jsonc binding (unlike D1), you connect with URL + token at runtime. Read them off env inside the handler.

3. Worker-safe client, src/lib/turso.ts

pnpm add @libsql/client

import { createClient } from '@libsql/client/web' // /web = HTTP-only, Worker-safe

export function getTurso(env: { TURSO_DATABASE_URL: string; TURSO_AUTH_TOKEN: string }) {
  return createClient({ url: env.TURSO_DATABASE_URL, authToken: env.TURSO_AUTH_TOKEN })
}

Construct it inside the request handler with the env binding, not at module top level.

add-vectors (the point)

Native vector columns + ANN index + KNN. Verified function names (docs.turso.tech/features/ai-and-embeddings):

• Column: F32_BLOB(<dim>) (32-bit float vector, fixed dimensionality).
• Insert: vector32('[...]') converts a JSON-array string to the blob (vector(...) is an alias).
• ANN index: CREATE INDEX <idx> ON <tbl>(libsql_vector_idx(<col>, 'metric=cosine')). The libsql_vector_idx() marker is required (it's how libSQL marks an ANN index). Add compress_neighbors=float8 to shrink it.
• KNN: vector_top_k('<idx>', vector32('[...]'), <k>) is a table-valued function returning id (= rowid); join back for columns.
• Distance: vector_distance_cos(a, b) → cosine distance (0..2).

CREATE TABLE recipe (
  id        INTEGER PRIMARY KEY,
  title     TEXT,
  embedding F32_BLOB(1536)            -- e.g. OpenAI text-embedding dim
);
CREATE INDEX recipe_idx ON recipe(libsql_vector_idx(embedding, 'metric=cosine'));

INSERT INTO recipe (title, embedding)
VALUES ('Stamppot', vector32('[0.012, -0.044, 0.91, ...]'));

-- 5 nearest neighbours to a query embedding, with distance
SELECT recipe.id, recipe.title,
       vector_distance_cos(recipe.embedding, vector32('[...query...]')) AS dist
FROM vector_top_k('recipe_idx', vector32('[...query...]'), 5)
JOIN recipe ON recipe.rowid = id
ORDER BY dist;

Index-syntax warning: the Turso Drizzle docs page shows ... USING vector_cosine(3) — that is stale/incorrect. Use libsql_vector_idx(col[, 'metric=cosine']) (the canonical engine syntax). Confirm against your libSQL version. ANN is approximate (DiskANN), top-k is approximate NN, not exact.

add-drizzle

pnpm add drizzle-orm @libsql/client

import { drizzle } from 'drizzle-orm/libsql'
import { createClient } from '@libsql/client/web' // /web for Workers
const client = createClient({ url: env.TURSO_DATABASE_URL, authToken: env.TURSO_AUTH_TOKEN })
export const db = drizzle(client)

F32_BLOB has no first-class Drizzle column, define a customType:

import { customType } from 'drizzle-orm/sqlite-core'
import { sql } from 'drizzle-orm'

const float32Array = customType<{
  data: number[]
  config: { dimensions: number }
  configRequired: true
  driverData: Buffer
}>({
  dataType(config) {
    return `F32_BLOB(${config.dimensions})`
  },
  fromDriver(value: Buffer) {
    return Array.from(new Float32Array(value.buffer))
  },
  toDriver(value: number[]) {
    return sql`vector32(${JSON.stringify(value)})`
  },
})

export const recipe = sqliteTable('recipe', {
  id: integer('id').primaryKey(),
  title: text('title'),
  embedding: float32Array('embedding', { dimensions: 1536 }),
})

vector_top_k is raw SQL (no query builder), and the ANN index goes in a hand-written migration (drizzle-kit won't generate libsql_vector_idx):

const rows = await db
  .select({ id: sql`id`, distance: sql`distance` })
  .from(sql`vector_top_k('recipe_idx', vector32(${JSON.stringify(queryVec)}), 5)`)
  .leftJoin(recipe, sql`${recipe}.id = id`)

(Cosmetic: drizzle-kit push flags customType columns as "changed" each run — drizzle-orm #3047, harmless.)

Workers gotchas

1. /web import or it breaks (silently fine in Node, fails to bundle on Workers).
2. It's an HTTP hop, not a binding. One round-trip to *.turso.io per query. Use batch([...]) (one request, implicit all-or-nothing transaction) to fold statements; keep the DB region near the Worker. Avoid interactive transaction() on Workers (holds a write lock ~5s, latency-sensitive).
3. No embedded replicas / sync on Workers (they need a local file: DB; Workers have no filesystem). Always remote-over-HTTP.
4. Credentials are runtime secrets (URL + token), not committed config.

When Turso vectors win

• vs Cloudflare Vectorize: Vectorize is a separate vector-only service, you'd sync IDs between it and D1. Turso keeps vectors + relational rows in one DB so one query does KNN + join. Pick Turso when embeddings sit next to data you already query.
• vs pgvector: Turso wins on SQLite simplicity + edge replication + no Postgres to run, at SQLite-fitting scale. pgvector wins at very large datasets / complex filtered ANN / existing Postgres.
• vs D1: D1 is a zero-latency local binding but has no vector type/ANN (you'd hand-roll slow similarity or bolt on Vectorize). Turso gives F32_BLOB + vector_top_k out of the box. Choose D1 for the local binding with no vectors; Turso when vectors-in-the-DB is the requirement.

Env var summary

TURSO_DATABASE_URL=libsql://<db>-<org>.turso.io
TURSO_AUTH_TOKEN=<jwt>     # DB or group token; server-only secret

Safety

Server-side only; URL + token are secrets. On Workers always @libsql/client/web. Vector indexes and the customType column go in hand-written migrations, review them.

See also

• Docs: AI/embeddings https://docs.turso.tech/features/ai-and-embeddings, SDK https://docs.turso.tech/sdk/ts/quickstart, Drizzle https://docs.turso.tech/sdk/ts/orm/drizzle
• Alternatives: /ro:neon (Postgres + pgvector), Cloudflare Vectorize, D1. Sibling data skills: /ro:cala, /ro:posthog