Skip to content
ParticleDB
Release candidateParticleDB 1.1.19-rc.17 is not yet GA or ready for production data.Release status →

Rust

Use the configured address for your client. See connection addresses and 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).

The 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).

Terminal window
cargo add particledb-sdk

The example connects as app, with the password in PARTICLEDB_PASSWORD. Start the server with the local start command, 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.

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.

Use tokio-postgres over the SQL client interface (port 5432). The examples below use bind parameters, transactions and typed rows. The blocking postgres crate, sqlx, and Diesel use the same protocol.

[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.

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.