libsql-client-skilld

name	libsql-client-skilld
description	ALWAYS use when writing code importing "@libsql/client". Consult for debugging, best practices, or modifying @libsql/client, libsql/client, libsql client, libsql-client-ts, libsql client ts.
metadata	{"version":"0.17.4","generated_by":"Anthropic · Haiku 4.5","generated_at":"2026-06-15T00:00:00.000Z"}

tursodatabase/libsql-client-ts @libsql/client@0.17.4

Tags: next: 0.17.3-pre.2, latest: 0.17.4

References: package.json • README • Docs • Issues • Releases

Search

Use skilld search "query" -p @libsql/client instead of grepping .skilld/ directories. Run skilld search --guide -p @libsql/client for full syntax, filters, and operators.

API Changes

This section documents version-specific API changes — prioritize recent major/minor releases. Note: Local documentation covers v0.14.0; v0.17.4 release notes are unavailable locally.

• NEW: migrate() API — v0.10.0 added dedicated migration function for both schema and regular databases source

• NEW: execute(sql, args) overload — v0.8.0-pre.1 added overload to match other SQLite SDK patterns source

• NEW: Concurrency limit option — v0.7.0 added configurable concurrency limit for parallel queries (defaults to 20) to prevent socket hangup errors source

• NEW: syncInterval config option — v0.5.3 added periodic sync support for embedded replicas source

• NEW: encryptionKey config option — v0.5.0 added encryption at rest for local database files source

• NEW: encryptionCipher option — v0.5.1 added cipher selection, changed default to SQLCipher source

• BREAKING: batch() parameter order — v0.3.0 moved transaction mode to second parameter; v0.2.1 introduced TransactionMode argument source

• BREAKING: Default transaction mode — v0.3.0 changed default from "immediate" to "deferred"; v0.2.1 had previously changed it to "immediate" source

• BREAKING: ./hrana import removed — v0.2.0 removed ./hrana import path, added ./ws for WebSocket-only client source

• NEW: @libsql/client/web conditional export — v0.3.2 added conditional exports redirecting to web module on edge platforms source

• NEW: Config.fetch option — v0.3.2 (and refined in v0.3.1) added support for overriding fetch implementation source

• NEW: ResultSet.toJSON() method — v0.3.1 added JSON serialization support source

• NEW: intMode config field — v0.2.2 added choice between numbers, bigints, or strings for SQLite integers source

• BREAKING: Value type includes bigint — v0.2.0 changed Value type to support bigint for future integer handling source

• NEW: Interactive transactions over HTTP — v0.2.0 added support via hrana-client 0.4 source

• BREAKING: libsql: URL protocol changed — v0.2.0 switched from WebSockets to HTTP source

• NEW: ?tls=0 query parameter — v0.2.0 added option to disable TLS for local libsql: URLs source

• BREAKING: Node requirement — v0.6.0 bumped hrana client and now requires Node 18+ source

• NEW: @libsql/client/node explicit import — v0.3.2 added explicit Node.js-specific module export source

• NEW: Client.protocol property — v0.3.0 added property to identify which protocol the client uses source

Also changed: batch() schema change wait option v0.6.1 · embedded replica sync WAL path fix v0.8.1 · wasm transaction fix v0.8.0-pre.1 · cache=private|sharedparameter v0.8.0-pre.1 · hrana 0.5 Hrana 3 support v0.3.2 · libsql package replacement for better-sqlite3 v0.3.3 · Bun support v0.3.3 · Hrana 2 default v0.3.4 · column introspectionResultSet.columnTypes v0.3.5 · connection reuse optimization v0.3.5

Best Practices

• Use batch operations for multiple statements rather than individual execute() calls to ensure atomicity and simplify transaction handling — the backend commits all changes on success or rolls back entirely on any failure source

• Prefer batch transactions over interactive transactions for atomic operations — interactive transactions lock the database for writing (with a 5-second timeout) which can degrade performance on high-latency databases source

• Use transaction mode "read" for read-only workloads to enable parallel execution; use "write" for any writes (which cannot operate in parallel on replicas) source

• Paginate large result sets with LIMIT and OFFSET to avoid RESPONSE_TOO_LARGE errors — do not attempt to fetch millions of rows in a single query source

• Create a new client instance per application runtime (serverless function, server instance, etc.) rather than reusing a long-lived global client, which can cause stale connection issues and "invalid baton" errors source

• Configure the concurrency option to match your workload — defaults to 20 concurrent requests, which may need tuning for high-throughput or resource-constrained environments source

• Use @libsql/client/web subpath for edge runtime deployments (Cloudflare Workers, Vercel Edge, Deno Deploy), and use the main @libsql/client import for Node.js and server environments source

• For new projects requiring local-first sync with bidirectional changes, use @tursodatabase/sync instead of embedded replicas — it provides explicit push() / pull(), lower bandwidth, and better multi-writer convergence source

• Call client.sync() explicitly or configure syncInterval for periodic syncing with embedded replicas; never open the local database file externally during sync to avoid data corruption source

• Use Drizzle ORM with drizzle-orm/libsql as the primary ORM integration — it provides the best developer experience and is officially supported, whereas Prisma requires additional adapter setup source

• Store database credentials in Nuxt's runtimeConfig and access them via useRuntimeConfig() in server routes to keep secrets out of client-side code source

• Use named placeholders (:name, @name, or $name) instead of positional (?) placeholders in hand-written SQL to improve readability and reduce parameter order errors source

• Do not use interactive transactions for high-concurrency workloads — they serialize write access and timeout after 5 seconds, making them unsuitable for busy applications where batch() is preferable source

• For embedded replicas, ensure periodic sync runs in the background on application startup or at regular intervals (e.g., every 5 minutes) rather than on-demand in request handlers, to maintain consistency without blocking user requests source