The libSQL JavaScript Client (`@libsql/client`) is a comprehensive TypeScript/JavaScript driver for interacting with libSQL databases, a fork of SQLite. It aims for API compatibility with `better-sqlite3`, offering both synchronous and opt-in promise-based APIs. This client supports Node.js, Bun, Deno, and web browsers, facilitating connections to in-memory, local file-based, and remote libSQL instances (including Turso databases). Key differentiators include support for embedded replicas (local SQLite files that sync with remote Turso databases for offline capabilities), remote access over HTTP/WebSockets, and advanced features like encryption at rest and AI/Vector Search integration when used with Turso. The current stable version is `0.5.29`, with active development towards a `0.6.x` release, which has introduced some breaking changes and new features. The npm package `libsql` is deprecated; users should install and import from `@libsql/client` instead.
npm install libsqlVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to connect to a remote libSQL (Turso) database, create a table, insert data using a batch operation, query data, and perform an update within a transaction, including a simulated rollback. It uses environment variables for secure credential management.
Change your `package.json` dependency from `"libsql": "^x.y.z"` to `"@libsql/client": "^x.y.z"` and update import paths accordingly, e.g., `import { createClient } from '@libsql/client';`.Upgrade `@libsql/client` to version `0.6.2` or higher to resolve database push and JSON parsing issues.
For maximum compatibility and to leverage libSQL's full feature set (especially for remote connections or embedded replicas), prefer using `createClient` and its async methods. Thoroughly test migration from `better-sqlite3` to ensure expected behavior.
Ensure `TURSO_DATABASE_URL` and `TURSO_AUTH_TOKEN` environment variables are correctly set and accessible in your deployment environment. For local `sqld` instances, add `?tls=0` to the URL if not using TLS. Use `libsql://` prefix for Turso URLs. Double-check URL format and token validity.
When deploying to serverless functions, Cloudflare Workers, or browsers, ensure you use `http(s):`, `ws(s):`, or `libsql:` URLs for remote connections. Avoid `file:` URLs in these environments.
Verify that `process.env.TURSO_DATABASE_URL` or the directly provided URL string is in the correct format (e.g., `libsql://your-db-slug-your-org.turso.io` or `file:./local.db`). Ensure environment variables are loaded (e.g., with `dotenv`).
Upgrade `@libsql/client` to version `0.6.2` or newer. This issue was a specific bug fixed in that release.
Always check if `selectResult.rows` exists and has elements before accessing `selectResult.rows[0]`. Operations like `client.execute('INSERT ...')` return `ResultSet` but `rows` array might be empty. Use `ResultSet.rowsAffected` for mutation operations. Consider `client.transaction` for complex read/write operations.Implement logic to prevent duplicate insertions, such as checking for existing records before inserting, or handling the error gracefully by providing user feedback. Ensure your application logic respects database constraints.