Skip to content

Latest commit

 

History

History
150 lines (107 loc) · 4.41 KB

README.md

File metadata and controls

150 lines (107 loc) · 4.41 KB
Raw

SQLx

🧰 The Rust SQL Toolkit


Built with ❤️ by The LaunchBadge team

SQLx is an async, pure Rust SQL crate featuring compile-time checked queries without a DSL.

  • Truly Asynchronous. Built from the ground-up using async/await for maximum concurrency.

  • Type-safe SQL (if you want it) without DSLs. Use the query!() macro to check your SQL and bind parameters at compile time. (You can still use dynamic SQL queries if you like.)

  • Pure Rust. The Postgres and MySQL/MariaDB drivers are written in pure Rust using zero unsafe code.

  • Runtime Agnostic. Works on async-std or tokio with the runtime-async-std or runtime-tokio cargo feature flag.

Install

async-std

# Cargo.toml
[dependencies]
sqlx = "0.2"

tokio

# Cargo.toml
[dependencies]
sqlx = { version = "0.2", default-features = false, features = [ "runtime-tokio", "macros" ] }

Cargo Feature Flags

  • runtime-async-std (on by default): Use the async-std runtime.

  • runtime-tokio: Use the tokio runtime. Mutually exclusive with the runtime-async-std feature.

  • postgres: Add support for the Postgres database server.

  • mysql: Add support for the MySQL (and MariaDB) database server.

  • uuid: Add support for UUID (in Postgres).

  • chrono: Add support for date and time types from chrono.

  • tls: Add support for TLS connections.

Examples

Connect

It is a very good idea to always create a connection pool at the beginning of your application and then share that.

// Postgres
let pool = sqlx::PgPool::new("postgres://localhost/database").await?;

Dynamic

The sqlx::query function provides general-purpose prepared statement execution. The result is an implementation of the Row trait. Values can be efficiently accessed by index or name.

let row = sqlx::query("SELECT is_active FROM users WHERE id = ?")
    .bind(some_user_id)
    .fetch_one(&mut conn)
    .await?;
    
let is_active: bool = row.get("is_active");

Static

The sqlx::query! macro prepares the SQL query and interprets the result in order to constrain input types and infer output types. The result of query! is an anonymous struct (or named tuple).

let countries = sqlx::query!(
        "SELECT country, COUNT(*) FROM users GROUP BY country WHERE organization = ?", 
        organization
    )
    .fetch(&mut conn) // -> impl Stream<Item = { country: String, count: i64 }>
    .map_ok(|rec| (rec.country, rec.count))
    .try_collect::<HashMap<_>>() // -> HashMap<String, i64>
    .await?;

See the beginnings of a RealWorld implementation in examples/realworld-postgres.

Safety

This crate uses #[forbid(unsafe_code)] to ensure everything is implemented in 100% Safe Rust.

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.