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).
ParticleDB SDK
Section titled “ParticleDB SDK”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).
cargo add particledb-sdkThe 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:
updatedSome("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
Section titled “SQL client interface with tokio-postgres”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.
Install
Section titled “Install”[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.
Quick start
Section titled “Quick start”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 11 alice2 bobThe 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.
Next steps
Section titled “Next steps”- SQL Reference. SQL syntax and examples
- ORM compatibility. Diesel, SQLx, and other ORMs
- SQL client connections. connection settings and compatibility
This site uses Google Analytics cookies to count visits. Privacy · License