async-graphql

async-graphql a high-performance graphql server library that's fully specification compliant

Book • 中文文档 • Docs • GitHub repository • Cargo package

This crate uses #![forbid(unsafe_code)] to ensure everything is implemented in 100% safe Rust.

Static schema

use std::error::Error;

use async_graphql::{http::GraphiQLSource, EmptyMutation, EmptySubscription, Object, Schema};
use async_graphql_poem::*;
use poem::{listener::TcpListener, web::Html, *};

struct Query;

#[Object]
impl Query {
    async fn howdy(&self) -> &'static str {
        "partner"
    }
}

#[handler]
async fn graphiql() -> impl IntoResponse {
    Html(GraphiQLSource::build().finish())
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    // create the schema
    let schema = Schema::build(Query, EmptyMutation, EmptySubscription).finish();

    // start the http server
    let app = Route::new().at("/", get(graphiql).post(GraphQL::new(schema)));
    println!("GraphiQL: http://localhost:8000");
    Server::new(TcpListener::bind("0.0.0.0:8000"))
        .run(app)
        .await?;
    Ok(())
}

Dynamic schema

Requires the dynamic-schema feature to be enabled.

use std::error::Error;

use async_graphql::{dynamic::*, http::GraphiQLSource};
use async_graphql_poem::*;
use poem::{listener::TcpListener, web::Html, *};

#[handler]
async fn graphiql() -> impl IntoResponse {
    Html(GraphiQLSource::build().finish())
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let query = Object::new("Query").field(Field::new(
        "howdy",
        TypeRef::named_nn(TypeRef::STRING),
        |_| FieldFuture::new(async { "partner" }),
    ));

    // create the schema
    let schema = Schema::build(query, None, None).register(query).finish()?;

    // start the http server
    let app = Route::new().at("/", get(graphiql).post(GraphQL::new(schema)));
    println!("GraphiQL: http://localhost:8000");
    Server::new(TcpListener::bind("0.0.0.0:8000"))
        .run(app)
        .await?;
    Ok(())
}

⚠️Security

I strongly recommend limiting the complexity and depth of queries in a production environment to avoid possible DDos attacks.

Features

Static and dynamic schemas are fully supported
Fully supports async/await
Type safety
Rustfmt friendly (Procedural Macro)
Custom scalars
Minimal overhead
Easy integration (poem, axum, actix-web, tide, warp, rocket ...)
Upload files (Multipart request)
Subscriptions (WebSocket transport)
Custom extensions
Error extensions
Limit query complexity/depth
Batch queries
Apollo Persisted Queries
Apollo Tracing extension
Apollo Federation(v2)

Note: Minimum supported Rust version: 1.86.0 or later

Examples

All examples are in the sub-repository, located in the examples directory.

git submodule update # update the examples repo
cd examples && cargo run --bin [name]

For more information, see the sub-repository README.md.

Integrations

Integrations are what glue async-graphql with your web server, here are provided ones, or you can build your own!

Crate features

This crate offers the following features. Most are not activated by default, except the integrations of GraphiQL (graphiql) and GraphQL Playground (playground):

feature	enables
`apollo_tracing`	Enable the Apollo tracing extension.
`apollo_persisted_queries`	Enable the Apollo persisted queries extension.
`boxed-trait`	Enables `async-trait` for all traits.
`bson`	Integrate with the `bson` crate.
`bigdecimal`	Integrate with the `bigdecimal` crate.
`cbor`	Support for serde_cbor.
`chrono`	Integrate with the `chrono` crate.
`chrono-tz`	Integrate with the `chrono-tz` crate.
`dataloader`	Support DataLoader.
`decimal`	Integrate with the `rust_decimal` crate.
`dynamic-schema`	Support dynamic schema
`fast_chemail`	Integrate with the `fast_chemail` crate.
`graphiql`	Enables the GraphiQL IDE integration
`hashbrown`	Integrate with the `hashbrown` crate.
`log`	Enable the Logger extension.
`opentelemetry`	Enable the OpenTelemetry extension.
`playground`	Enables the GraphQL playground IDE integration
`rawvalue`	Support raw values from `serde_json`
`secrecy`	Integrate with the `secrecy` crate.
`smol_str`	Integrate with the `smol_str` crate.
`string_number`	Enable the StringNumber.
`time`	Integrate with the `time` crate.
`tracing`	Enable the Tracing extension.
`tempfile`	Save the uploaded content in the temporary file.
`tokio-sync`	Integrate with the `tokio::sync::RwLock` and `tokio::sync::Mutex`.
`unblock`	Support Asynchronous reader for Upload
`uuid`	Integrate with the `uuid` crate.
`url`	Integrate with the `url` crate.

Observability

One of the tools used to monitor your graphql server in production is Apollo Studio. Apollo Studio is a cloud platform that helps you build, monitor, validate, and secure your organization's data graph. Add the extension crate async_graphql_apollo_studio_extension to make this available.

Who's using `async-graphql` in production?

Community Showcase

rust-actix-graphql-sqlx-postgresql Using GraphQL with Rust and Apollo Federation
entity-rs A simplistic framework based on TAO, Facebook's distributed database for Social Graph.
vimwiki-server Provides graphql server to inspect and manipulate vimwiki files.
Diana Diana is a GraphQL system for Rust that's designed to work as simply as possible out of the box, without sacrificing configuration ability.
cindythink
sudograph

Blog Posts

References

License

Licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT) at your option.