Skip to main content

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.