Merge pull request #197 from penberg/docs

libsql: Improve documentation

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

crates/bindings/js/README.md

@@ -1,4 +1,4 @@
-# LibSQL JavaScript bindings
+# libSQL API for JavaScript
 
 ## Developing
 

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, '[email protected]')")
+```
+
+#### 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
+```

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 ('[email protected]')").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 ('[email protected]')", ()).unwrap();
+```
+
+#### Querying rows from a table
+
+```rust
+let rows = conn.execute("SELECT * FROM users WHERE email = ?", params!["[email protected]"]).unwrap().unwrap();
+let row = rows.next().unwrap().unwrap();
+// prints "[email protected]"
+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
 ```

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.
 //!