diff --git a/bindings/rust/README.md b/bindings/rust/README.md new file mode 100644 index 000000000..a8c1ce4c4 --- /dev/null +++ b/bindings/rust/README.md @@ -0,0 +1,158 @@ +# turso + +The next evolution of SQLite: A high-performance, SQLite-compatible database library for Rust + +## Features + +- **SQLite Compatible**: Drop-in replacement for rusqlite with familiar API +- **High Performance**: Built with Rust for maximum speed and efficiency +- **Async/Await Support**: Native async operations with tokio support +- **In-Process**: No network overhead, runs directly in your application +- **Cross-Platform**: Supports Linux, macOS, and Windows +- **Transaction Support**: Full ACID transactions with rollback support +- **Prepared Statements**: Optimized query execution with parameter binding + +## Installation + +Add this to your `Cargo.toml`: + +```toml +[dependencies] +turso = "0.1" +tokio = { version = "1.0", features = ["full"] } +``` + +## Quick Start + +### In-Memory Database + +```rust +use turso::Builder; + +#[tokio::main] +async fn main() -> turso::Result<()> { + // Create an in-memory database + let db = Builder::new_local(":memory:").build().await?; + let conn = db.connect()?; + + // Create a table + conn.execute( + "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)", + () + ).await?; + + // Insert data + conn.execute( + "INSERT INTO users (name, email) VALUES (?1, ?2)", + ["Alice", "alice@example.com"] + ).await?; + + conn.execute( + "INSERT INTO users (name, email) VALUES (?1, ?2)", + ["Bob", "bob@example.com"] + ).await?; + + // Query data + let mut rows = conn.query("SELECT * FROM users", ()).await?; + + while let Some(row) = rows.try_next().await? { + let id = row.get_value(0)?; + let name = row.get_value(1)?; + let email = row.get_value(2)?; + println!("User: {} - {} ({})", + id.as_integer().unwrap_or(&0), + name.as_text().unwrap_or(&"".to_string()), + email.as_text().unwrap_or(&"".to_string()) + ); + } + + Ok(()) +} +``` + +### File-Based Database + +```rust +use turso::Builder; + +#[tokio::main] +async fn main() -> turso::Result<()> { + // Create or open a database file + let db = Builder::new_local("my-database.db").build().await?; + let conn = db.connect()?; + + // Create a table + conn.execute( + r#"CREATE TABLE IF NOT EXISTS posts ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + title TEXT NOT NULL, + content TEXT, + created_at DATETIME DEFAULT CURRENT_TIMESTAMP + )"#, + () + ).await?; + + // Insert a post + let rows_affected = conn.execute( + "INSERT INTO posts (title, content) VALUES (?1, ?2)", + ["Hello World", "This is my first blog post!"] + ).await?; + + println!("Inserted {} rows", rows_affected); + + Ok(()) +} +``` + +## API Reference + +### Builder + +Create a new database: + +```rust +let db = Builder::new_local(":memory:").build().await?; +let db = Builder::new_local("data.db").build().await?; +``` + +### Connection + +Execute queries and statements: + +```rust +// Execute SQL directly +let rows_affected = conn.execute("INSERT INTO users (name) VALUES (?1)", ["Alice"]).await?; + +// Query for multiple rows +let mut rows = conn.query("SELECT * FROM users WHERE age > ?1", [18]).await?; + +// Prepare statements for reuse +let mut stmt = conn.prepare("SELECT * FROM users WHERE id = ?1").await?; +let mut rows = stmt.query([42]).await?; + +// Execute prepared statements +let rows_affected = stmt.execute(["Alice"]).await?; +``` + +### Working with Results + +```rust +use futures_util::TryStreamExt; + +let mut rows = conn.query("SELECT name, email FROM users", ()).await?; + +while let Some(row) = rows.try_next().await? { + let name = row.get_value(0)?.as_text().unwrap_or(&"".to_string()); + let email = row.get_value(1)?.as_text().unwrap_or(&"".to_string()); + println!("{}: {}", name, email); +} +``` + +## License + +MIT + +## Support + +- [GitHub Issues](https://github.com/tursodatabase/turso/issues) +- [Discord Community](https://discord.gg/turso)