Getting started
Your first program
This program builds an operator, writes a file, reads it back, inspects its metadata, and deletes it. It runs against the in-memory service with no credentials, so you can paste it into a fresh project and run it as-is.
# Cargo.toml
[dependencies]
opendal = "0.59"
tokio = { version = "1", features = ["full"] }
use opendal::Operator;
use opendal::Result;
use opendal::services;
#[tokio::main]
async fn main() -> Result<()> {
// Configure a service, then build an operator from it.
let op = Operator::new(services::Memory::default())?;
// The same verbs work on every service.
op.write("hello.txt", "Hello, World!").await?;
let bytes = op.read("hello.txt").await?;
println!("read {} bytes", bytes.len());
let meta = op.stat("hello.txt").await?;
println!("size = {} bytes", meta.content_length());
op.delete("hello.txt").await?;
Ok(())
}
Point it at a real backend
Only the service changes; the operations stay identical. To use S3, enable its feature and configure the builder:
opendal = { version = "0.59", features = ["services-s3"] }
use opendal::services;
use opendal::Operator;
let op = Operator::new(
services::S3::default()
.bucket("my-bucket")
.region("us-east-1"),
)?;
op.write("hello.txt", "Hello from S3!").await?;
Each service is gated behind its own services-* feature, so enable the ones
you use. The next page, Connecting to your storage, covers
the construction options and credentials in depth; Services lists
every backend and its configuration keys.
Blocking vs async
OpenDAL is async-first. Operator exposes async methods and needs an async
runtime (Tokio by default).
For synchronous code, enable the blocking feature and use
blocking::Operator. Build it from an async operator, then call the same verbs
without .await:
opendal = { version = "0.59", features = ["blocking"] }
use opendal::blocking;
use opendal::services;
use opendal::Operator;
// Enter a Tokio runtime; the blocking operator runs every call on it.
let runtime = tokio::runtime::Runtime::new()?;
let _guard = runtime.enter();
let op = Operator::new(services::Memory::default())?;
let bop = blocking::Operator::new(op)?;
bop.write("hello.txt", "Hello, World!")?;
let bytes = bop.read("hello.txt")?;
blocking::Operator::new captures the Tokio runtime that is current when it is
called and returns an error if there is none. Call the blocking operator from
synchronous code, not from inside an async task.