Skip to content
Get packs

Guide · Open source

How to use libSQL: build, run the shell and pick a driver

Updated · written with AI from the project's own documentation and checked against our catalogue data

libSQL is an open source fork of SQLite, maintained by Turso, that keeps SQLite compatibility and adds features such as embedded replicas and a server mode for remote access. This guide is for developers who already know SQLite and want to build libSQL from source, open its SQL shell, and understand which drivers and features it offers. By the end you will know what to install, how to build the project, and whether libSQL fits your project.

libSQLtursodatabase/libsql · ★ 17.3k · MIT

Quick start

  1. 1Check your fit. Confirm libSQL suits your project, since the README recommends Turso for new projects and notes the single-writer limit.
  2. 2Install the Rust toolchain. Install Rust so that the cargo command is available on your machine.
  3. 3Clone the repository. Download the tursodatabase/libsql source code to your computer.
  4. 4Build the library and tools. Run cargo xtask build from the project root to build the SQLite-compatible C library and tools.
  5. 5Open the SQL shell. Change into libsql-sqlite3 and run ./libsql, then use .open FILENAME for a saved database.
  6. 6Pick a driver. Choose an official driver for your language, such as Rust, JavaScript, or Go, from the README list.

Check whether libSQL is the right choice

libSQL is aimed at developers who already use SQLite and want extra features such as embedded replicas. It also suits teams that want a SQLite-based database reachable remotely through libsql-server, and projects that need a SQLite fork with open contribution rules.

The README says new projects should look at the separate Turso database project instead, because new features are going into Turso. libSQL also inherits SQLite's single-writer model, so it is not the choice if you need concurrent writes.

  • Good fit: existing SQLite users, remote access via libsql-server, open contribution needs
  • Not a fit: new projects (look at Turso), applications needing concurrent writes, non-developers wanting a ready-made app

Install prerequisites and build libSQL

The install method is clone-and-build. The only prerequisite named in the source is the Rust toolchain, which provides cargo. Once you have cloned the repository, run the build command from the project root.

The build produces the SQLite-compatible C library and tools.

  • Prerequisite: Rust toolchain (cargo)
cargo xtask build

Open the SQL shell

The README says to launch the libsql program from the libsql-sqlite3 directory. The shell starts on a transient in-memory database, so nothing is saved unless you open a file.

To use a persistent database, use the .open FILENAME command inside the shell. Type .help to see usage hints.

  • Run from the libsql-sqlite3 folder with ./libsql
  • Use .open FILENAME to switch to a persistent database
  • Use .help for usage hints
cd libsql-sqlite3 && ./libsql

Choose an interface and driver

libSQL provides two interfaces: the libSQL API, which supports all the features, and the SQLite C API for compatibility. If you want to write application code, pick an official driver for your language.

The README lists official drivers for TypeScript/JavaScript, Rust, and Go (with and without CGO). Python and C drivers are marked experimental.

  • Official: TypeScript / JS, Rust, Go, Go (no CGO)
  • Experimental: Python, C
  • Community: PHP, D, Ring

Use embedded replicas and the server mode

Embedded replicas let you keep a replicated database inside your app. libSQL server provides remote SQLite access, similar in purpose to PostgreSQL or MySQL.

The README also lists extensions to core SQLite, including an ALTER TABLE extension for modifying column types and constraints, randomized ROWID, WebAssembly user defined functions, and a virtual write-ahead log interface. The full description is in libsql-sqlite3/doc/libsql_extensions.md.

  • Embedded replicas: replicated database inside your app
  • libsql-server: remote access to SQLite
  • Extensions are documented in libsql-sqlite3/doc/libsql_extensions.md

Run libSQL in Docker

The README points to a separate Docker guide for running libSQL in a container. Follow the instructions in that guide rather than the build steps above.

What people use it for

  • Adding embedded replicas so a replicated database lives inside your application
  • Running a SQLite-compatible database that clients reach remotely through libsql-server
  • Experimenting with the SQL shell on a temporary in-memory database or a saved file
  • Using the Rust, JavaScript, or Go drivers to connect application code to libSQL

Frequently asked questions

Is libSQL free and open source?

Yes. The repository is licensed under the MIT License and the README describes libSQL as an open source, open contribution fork of SQLite. Check the LICENSE.md file in the repository for the full terms.

What do I need to install libSQL?

The source names the Rust toolchain (cargo) as the prerequisite. Clone the repository and run cargo xtask build to build the SQLite-compatible C library and tools.

Is libSQL a replacement for SQLite?

libSQL is a fork of SQLite that keeps SQLite compatibility and adds features such as embedded replicas and libsql-server. The README says it inherits SQLite's single-writer model.

Should I use libSQL or Turso for a new project?

The README says that if you are starting a new project, you should look at Turso, because libSQL is actively maintained but new features are being developed in Turso.

Does libSQL support concurrent writes?

The README says libSQL inherits SQLite's single-writer model, so it does not offer concurrent writes. The README says Turso is the project that goes beyond this.

How does libSQL compare to PostgreSQL or DuckDB?

The README describes libSQL as a SQLite fork with a libsql-server mode for remote access, similar in purpose to PostgreSQL or MySQL. It does not compare performance, so check each project's documentation for workload fit.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

libSQL suits developers who already use SQLite and want embedded replicas, remote access through libsql-server, or a SQLite fork with open contribution rules. If you are starting a new project or need concurrent writes, the README points you to Turso instead.

Install options & downloads