gensparkにて、まとめたもの。
SurrealDB Rust SDK 最新版の使い方（2025年7月現在）
1. Cargo.toml の設定
[dependencies]
surrealdb = "2.3.7" # 最新版
tokio = { version = "1.0", features = ["macros", "rt-multi-thread"] }
serde = { version = "1.0", features = ["derive"] }
2. 基本的な接続とCRUD操作
use surrealdb::engine::remote::ws::Ws;
use surrealdb::opt::auth::Root;
use surrealdb::{Surreal, RecordId};
use serde::{Deserialize, Serialize};
#[derive(Serialize, Deserialize, Debug)]
struct Person {
#[serde(skip_serializing_if = "Option::is_none")]
id: Option<RecordId>,
name: String,
age: u8,
}
#[tokio::main]
async fn main() -> surrealdb::Result<()> {
// SurrealDBサーバーに接続
let db = Surreal::new::<Ws>("localhost:8000").await?;
// rootユーザーでサインイン
db.signin(Root {
username: "root",
password: "root",
}).await?;
// 名前空間とデータベースを選択
db.use_ns("test").use_db("test").await?;
// CREATE - レコード作成（ランダムID）
let person: Option<Person> = db
.create("person")
.content(Person {
id: None,
name: "田中太郎".to_string(),
age: 30,
})
.await?;
println!("Created: {:?}", person);
// CREATE - 特定IDでレコード作成
let person_with_id: Option<Person> = db
.create(("person", "tanaka"))
.content(Person {
id: None,
name: "田中花子".to_string(),
age: 28,
})
.await?;
println!("Created with ID: {:?}", person_with_id);
// READ - 全レコード取得
let people: Vec<Person> = db.select("person").await?;
println!("All people: {:?}", people);
// READ - 特定IDのレコード取得
let specific_person: Option<Person> = db.select(("person", "tanaka")).await?;
println!("Specific person: {:?}", specific_person);
// UPDATE - レコード更新
let updated: Option<Person> = db
.update(("person", "tanaka"))
.merge(serde_json::json!({"age": 29}))
.await?;
println!("Updated: {:?}", updated);
// DELETE - レコード削除
let deleted: Option<Person> = db.delete(("person", "tanaka")).await?;
println!("Deleted: {:?}", deleted);
Ok(())
}
3. クエリの使用例
use surrealdb::{Surreal, Value};
#[tokio::main]
async fn main() -> surrealdb::Result<()> {
let db = Surreal::new::<Ws>("localhost:8000").await?;
db.signin(Root {
username: "root",
password: "root",
}).await?;
db.use_ns("test").use_db("test").await?;
// 複数のクエリを実行
let mut response = db.query("
CREATE person:john SET name = 'John', age = 25;
CREATE person:jane SET name = 'Jane', age = 30;
SELECT * FROM person WHERE age > 20;
").await?;
// 結果をインデックスで取得
let created_john: Option<Person> = response.take(0)?;
let created_jane: Option<Person> = response.take(1)?;
let filtered_people: Vec<Person> = response.take(2)?;
println!("John: {:?}", created_john);
println!("Jane: {:?}", created_jane);
println!("Filtered: {:?}", filtered_people);
Ok(())
}
4. パラメータ付きクエリ
#[tokio::main]
async fn main() -> surrealdb::Result<()> {
let db = Surreal::new::<Ws>("localhost:8000").await?;
db.signin(Root {
username: "root",
password: "root",
}).await?;
db.use_ns("test").use_db("test").await?;
// パラメータを使用したクエリ
let mut result = db
.query("SELECT * FROM person WHERE age > $min_age")
.bind(("min_age", 25))
.await?;
let people: Vec<Person> = result.take(0)?;
println!("People over 25: {:?}", people);
Ok(())
}
5. type::thing() の使い方
type::thing() は動的にRecordIDを作成する場合に使用します：
#[tokio::main]
async fn main() -> surrealdb::Result<()> {
let db = Surreal::new::<Ws>("localhost:8000").await?;
db.signin(Root {
username: "root",
password: "root",
}).await?;
db.use_ns("test").use_db("test").await?;
// type::thing()を使用してレコードID作成
let user_id = "user123";
let mut result = db
.query("CREATE type::thing('person', $id) SET name = $name, age = $age")
.bind(("id", user_id))
.bind(("name", "山田太郎"))
.bind(("age", 35))
.await?;
let created: Option<Person> = result.take(0)?;
println!("Created with thing: {:?}", created);
// 配列ベースのRecordID（効率的な範囲クエリ用）
let timestamp = "2025-07-22T10:00:00Z";
let mut result = db
.query("CREATE weather:[$location, $time] SET temperature = $temp")
.bind(("location", "Tokyo"))
.bind(("time", timestamp))
.bind(("temp", 25.5))
.await?;
Ok(())
}
6. 静的シングルトンパターン（推奨）
use std::sync::LazyLock;
use surrealdb::engine::remote::ws::{Client, Ws};
use surrealdb::opt::auth::Root;
use surrealdb::Surreal;
// グローバルなDB接続
static DB: LazyLock<Surreal<Client>> = LazyLock::new(Surreal::init);
async fn init_database() -> surrealdb::Result<()> {
DB.connect::<Ws>("localhost:8000").await?;
DB.signin(Root {
username: "root",
password: "root",
}).await?;
DB.use_ns("test").use_db("test").await?;
Ok(())
}
// どこからでも使える関数
async fn create_person(name: &str, age: u8) -> surrealdb::Result<Option<Person>> {
DB.create("person")
.content(Person {
id: None,
name: name.to_string(),
age,
})
.await
}
#[tokio::main]
async fn main() -> surrealdb::Result<()> {
// 初期化
init_database().await?;
// 使用例
let person = create_person("佐藤花子", 27).await?;
println!("Created: {:?}", person);
Ok(())
}
7. SurrealDBサーバーの起動
まずSurrealDBサーバーを起動する必要があります：
# インメモリサーバー起動
surreal start --user root --pass root
# または特定ポートで
surreal start --user root --pass root --bind 127.0.0.1:8000
thingを使う判断基準
使う場合：
- パラメータから動的にRecordIDを生成する
- 配列やオブジェクトベースの複雑なID構造が必要
- 効率的な範囲クエリが必要
使わない場合：
- シンプルな文字列や数値のID
- ランダムIDで十分
- 基本的なCRUD操作のみ
これらのコードは全てコピペして動作します。SurrealDB v2.3.7の最新機能を活用した実用的な例です。
