diff --git a/crates/README.md b/crates/README.md index 124e00581d..5a54eef7dd 100644 --- a/crates/README.md +++ b/crates/README.md @@ -1,48 +1,36 @@ -# LibSQL API +# libSQL API -LibSQL is an embeddable SQL database engine based on SQLite. +[![Twitter badge][]][Twitter URL] [![Discord badge][]][Discord URL] -The libSQL API a batteries-included wrapper around the SQLite C API to support transparent replication while retaining compatibility with the SQLite ecosystem, such as the SQL dialect and extensions. +_libSQL is an embeddable SQL database engine based on SQLite._ -## Getting Started - -The libSQL API supports the following programming languages: - -* ✅ [Rust](core) -* ✅ [Python](bindings/python) -* 👷 [JavaScript](bindings/js) -* 👷 [Go](bindings/go) -* 👷 [C](bindings/c) +This libSQL API is an experimental, batteries-included library built on top of SQLite to support replication while retaining compatibility with the SQLite ecosystem, such as the SQL dialect and extensions. -## Developing +## Features -Setting up the environment: +* **Embedded replicas** that allow you to have replicated database inside your app. +* Supports **Rust**, **JavaScript**, **Python**, **Go**, and more. -```sh -export LIBSQL_STATIC_LIB_DIR=$(pwd)/../.libs -``` - -Building the APIs: - -```sh -cargo build -``` +## Getting Started -Running the tests: +* [Rust](core) +* [Python](bindings/python) +* [JavaScript](bindings/js) (wip) +* [Go](bindings/go) (wip) +* [C](bindings/c) (wip) -```sh -cargo test -``` +## License -Running the benchmarks: +This project is licensed under the [MIT license]. -```sh -cargo test -``` +### Contribution -Run benchmarks and generate flamegraphs: +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in libSQL by you, shall be licensed as MIT, without any additional +terms or conditions. -```console -echo -1 | sudo tee /proc/sys/kernel/perf_event_paranoid -cargo bench --bench benchmark -- --profile-time=5 -``` +[Twitter badge]: https://img.shields.io/twitter/follow/libsqlhq.svg?style=social&label=Follow +[Twitter URL]: https://twitter.com/intent/follow?screen_name=libsqlhq +[Discord badge]: https://img.shields.io/discord/1026540227218640906?color=5865F2&label=discord&logo=discord&logoColor=8a9095 +[Discord URL]: https://discord.gg/TxwbQTWHSr +[MIT license]: https://github.com/libsql/libsql/blob/main/LICENSE.md diff --git a/crates/bindings/js/README.md b/crates/bindings/js/README.md index 4b530a4894..86b645ab8a 100644 --- a/crates/bindings/js/README.md +++ b/crates/bindings/js/README.md @@ -1,4 +1,4 @@ -# LibSQL JavaScript bindings +# libSQL API for JavaScript ## Developing diff --git a/crates/bindings/python/README.md b/crates/bindings/python/README.md index a8e885ec5e..433218d62a 100644 --- a/crates/bindings/python/README.md +++ b/crates/bindings/python/README.md @@ -1,10 +1,39 @@ -# LibSQL Python bindings +# libSQL API for Python + +## Getting Started + +#### Connecting to a database + +```python +import libsql + +con = libsql.connect("hello.db") +cur = con.cursor() +``` + +#### Creating a table + +```python +cur.execute("CREATE TABLE users (id INTEGER, email TEXT);") +``` + +#### Inserting rows into a table + +```python +cur.execute("INSERT INTO users VALUES (1, 'alice@example.org')") +``` + +#### Querying rows from a table + +```python +print(cur.execute("SELECT * FROM users").fetchone()) +``` ## Developing Setup the development environment: -``` +```sh python3 -m venv .env source .env/bin/activate pip3 install maturin pyperf pytest @@ -18,6 +47,18 @@ maturin develop && python3 example.py Run the tests: -``` +```sh pytest ``` + +Run the libSQL benchmarks: + +```sh +python3 perf-libsql.py +``` + +Run the SQLite benchmarks for comparison: + +```sh +python3 perf-sqlite3.py +``` diff --git a/crates/core/README.md b/crates/core/README.md index 1b3beed480..aa96f14c77 100644 --- a/crates/core/README.md +++ b/crates/core/README.md @@ -1,18 +1,67 @@ -# LibSQL API for Rust - -LibSQL is an embeddable SQL database engine based on SQLite. -This Rust API is a batteries-included wrapper around the SQLite C API to support transparent replication while retaining compatibility with the SQLite ecosystem, such as the SQL dialect and extensions. If you are building an application in Rust, this is the crate you should use. -There are also libSQL language bindings of this Rust crate to other languages such as [JavaScript](../bindings/js), [Python](../bindings/python), [Go](../bindings/go), and [C](../bindings/c). +# libSQL API for Rust ## Getting Started -To get started, you first need to create a [`Database`] object and then open a [`Connection`] to it, which you use to query: +#### Connecting to a database ```rust use libsql_core::Database; -let db = Database::open(":memory:"); +let db = Database::open("hello.db"); + let conn = db.connect().unwrap(); -conn.execute("CREATE TABLE IF NOT EXISTS users (email TEXT)") .unwrap(); -conn.execute("INSERT INTO users (email) VALUES ('alice@example.org')").unwrap(); +``` + +#### Creating a table + +```rust +conn.execute("CREATE TABLE IF NOT EXISTS users (email TEXT)", ()).unwrap(); +``` + +#### Inserting rows into a table + +```rust +conn.execute("INSERT INTO users (email) VALUES ('alice@example.org')", ()).unwrap(); +``` + +#### Querying rows from a table + +```rust +let rows = conn.execute("SELECT * FROM users WHERE email = ?", params!["alice@example.org"]).unwrap().unwrap(); +let row = rows.next().unwrap().unwrap(); +// prints "alice@example.org" +println!("{}", row.get::<&str>(0).unwrap()); +``` + +## Developing + +Setting up the environment: + +```sh +export LIBSQL_STATIC_LIB_DIR=$(pwd)/../../.libs +``` + +Building the APIs: + +```sh +cargo build +``` + +Running the tests: + +```sh +cargo test +``` + +Running the benchmarks: + +```sh +cargo bench +``` + +Run benchmarks and generate flamegraphs: + +```console +echo -1 | sudo tee /proc/sys/kernel/perf_event_paranoid +cargo bench --bench benchmark -- --profile-time=5 ``` diff --git a/crates/core/src/lib.rs b/crates/core/src/lib.rs index b9f34e2aab..f15ca70d8d 100644 --- a/crates/core/src/lib.rs +++ b/crates/core/src/lib.rs @@ -1,6 +1,6 @@ -//! # LibSQL API for Rust +//! # libSQL API for Rust //! -//! LibSQL is an embeddable SQL database engine based on SQLite. +//! libSQL is an embeddable SQL database engine based on SQLite. //! This Rust API is a batteries-included wrapper around the SQLite C API to support transparent replication while retaining compatibility with the SQLite ecosystem, such as the SQL dialect and extensions. If you are building an application in Rust, this is the crate you should use. //! There are also libSQL language bindings of this Rust crate to other languages such as [JavaScript](), Python, Go, and C. //!