# Rust

Connect to ParticleDB from Rust, run parameterized queries, handle transactions and errors.

Source: https://particledb.ai/sdks/rust/

Use the configured address for your client. See [connection addresses](/installation/ports/) and [security](/guides/security/). The ParticleDB SDK examples use the database port, 7173; the other examples use the SQL client address.

Rust applications can use the ParticleDB SDK over the native client protocol (port 7173) or
tokio-postgres over the SQL client interface (port 5432).

## ParticleDB SDK

The [`particledb-sdk`](https://crates.io/crates/particledb-sdk) crate on crates.io, MIT licensed,
from version `0.2.0`; the current version is `0.2.1`. It requires Rust 1.87 or newer and
server `1.1.19-rc.13` or later. On
Linux, building its TLS dependency needs `pkg-config` and the OpenSSL development headers
(`libssl-dev` on Debian and Ubuntu).

```bash
cargo add particledb-sdk
```

The example connects as `app`, with the password in `PARTICLEDB_PASSWORD`. Start the server
with the [local start command](/getting-started/quickstart/#2-start-locally), replacing
`--no-auth` with `--auth-method scram-sha-256 --pg-username app --pg-password-file ./pdb-password`.
The password file holds only the password. The SDK connects to `localhost:7173` by default.

```rust
use particledb_sdk::{Config, ParticleDB, Value};

fn main() -> particledb_sdk::Result<()> {
    let db = ParticleDB::connect(Config {
        user: "app".into(),
        password: std::env::var("PARTICLEDB_PASSWORD").unwrap_or_default(),
        ..Config::default()
    })?;

    db.execute("CREATE TABLE notes (id BIGINT PRIMARY KEY, body TEXT)", &[])?;
    db.execute("INSERT INTO notes VALUES ($1, $2)",
        &[Value::Int64(1), Value::String("first".into())])?;

    db.transaction(|tx| {
        tx.execute("UPDATE notes SET body = $1 WHERE id = $2",
            &[Value::String("updated".into()), Value::Int64(1)])?;
        Ok(())
    })?;

    let row = db.query_one("SELECT body FROM notes WHERE id = $1", &[Value::Int64(1)])?;
    println!("{}", row.unwrap().get_by_name::<String>("body")?);

    db.kv().set("session:123", "active")?;
    println!("{:?}", db.kv().get("session:123")?);
    Ok(())
}
```

Output:

```
updated
Some("active")
```

Calls are blocking; share one client between threads. Returning `Err` from the transaction
closure rolls the transaction back.

## SQL client interface with tokio-postgres

Use [`tokio-postgres`](https://docs.rs/tokio-postgres/latest/tokio_postgres/) over the SQL client interface (port
5432). The examples below use bind parameters, transactions and typed rows. The
blocking [`postgres`](https://docs.rs/postgres/latest/postgres/) crate, [`sqlx`](https://docs.rs/sqlx/latest/sqlx/),
and [Diesel](https://diesel.rs/) use the same protocol.

### Install

```toml
[dependencies]
tokio = { version = "1", features = ["full"] }
tokio-postgres = "0.7"
```

The example connects as `postgres` with the password `secret`, for a server started with
`particledb start --auth-method scram-sha-256 --pg-password secret`. With the server's default
`--auth-method password`, connect over TLS (for example with `postgres-native-tls` or
`tokio-postgres-rustls`); see [TLS and authentication](/connectivity/tls/#authentication).

### Quick start

```rust
use tokio_postgres::NoTls;

#[tokio::main]
async fn main() -> Result<(), tokio_postgres::Error> {
    let (mut client, connection) = tokio_postgres::connect(
        "host=localhost port=5432 user=postgres password=secret dbname=particledb",
        NoTls,
    )
    .await?;
    tokio::spawn(async move {
        if let Err(e) = connection.await {
            eprintln!("connection error: {e}");
        }
    });

    client
        .batch_execute("CREATE TABLE users (id BIGINT PRIMARY KEY, name TEXT)")
        .await?;
    let n = client
        .execute("INSERT INTO users (id, name) VALUES ($1, $2)", &[&1i64, &"alice"])
        .await?;
    println!("inserted {n}");

    // Transaction: commit() makes it durable; dropping it without commit rolls back
    let tx = client.transaction().await?;
    tx.execute("INSERT INTO users (id, name) VALUES ($1, $2)", &[&2i64, &"bob"])
        .await?;
    tx.commit().await?;

    for row in client
        .query("SELECT id, name FROM users WHERE id >= $1 ORDER BY id", &[&1i64])
        .await?
    {
        let id: i64 = row.get("id");
        let name: &str = row.get("name");
        println!("{id} {name}");
    }
    Ok(())
}
```

Output:

```
inserted 1
1 alice
2 bob
```

The server infers parameter types from the statement: in `WHERE id >= $1` against a
`BIGINT` column it reports `$1` as `int8`, so an `i64` binds without `prepare_typed`.

Key-value operations and vector search are SQL functions and operators, so call them the same
way, for example `SELECT KV_GET($1)` or `ORDER BY embedding  '[0.1,0.2,0.3]' LIMIT 5`.
See [Vector Search](/sql/vector-search/).

## Next steps

- [SQL Reference](/sql/overview/). SQL syntax and examples
- [ORM compatibility](/connectivity/orm-compatibility/). Diesel, SQLx, and other ORMs
- [SQL client connections](/connectivity/pg-wire/). connection settings and compatibility
