Initial commit - move from sqld/

Author: psarna

.gitignore

@@ -0,0 +1,2 @@
+Cargo.lock
+target/

Cargo.toml

@@ -0,0 +1,44 @@
+[package]
+name = "libsql-client"
+version = "0.5.10"
+edition = "2021"
+license = "Apache-2.0"
+description = "HTTP-based client for libSQL and sqld"
+keywords = ["libsql", "sqld", "database", "driver", "http"]
+repository = "https://github.com/libsql/libsql-client-rs"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+url = "2.3.1"
+base64 = "0.21.0"
+num-traits = "0.2.15"
+serde_json = "1.0.91"
+worker = { version = "0.0.12", optional = true }
+anyhow = "1.0.69"
+async-trait = "0.1.64"
+reqwest = { version = "0.11.14", optional = true, default-features = false, features = ["rustls-tls"] }
+rusqlite = { version = "0.28.0", optional = true, default-features = false, features = [
+    "column_decltype"
+] }
+
+[features]
+default = ["local_backend", "reqwest_backend"]
+workers_backend = ["worker"]
+reqwest_backend = ["reqwest"]
+local_backend = ["rusqlite"]
+
+[dev-dependencies]
+tokio = { version = "1", features = ["full"] }
+libsql-client = { path = ".", features = ["reqwest_backend", "local_backend"] }
+rand = "0.8.5"
+
+[[example]]
+name = "select"
+path = "examples/select.rs"
+
+[[example]]
+name = "connect_from_env"
+path = "examples/connect_from_env.rs"
+
+[workspace]

README.md

@@ -0,0 +1,100 @@
+# Rust libSQL client library
+
+libSQL Rust client library can be used to communicate with [sqld](https://github.com/libsql/sqld/) natively over HTTP protocol with native Rust interface.
+
+At the moment the library works with the following backends:
+ - local
+ - reqwest
+ - Cloudflare Workers environment (optional)
+
+## Quickstart
+
+In order to use the database in your project, just call `libsql_client::connect()`:
+```rust
+    let db = libsql_client::connect()?;
+```
+
+The only thing you need to provide is an env variable with the database URL, e.g.
+```
+export LIBSQL_CLIENT_URL="file:////tmp/example.db"
+```
+for a local database stored in a file, or
+```
+export LIBSQL_CLIENT_URL="https://user:[email protected]"
+```
+for a remote database connection.
+
+You can also explicitly use a specific backend. Examples of that are covered in the next paragraphs.
+
+### Local
+
+In order to connect to the database, set up the URL to point to a local path:
+```
+export LIBSQL_CLIENT_URL = "/tmp/example.db"
+```
+
+`local_backend` feature is enabled by default, so add the dependency like this:
+```
+cargo add libsql-client
+```
+
+Example for how to connect to the database and perform a query:
+```rust
+    let db = libsql_client::local::Connection::connect_from_env()?;
+    let response = db
+        .execute("SELECT * FROM table WHERE key = 'key1'")
+        .await?;
+    (...)
+```
+
+
+### Reqwest
+In order to connect to the database, set up the following env variables:
+```
+export LIBSQL_CLIENT_URL = "https://your-db-url.example.com"
+export LIBSQL_CLIENT_USER = "me"
+export LIBSQL_CLIENT_PASS = "my-password"
+```
+... or just the URL, if it contains the required auth information:
+```
+export LIBSQL_CLIENT_URL = "https://user@pass:your-db-url.example.com"
+```
+
+`reqwest_backend` feature is enabled by default, so add the dependency like this:
+```
+cargo add libsql-client
+```
+
+Example for how to connect to the database and perform a query from a GET handler:
+```rust
+    let db = libsql_client::reqwest::Connection::connect_from_env()?;
+    let response = db
+        .execute("SELECT * FROM table WHERE key = 'key1'")
+        .await?;
+    (...)
+```
+
+### Cloudflare Workers
+
+In order to connect to the database, set up the following variables in `.dev.vars`, or register them as secrets:
+```
+LIBSQL_CLIENT_URL = "https://your-db-url.example.com"
+LIBSQL_CLIENT_USER = "me"
+LIBSQL_CLIENT_PASS = "my-password"
+```
+
+Add it as dependency with `workers_backend` backend enabled. Turn off default features, as they are not guaranteed to compile to `wasm32-unknown-unknown`,
+which is required in this environment:
+```
+cargo add libsql-client --no-default-features -F workers_backend
+```
+
+Example for how to connect to the database and perform a query from a GET handler:
+```rust
+router.get_async("/", |_, ctx| async move {
+    let db = libsql_client::workers::Connection::connect_from_ctx(&ctx)?;
+    let response = db
+        .execute("SELECT * FROM table WHERE key = 'key1'")
+        .await?;
+    (...)
+```

examples/connect_from_env.rs

@@ -0,0 +1,76 @@
+use anyhow::Result;
+use libsql_client::{connect, params, Connection, QueryResult, ResultSet, Statement};
+use rand::prelude::SliceRandom;
+
+fn result_to_string(query_result: QueryResult) -> Result<String> {
+    let mut ret = String::new();
+    let ResultSet { columns, rows } = query_result.into_result_set()?;
+    for column in &columns {
+        ret += &format!("| {column:16} |");
+    }
+    ret += "\n| -------------------------------------------------------- |\n";
+    for row in rows {
+        for column in &columns {
+            ret += &format!("| {:16} |", row.cells[column].to_string());
+        }
+        ret += "\n";
+    }
+    Ok(ret)
+}
+
+// Bumps a counter for one of the geographic locations picked at random.
+async fn bump_counter(db: impl Connection) -> Result<String> {
+    // Recreate the tables if they do not exist yet
+    db.batch([
+        "CREATE TABLE IF NOT EXISTS counter(country TEXT, city TEXT, value, PRIMARY KEY(country, city)) WITHOUT ROWID",
+        "CREATE TABLE IF NOT EXISTS coordinates(lat INT, long INT, airport TEXT, PRIMARY KEY (lat, long))"
+    ]).await?;
+
+    // For demo purposes, let's pick a pseudorandom location
+    const FAKE_LOCATIONS: &[(&str, &str, &str, f64, f64)] = &[
+        ("WAW", "PL", "Warsaw", 52.22959, 21.0067),
+        ("EWR", "US", "Newark", 42.99259, -81.3321),
+        ("HAM", "DE", "Hamburg", 50.118801, 7.684300),
+        ("HEL", "FI", "Helsinki", 60.3183, 24.9497),
+        ("NSW", "AU", "Sydney", -33.9500, 151.1819),
+    ];
+
+    let (airport, country, city, latitude, longitude) =
+        *FAKE_LOCATIONS.choose(&mut rand::thread_rng()).unwrap();
+
+    db.transaction([
+        Statement::with_params(
+            "INSERT OR IGNORE INTO counter VALUES (?, ?, 0)",
+            // Parameters that have a single type can be passed as a regular slice
+            &[country, city],
+        ),
+        Statement::with_params(
+            "UPDATE counter SET value = value + 1 WHERE country = ? AND city = ?",
+            &[country, city],
+        ),
+        Statement::with_params(
+            "INSERT OR IGNORE INTO coordinates VALUES (?, ?, ?)",
+            // Parameters with different types can be passed to a convenience macro - params!()
+            params!(latitude, longitude, airport),
+        ),
+    ])
+    .await?;
+
+    let counter_response = db.execute("SELECT * FROM counter").await?;
+    let scoreboard = result_to_string(counter_response)?;
+    let html = format!("Scoreboard:\n{scoreboard}");
+    Ok(html)
+}
+
+#[tokio::main]
+async fn main() {
+    let db = connect().unwrap();
+    let response = bump_counter(db)
+        .await
+        .unwrap_or_else(|e| format!("Error: {e}"));
+    println!(
+        "Connection parameters: backend={:?} url={:?}\n{response}",
+        std::env::var("LIBSQL_CLIENT_BACKEND"),
+        std::env::var("LIBSQL_CLIENT_URL")
+    );
+}

examples/select.rs

@@ -0,0 +1,84 @@
+use anyhow::Result;
+use libsql_client::{params, Connection, QueryResult, ResultSet, Statement};
+use rand::prelude::SliceRandom;
+
+fn result_to_string(query_result: QueryResult) -> Result<String> {
+    let mut ret = String::new();
+    let ResultSet { columns, rows } = query_result.into_result_set()?;
+    for column in &columns {
+        ret += &format!("| {column:16} |");
+    }
+    ret += "\n| -------------------------------------------------------- |\n";
+    for row in rows {
+        for column in &columns {
+            ret += &format!("| {:16} |", row.cells[column].to_string());
+        }
+        ret += "\n";
+    }
+    Ok(ret)
+}
+
+// Bumps a counter for one of the geographic locations picked at random.
+async fn bump_counter(db: impl Connection) -> Result<String> {
+    // Recreate the tables if they do not exist yet
+    db.batch([
+        "CREATE TABLE IF NOT EXISTS counter(country TEXT, city TEXT, value, PRIMARY KEY(country, city)) WITHOUT ROWID",
+        "CREATE TABLE IF NOT EXISTS coordinates(lat INT, long INT, airport TEXT, PRIMARY KEY (lat, long))"
+    ]).await?;
+
+    // For demo purposes, let's pick a pseudorandom location
+    const FAKE_LOCATIONS: &[(&str, &str, &str, f64, f64)] = &[
+        ("WAW", "PL", "Warsaw", 52.22959, 21.0067),
+        ("EWR", "US", "Newark", 42.99259, -81.3321),
+        ("HAM", "DE", "Hamburg", 50.118801, 7.684300),
+        ("HEL", "FI", "Helsinki", 60.3183, 24.9497),
+        ("NSW", "AU", "Sydney", -33.9500, 151.1819),
+    ];
+
+    let (airport, country, city, latitude, longitude) =
+        *FAKE_LOCATIONS.choose(&mut rand::thread_rng()).unwrap();
+
+    db.transaction([
+        Statement::with_params(
+            "INSERT OR IGNORE INTO counter VALUES (?, ?, 0)",
+            // Parameters that have a single type can be passed as a regular slice
+            &[country, city],
+        ),
+        Statement::with_params(
+            "UPDATE counter SET value = value + 1 WHERE country = ? AND city = ?",
+            &[country, city],
+        ),
+        Statement::with_params(
+            "INSERT OR IGNORE INTO coordinates VALUES (?, ?, ?)",
+            // Parameters with different types can be passed to a convenience macro - params!()
+            params!(latitude, longitude, airport),
+        ),
+    ])
+    .await?;
+
+    let counter_response = db.execute("SELECT * FROM counter").await?;
+    let scoreboard = result_to_string(counter_response)?;
+    let html = format!("Scoreboard:\n{scoreboard}");
+    Ok(html)
+}
+
+#[tokio::main]
+async fn main() {
+    match libsql_client::reqwest::Connection::connect_from_env() {
+        Ok(remote_db) => {
+            match bump_counter(remote_db).await {
+                Ok(response) => println!("Remote:\n{response}"),
+                Err(e) => println!("Remote database query failed: {e}"),
+            };
+        }
+        Err(e) => println!("Failed to fetch from a remote database: {e}"),
+    }
+
+    let mut path_buf = std::env::temp_dir();
+    path_buf.push("libsql_client_test_db.db");
+    let local_db = libsql_client::local::Connection::connect(path_buf.as_path()).unwrap();
+    match bump_counter(local_db).await {
+        Ok(response) => println!("Local:\n{response}"),
+        Err(e) => println!("Local database query failed: {e}"),
+    };
+}