libsql/README.md

libSQL

libSQL is an open source, open contribution fork of SQLite, created and maintained by Turso.

libSQL Docs · libSQL Manifesto · Turso · Turso Docs · Discord · Blog & Tutorials

---

Documentation

We aim to evolve it to suit many more use cases than SQLite was originally designed for, and plan to use third-party OSS code wherever it makes sense.

libSQL has many great features, including:

• Embedded replicas that allow you to have replicated database inside your app.
• libSQL server for remote SQLite access, similar to PostgreSQL or MySQL
• Supports Rust, JavaScript, Python, Go, and more.

There are also various improvements and extensions to the core SQLite:

• ALTER TABLE extension for modifying column types and constraints
• Randomized ROWID
• WebAssembly User Defined Functions
• Pass down SQL string to virtual table implementation
• Virtual write-ahead log interface

The comprehensive description can be found here

Official Drivers

• TypeScript / JS
• Rust
• Go
• Go (no CGO)

Experimental Drivers

• Python (experimental)
• C (experimental)

Community Drivers

• PHP
• D (experimental, based on the C driver)

GUI Support

• Beekeeper Studio — macOS, Windows, and Linux
• Outerbase — Runs in the browser
• TablePlus — macOS, Windows, and Linux
• Dataflare — Paid (with limited free version) macOS, Windows, and Linux
• libSQL Studio - Runs in the browser

Getting Started

The project provides two interfaces: the libSQL API, which supports all the features, and the SQLite C API for compatibility.

To build the SQLite-compatible C library and tools, run:

cargo xtask build

To run the SQL shell, launch the libsql program:

$ cd libsql-sqlite3 && ./libsql
libSQL version 0.2.1 (based on SQLite version 3.43.0) 2023-05-23 11:47:56
Enter ".help" for usage hints.
Connected to a transient in-memory database.
Use ".open FILENAME" to reopen on a persistent database.
libsql>

Docker

To run libSQL using docker, refer to the Docker Docs

Why a fork?

SQLite has solidified its place in modern technology stacks, embedded in nearly any computing device you can think of. Its open source nature and public domain availability make it a popular choice for modification to meet specific use cases.

But despite having its code available, SQLite famously doesn't accept external contributors and doesn't adhere to a code of conduct. So community improvements cannot be widely enjoyed.

There have been other forks in the past, but they all focus on a specific technical difference. We aim to be a community where people can contribute from many different angles and motivations.

We want to see a world where everyone can benefit from all of the great ideas and hard work that the SQLite community contributes back to the codebase. Community contributions work well, because we’ve done it before. If this was possible, what do you think SQLite could become?

You can read more about our goals and motivation in our product vision.

Compatibility with SQLite

Compatibility with SQLite is of great importance for us. But it can mean many things. So here's our stance:

• The file format: libSQL will always be able to ingest and write the SQLite file format. We would love to add extensions like encryption, and CRC that require the file to be changed. But we commit to always doing so in a way that generates standard sqlite files if those features are not used.
• The API: libSQL will keep 100% compatibility with the SQLite API, but we may add additional APIs.
• Embedded: SQLite is an embedded database that can be consumed as a single .c file with its accompanying header. libSQL will always be embeddable, meaning it runs inside your process without needing a network connection. But we may change the distribution, so that object files are generated, instead of a single .c file.

License

libSQL is licensed under an Open Source License, and we adhere to a clear Code of Conduct.